fix(highlight): retry highlight computation when Normal has no background

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.
This commit is contained in:
Barrett Ruth 2026-03-05 19:40:48 -05:00
parent 904f141366
commit d1f7acde8e
Signed by: barrett
GPG key ID: A6C96C9349D2FC81
2 changed files with 19 additions and 0 deletions

View file

@ -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