Skip to content

fix(nvim): keep the palette readable on terminals without truecolor - #54

Merged
YASoftwareDev merged 2 commits into
masterfrom
fix/nvim-low-colour-terminal
Sep 18, 2026
Merged

YASoftwareDev merged 2 commits into
masterfrom
fix/nvim-low-colour-terminal

Conversation

@YASoftwareDev

Copy link
Copy Markdown
Owner

What

On a terminal that cannot carry truecolor, nvim rendered near-black text on a
near-black background. Such terminals now get habamax with notermguicolors;
terminals reporting 256 colours keep nightfly and truecolor, unchanged.

Closes #53.

Why

Two facts, both measured 2026-09-18 on dev-01:

  1. init.lua forced opt.termguicolors = true unconditionally, so nvim emits
    38;2;R;G;B even on an 8-colour terminfo. Captured from the raw PTY stream
    under TERM=xterm (tput colors = 8):

    [38;2;195;204;220m[48;2;1;22;39m
    
  2. nightfly defines no cterm colours at all, so nothing readable is left
    when those sequences do not arrive. Resolved Normal/Comment, identical on
    every TERM tried:

    scheme Normal ctermfg/ctermbg
    nightfly (active), gruvbox, default none / none
    habamax 251 / 234
    desert 231 / 236

What was ruled out first

The tmux config was the other suspect: .tmux.conf.local sets
default-terminal "tmux-256color" and adds Tc only for an outer
xterm-256color. Probed all 14 fleet hosts through the caged account; 12
answered (gapcio and hultaj do not resolve from dev-01, a recorded limit). All
12 have the tmux-256color terminfo entry and tmux 3.0a-3.4, so every one is
Tc-capable. Not the cause on those hosts.

Direction of the gate, stated because it is a trade-off

The gate fires only on positive evidence of a low-colour terminal (TERM without
256/direct and no COLORTERM), so no 256-colour host changes. ssh does not
forward COLORTERM, so a capable terminal that advertises nothing lands on the
readable fallback. That direction is deliberate: a downgraded palette is visible
and one line in ~/.config/nvim/local.lua undoes it, while an unreadable buffer
is the bug being fixed. local.lua.example documents the override.

Verified

  • tests/nvim-colour-fallback.sh - new, two arms (low-colour must be readable,
    256-colour must be unchanged). Wired into nvim-version-gates, so it runs on
    pinned nvim 0.10.4 and 0.11.5. No new job, so ci-gate's needs is unchanged
    and tests/ci-gate-covers-all.py still passes.

  • Red-proof. Reverting both halves of the fix (opt.termguicolors = true,
    if true then) turns arm 1 red on both checks while arm 2 stays green, so the
    test discriminates rather than merely failing:

    arm 1: scheme=nightfly tgc=true ctermfg=nil ctermbg=nil
      ERROR: no ctermbg on a low-colour terminal - the buffer has no readable background
      ERROR: termguicolors still on for a low-colour terminal - RGB it cannot parse
    arm 2: OK: 256-colour terminal keeps nightfly / keeps termguicolors
    RESULT: FAILED
    

    Restored: RESULT: PASSED (4 checks ran, none skipped).

  • The skip path is red-proofed too. Arm 2 needs the nightfly plugin on disk;
    a failed data-dir probe used to read as "nothing to check". Forcing the probe
    to fail now gives ERROR: could not resolve nvim's data dir and rc=1, and the
    verdict reports how many checks actually ran.

  • bash tests/lint-workflows.sh - PASSED (3 checks, none skipped).

  • bash test.sh workstation - 61/62, 0 failures, 1 skip; same as before.

  • shellcheck -S warning clean on the new script.

Not established

Which servers show this, and what their terminals report. If a host where it
looks wrong reports 256 colours, this gate will not fire there and the cause is
something else - the outer-TERM Tc override is the next suspect. TERM and
tput colors from one such server would settle it.

termguicolors was forced on, while nightfly defines only gui colours -
measured 2026-09-18, its Normal and Comment carry no ctermfg/ctermbg at
all. A terminal that cannot parse 38;2;R;G;B therefore had nothing to
fall back to and rendered near-black on near-black (#53).

Only downgrade on positive evidence of a low-colour terminal, so every
host reporting 256 colours keeps nightfly and truecolor unchanged.

Closes #53
@YASoftwareDev
YASoftwareDev merged commit 3b7e28c into master Sep 18, 2026
30 checks passed
@YASoftwareDev
YASoftwareDev deleted the fix/nvim-low-colour-terminal branch September 18, 2026 10:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

nvim palette unreadable on some servers: near-black text on near-black background

2 participants