feat: allow transparent background via config or flag

[mvanhorn]

Summary

Adds an opt-in transparent-background mode for the diff UI. Users can pass --transparent on the command line or set transparent_background = true in their config. When enabled, the diff theme omits the background fill so terminal or IDE theming shows through.

Why this matters

#245 wanted hunk's output to blend with their terminal color scheme rather than re-stating a hard-coded background. This change is opt-in and keeps the default rendering untouched.

Changes

• src/core/cli.ts + src/core/cli.test.ts - new --transparent flag.
• src/core/config.ts + src/core/config.test.ts - new transparent_background config key.
• src/core/types.ts - thread the option through the config type.
• src/ui/App.tsx - read the option and apply it to the diff theme.
• src/ui/themes.ts + src/ui/themes.test.ts - theme variant that drops the background fill.
• src/ui/diff/pierre.ts - omit the background ink when the theme says so.
• README.md + CHANGELOG.md - document the new option.

Testing

New unit tests cover the flag, the config key, and the transparent theme. Existing tests still pass.

Fixes #245

[greptile-apps]

Greptile Summary

Adds an opt-in --transparent-background CLI flag and transparent_background config key that replaces all painted surface colors with \"transparent\" so the terminal or IDE background shows through Hunk's diff UI.

• themes.ts gets a withTransparentBackground() helper and a TRANSPARENT_BACKGROUND constant; App.tsx applies it via useMemo; pierre.ts broadens the word-diff background cache key to include the actual color values so transparent and opaque variants of the same theme don't collide.
• Config, CLI, and type layers are all updated consistently, accepting both transparent_background (snake_case) and transparentBackground (camelCase) in TOML; new unit tests cover the flag, config key, and theme transformation.

Confidence Score: 3/5

Safe to merge for users who leave transparent mode off; the default path is unchanged. Enabling transparent mode will render word-diff highlight spans as dark opaque blocks.

The transparent path in wordDiffHighlightBg computes backgrounds by passing the string 'transparent' into hexToRgb, which silently falls back to black. Every word-diff emphasis span gets a dark opaque color instead of transparent whenever the feature is used, directly breaking the feature's core promise for syntax-highlighted content.

src/ui/diff/pierre.ts — the wordDiffHighlightBg function needs a guard for 'transparent' backgrounds before the hex-distance computation runs.

Important Files Changed

Filename	Overview
src/ui/diff/pierre.ts	Cache key broadened to include all background colors — correct design — but wordDiffHighlightBg doesn't guard against the "transparent" string, so hexToRgb falls back to black and produces dark opaque word-diff highlights instead of transparent ones.
src/ui/themes.ts	Adds TRANSPARENT_BACKGROUND constant and withTransparentBackground() that copies a theme while replacing all painted surface fields with "transparent"; non-background fields (text, borders, syntax colors) are correctly preserved.
src/ui/App.tsx	Correctly wraps the transparent-background variant in useMemo keyed on baseTheme and the bootstrap flag, so the active theme is only recomputed when the user changes theme or the transparency setting changes.
src/core/config.ts	transparentBackground is threaded through config defaults, mergeOptions, and finalization; accepts both snake_case and camelCase TOML keys and correctly defaults to false.
src/core/cli.ts	Adds --transparent-background / --no-transparent-background flags with consistent help text in both the commander option registration and the manual renderCliHelp output.
src/core/types.ts	Adds the optional transparentBackground boolean to CommonOptions — straightforward one-line change.
src/ui/themes.test.ts	New test file; verifies all painted surfaces are replaced, id/label/text/syntax fields are preserved, and the original theme is not mutated.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[CLI --transparent-background] --> B[parseCli transparentBackground: true]
    C[config.toml transparent_background = true] --> D[readConfigPreferences]
    D --> E[mergeOptions]
    B --> E
    E --> F[resolvedOptions.transparentBackground]
    F --> G[bootstrap.input.options.transparentBackground]
    G --> H{transparent?}
    H -- yes --> I[withTransparentBackground baseTheme]
    H -- no --> J[baseTheme unchanged]
    I --> K[activeTheme all bg = transparent]
    J --> K2[activeTheme normal hex colors]
    K --> L[pierre.ts wordDiffHighlightBg]
    K2 --> L
    L --> M{addedBg === transparent?}
    M -- yes --> N[return transparent - fix needed]
    M -- no --> O[hexColorDistance + strengthen normal hex path]

Loading

Comments Outside Diff (1)

1. src/ui/diff/pierre.ts, line 208-216 (link)

   Word-diff highlights compute as opaque dark boxes in transparent mode

   hexToRgb falls back to black {r:0,g:0,b:0} for the string "transparent", so hexColorDistance("transparent", "transparent") returns 0 (< MIN_WORD_DIFF_BG_DISTANCE). This sends both the addition and deletion paths into strengthenWordDiffBg("transparent", signColor), which blends toward black and emits a dark opaque hex like #1b2a1f as the word-diff emphasis background. Every word-level change highlight will show a solid dark background even though transparent mode was requested.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: src/ui/diff/pierre.ts
   Line: 208-216
   
   Comment:
   **Word-diff highlights compute as opaque dark boxes in transparent mode**
   
   `hexToRgb` falls back to black `{r:0,g:0,b:0}` for the string `"transparent"`, so `hexColorDistance("transparent", "transparent")` returns `0` (< `MIN_WORD_DIFF_BG_DISTANCE`). This sends both the addition and deletion paths into `strengthenWordDiffBg("transparent", signColor)`, which blends toward black and emits a dark opaque hex like `#1b2a1f` as the word-diff emphasis background. Every word-level change highlight will show a solid dark background even though transparent mode was requested.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
src/ui/diff/pierre.ts:208-216
**Word-diff highlights compute as opaque dark boxes in transparent mode**

`hexToRgb` falls back to black `{r:0,g:0,b:0}` for the string `"transparent"`, so `hexColorDistance("transparent", "transparent")` returns `0` (< `MIN_WORD_DIFF_BG_DISTANCE`). This sends both the addition and deletion paths into `strengthenWordDiffBg("transparent", signColor)`, which blends toward black and emits a dark opaque hex like `#1b2a1f` as the word-diff emphasis background. Every word-level change highlight will show a solid dark background even though transparent mode was requested.

```suggestion
/** Resolve the inline word-diff background, strengthening theme colors that are too subtle to see. */
function wordDiffHighlightBg(kind: SplitLineCell["kind"], theme: AppTheme) {
  if (theme.addedBg === "transparent") {
    return "transparent";
  }
  const cacheKey = [
```

_{Reviews (1): Last reviewed commit: "feat: allow transparent background via c..." | Re-trigger Greptile}