From 904f141366533d00e059b6c455516856d006a3a4 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Thu, 5 Mar 2026 19:37:33 -0500 Subject: [PATCH 1/8] fix(highlight): replace hardcoded theme-specific color fallbacks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Problem: fallback hex values for `Normal.bg`, `DiffAdd.bg`, etc. in `compute_highlight_groups` were hardcoded to catppuccin mocha colors (`0x1e1e2e`, `0x2e4a3a`, `0x4a2e3a`, etc.), producing visibly wrong highlight groups for users on any other colorscheme when `Normal` has no background (transparent terminals or early startup). Solution: replace all hardcoded fallbacks with `vim.o.background`-aware neutral values — dark mode gets near-black/grey, light mode gets near-white/dark-grey — so the fallback path is theme-agnostic. --- lua/diffs/init.lua | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/lua/diffs/init.lua b/lua/diffs/init.lua index 77f521a..a176d80 100644 --- a/lua/diffs/init.lua +++ b/lua/diffs/init.lua @@ -470,11 +470,12 @@ local function compute_highlight_groups() local diff_added = resolve_hl('diffAdded') local diff_removed = resolve_hl('diffRemoved') - local bg = normal.bg or 0x1e1e2e - local add_bg = diff_add.bg or 0x2e4a3a - local del_bg = diff_delete.bg or 0x4a2e3a - local add_fg = diff_added.fg or diff_add.fg or 0x80c080 - local del_fg = diff_removed.fg or diff_delete.fg or 0xc08080 + local dark = vim.o.background ~= 'light' + local bg = normal.bg or (dark and 0x1a1a1a or 0xf0f0f0) + local add_bg = diff_add.bg or (dark and 0x1a3a1a or 0xd0ffd0) + local del_bg = diff_delete.bg or (dark and 0x3a1a1a or 0xffd0d0) + local add_fg = diff_added.fg or diff_add.fg or (dark and 0x80d080 or 0x206020) + local del_fg = diff_removed.fg or diff_delete.fg or (dark and 0xd08080 or 0x802020) local blended_add = blend_color(add_bg, bg, 0.4) local blended_del = blend_color(del_bg, bg, 0.4) @@ -483,7 +484,7 @@ local function compute_highlight_groups() local blended_add_text = blend_color(add_fg, bg, alpha) local blended_del_text = blend_color(del_fg, bg, alpha) - vim.api.nvim_set_hl(0, 'DiffsClear', { default = true, fg = normal.fg or 0xc0c0c0, bg = bg }) + vim.api.nvim_set_hl(0, 'DiffsClear', { default = true, fg = normal.fg or (dark and 0xcccccc or 0x333333), bg = bg }) vim.api.nvim_set_hl(0, 'DiffsAdd', { default = true, bg = blended_add }) vim.api.nvim_set_hl(0, 'DiffsDelete', { default = true, bg = blended_del }) vim.api.nvim_set_hl(0, 'DiffsAddNr', { default = true, fg = blended_add_text, bg = blended_add }) From d1f7acde8ef5d7304f58b22172eebb75cef6aeec Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Thu, 5 Mar 2026 19:40:48 -0500 Subject: [PATCH 2/8] fix(highlight): retry highlight computation when Normal has no background MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Problem: if `Normal.bg` is nil when `compute_highlight_groups` first runs (colorscheme not yet loaded), the neutral fallbacks are baked in and never corrected — the `ColorScheme` autocmd only fires for explicit `:colorscheme` calls, which may come too late for some plugin manager configurations. Solution: when `Normal.bg` is absent, schedule a single deferred retry via `vim.schedule` that recomputes all highlight groups and invalidates attached buffer caches once the event loop settles. Also document the load-order requirement and the retry behaviour in the highlight groups section of the vimdoc. --- doc/diffs.nvim.txt | 7 +++++++ lua/diffs/init.lua | 12 ++++++++++++ 2 files changed, 19 insertions(+) diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt index cfcd1b6..79f34b7 100644 --- a/doc/diffs.nvim.txt +++ b/doc/diffs.nvim.txt @@ -758,6 +758,13 @@ character-level groups blend at 60% for more contrast. Line-number groups combine both: background from the line-level blend, foreground from the character-level blend. +Note: highlight groups are computed when the first diff buffer is attached, +so your colorscheme must be loaded before any diff buffer opens. If `Normal` +has no background at that point (colorscheme loaded too late, or transparent +terminal), diffs.nvim schedules one deferred retry via |vim.schedule()| to +recompute once the event loop settles. To avoid relying on this, ensure your +colorscheme plugin has `priority = 1000` and `lazy = false`. + Fugitive unified diff highlights: ~ *DiffsAdd* DiffsAdd Background for `+` lines. Derived by blending diff --git a/lua/diffs/init.lua b/lua/diffs/init.lua index a176d80..a68b7ee 100644 --- a/lua/diffs/init.lua +++ b/lua/diffs/init.lua @@ -162,6 +162,7 @@ local default_config = { local config = vim.deepcopy(default_config) local initialized = false +local hl_retry_pending = false ---@diagnostic disable-next-line: missing-fields local fast_hl_opts = {} ---@type diffs.HunkOpts @@ -477,6 +478,17 @@ local function compute_highlight_groups() local add_fg = diff_added.fg or diff_add.fg or (dark and 0x80d080 or 0x206020) local del_fg = diff_removed.fg or diff_delete.fg or (dark and 0xd08080 or 0x802020) + if not normal.bg and not hl_retry_pending then + hl_retry_pending = true + vim.schedule(function() + hl_retry_pending = false + compute_highlight_groups() + for bufnr, _ in pairs(attached_buffers) do + invalidate_cache(bufnr) + end + end) + end + local blended_add = blend_color(add_bg, bg, 0.4) local blended_del = blend_color(del_bg, bg, 0.4) From 3e659eb6ab0a191b35dd16b880f913c0df6ca988 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Thu, 5 Mar 2026 19:42:54 -0500 Subject: [PATCH 3/8] docs: move colorscheme load-order note to setup section --- doc/diffs.nvim.txt | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt index 79f34b7..77ddee6 100644 --- a/doc/diffs.nvim.txt +++ b/doc/diffs.nvim.txt @@ -65,6 +65,10 @@ Install with lazy.nvim: >lua The plugin works automatically with no configuration required. For customization, see |diffs-config|. +Note: highlight groups are derived from `Normal` when the first diff buffer +opens. Your colorscheme must be loaded by then. With lazy.nvim, ensure it +has `priority = 1000` and `lazy = false`. + ============================================================================== CONFIGURATION *diffs-config* @@ -758,12 +762,6 @@ character-level groups blend at 60% for more contrast. Line-number groups combine both: background from the line-level blend, foreground from the character-level blend. -Note: highlight groups are computed when the first diff buffer is attached, -so your colorscheme must be loaded before any diff buffer opens. If `Normal` -has no background at that point (colorscheme loaded too late, or transparent -terminal), diffs.nvim schedules one deferred retry via |vim.schedule()| to -recompute once the event loop settles. To avoid relying on this, ensure your -colorscheme plugin has `priority = 1000` and `lazy = false`. Fugitive unified diff highlights: ~ *DiffsAdd* From b421b480c2827d2b82db04094fef311bb7bf2f0d Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Thu, 5 Mar 2026 19:43:08 -0500 Subject: [PATCH 4/8] docs: tighten colorscheme load-order note --- doc/diffs.nvim.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt index 77ddee6..8df152a 100644 --- a/doc/diffs.nvim.txt +++ b/doc/diffs.nvim.txt @@ -65,9 +65,8 @@ Install with lazy.nvim: >lua The plugin works automatically with no configuration required. For customization, see |diffs-config|. -Note: highlight groups are derived from `Normal` when the first diff buffer -opens. Your colorscheme must be loaded by then. With lazy.nvim, ensure it -has `priority = 1000` and `lazy = false`. +Your colorscheme must be loaded before any diff buffer opens. With lazy.nvim, +set `priority = 1000` and `lazy = false` on your colorscheme plugin. ============================================================================== CONFIGURATION *diffs-config* From 8135179deabf9dfba70fde2e5a2811c4083a52d2 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Thu, 5 Mar 2026 19:43:32 -0500 Subject: [PATCH 5/8] docs: fix tense on colorscheme load-order note --- doc/diffs.nvim.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt index 8df152a..ba75972 100644 --- a/doc/diffs.nvim.txt +++ b/doc/diffs.nvim.txt @@ -65,8 +65,8 @@ Install with lazy.nvim: >lua The plugin works automatically with no configuration required. For customization, see |diffs-config|. -Your colorscheme must be loaded before any diff buffer opens. With lazy.nvim, -set `priority = 1000` and `lazy = false` on your colorscheme plugin. +Load your colorscheme before `diffs.nvim`. With lazy.nvim, set +`priority = 1000` and `lazy = false` on your colorscheme plugin. ============================================================================== CONFIGURATION *diffs-config* From 4848e8d5fe150fa8d5f8c43f16372ac723a9cc44 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Thu, 5 Mar 2026 19:43:45 -0500 Subject: [PATCH 6/8] docs: add 'for example' to colorscheme note --- doc/diffs.nvim.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt index ba75972..91aa99d 100644 --- a/doc/diffs.nvim.txt +++ b/doc/diffs.nvim.txt @@ -65,8 +65,8 @@ Install with lazy.nvim: >lua The plugin works automatically with no configuration required. For customization, see |diffs-config|. -Load your colorscheme before `diffs.nvim`. With lazy.nvim, set -`priority = 1000` and `lazy = false` on your colorscheme plugin. +Load your colorscheme before `diffs.nvim`. For example, with lazy.nvim, +set `priority = 1000` and `lazy = false` on your colorscheme plugin. ============================================================================== CONFIGURATION *diffs-config* From b359ea15950303234202e0adec605c1a8e2edae9 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Thu, 5 Mar 2026 19:48:49 -0500 Subject: [PATCH 7/8] doc: clarify colorscheme --- doc/diffs.nvim.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt index 91aa99d..6288f0c 100644 --- a/doc/diffs.nvim.txt +++ b/doc/diffs.nvim.txt @@ -65,7 +65,7 @@ Install with lazy.nvim: >lua The plugin works automatically with no configuration required. For customization, see |diffs-config|. -Load your colorscheme before `diffs.nvim`. For example, with lazy.nvim, +NOTE: Load your colorscheme before `diffs.nvim`. For example, with lazy.nvim, set `priority = 1000` and `lazy = false` on your colorscheme plugin. ============================================================================== From 93ec56e616f464457548f364a6127647f24ee0b1 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Thu, 5 Mar 2026 19:49:59 -0500 Subject: [PATCH 8/8] ci: format --- lua/diffs/init.lua | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/lua/diffs/init.lua b/lua/diffs/init.lua index a68b7ee..ca20308 100644 --- a/lua/diffs/init.lua +++ b/lua/diffs/init.lua @@ -496,7 +496,11 @@ local function compute_highlight_groups() local blended_add_text = blend_color(add_fg, bg, alpha) local blended_del_text = blend_color(del_fg, bg, alpha) - vim.api.nvim_set_hl(0, 'DiffsClear', { default = true, fg = normal.fg or (dark and 0xcccccc or 0x333333), bg = bg }) + vim.api.nvim_set_hl( + 0, + 'DiffsClear', + { default = true, fg = normal.fg or (dark and 0xcccccc or 0x333333), bg = bg } + ) vim.api.nvim_set_hl(0, 'DiffsAdd', { default = true, bg = blended_add }) vim.api.nvim_set_hl(0, 'DiffsDelete', { default = true, bg = blended_del }) vim.api.nvim_set_hl(0, 'DiffsAddNr', { default = true, fg = blended_add_text, bg = blended_add })