feat(tui): add opt-in transparent backgrounds

Author: TheGreatAxios

src/index.ts

@@ -17,6 +17,7 @@ import {
 import { runExec } from "./exec/runner.js";
 import { runOnboarding } from "./tui/onboarding.js";
 import { runTUI } from "./tui/runner/index.js";
+import { configureTransparentBackground } from "./tui/theme.js";
 
 export interface Runners {
   runTUI: (config: import("./config/index.js").Config) => Promise<number>;
@@ -84,6 +85,8 @@ export async function mainWithRunners(
   }
 
   let exitCode: number;
+  // Welcome, setup, and the product host read `UI` at construction time.
+  if (config.command === "tui") configureTransparentBackground();
   if (!config.configured) {
     if (config.command === "exec") {
       // Exec needs a provider; onboarding is TUI-only. Fail closed with a

src/tui/theme-transparent.test.ts

@@ -0,0 +1,151 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import {
+  BRAND,
+  configureTransparentBackground,
+  corbitsDark,
+  resetTransparentBackgroundLogForTests,
+  resolveGround,
+  TRANSPARENT_BACKGROUND,
+  UI,
+  type Theme,
+  type TransparentBackgroundEnv,
+} from "./theme.js";
+
+const SUPPORTED: TransparentBackgroundEnv = {
+  CORBITS_TRANSPARENT_BACKGROUND: "1",
+  COLORTERM: "truecolor",
+  TERM_PROGRAM: "kitty",
+};
+
+const NO_TRUECOLOR: TransparentBackgroundEnv = {
+  CORBITS_TRANSPARENT_BACKGROUND: "1",
+  TERM_PROGRAM: "kitty",
+};
+
+const UNKNOWN_TERMINAL: TransparentBackgroundEnv = {
+  CORBITS_TRANSPARENT_BACKGROUND: "true",
+  COLORTERM: "truecolor",
+  TERM: "xterm-256color",
+};
+
+// Stand-in for the future light theme: the resolver must honor whatever
+// ground the active theme carries, not just the dark hex.
+const light: Theme = {
+  ...corbitsDark,
+  name: "corbits-light",
+  ground: "#f7ead5",
+};
+
+afterEach(() => {
+  (UI as { ground: string }).ground = corbitsDark.ground;
+  resetTransparentBackgroundLogForTests();
+});
+
+describe("resolveGround", () => {
+  test("default stays opaque without logging", () => {
+    let logged = 0;
+    for (const theme of [corbitsDark, light]) {
+      expect(resolveGround(theme, {}, () => logged++)).toBe(theme.ground);
+    }
+    expect(logged).toBe(0);
+  });
+
+  test("requested and supported resolves transparent for both themes", () => {
+    let logged = 0;
+    const onFallback = () => logged++;
+    expect(resolveGround(corbitsDark, SUPPORTED, onFallback)).toBe(
+      TRANSPARENT_BACKGROUND,
+    );
+    expect(resolveGround(light, SUPPORTED, onFallback)).toBe(
+      TRANSPARENT_BACKGROUND,
+    );
+    expect(logged).toBe(0);
+  });
+
+  test("truthy env spellings opt in when supported", () => {
+    for (const value of ["1", "true", "yes", "on", " TRUE "]) {
+      const env = { ...SUPPORTED, CORBITS_TRANSPARENT_BACKGROUND: value };
+      expect(resolveGround(corbitsDark, env)).toBe(TRANSPARENT_BACKGROUND);
+    }
+  });
+
+  test("falsy env spellings stay opaque without logging", () => {
+    let logged = 0;
+    for (const value of ["0", "false", "off", "", "no"]) {
+      const env = { ...SUPPORTED, CORBITS_TRANSPARENT_BACKGROUND: value };
+      expect(resolveGround(corbitsDark, env, () => logged++)).toBe(
+        corbitsDark.ground,
+      );
+    }
+    expect(logged).toBe(0);
+  });
+
+  test("requested without truecolor falls back to opaque with one log line", () => {
+    const lines: string[] = [];
+    expect(resolveGround(corbitsDark, NO_TRUECOLOR, (m) => lines.push(m))).toBe(
+      corbitsDark.ground,
+    );
+    expect(resolveGround(light, NO_TRUECOLOR, (m) => lines.push(m))).toBe(
+      light.ground,
+    );
+    expect(lines).toHaveLength(1);
+  });
+
+  test("requested on an unknown terminal falls back to opaque", () => {
+    const lines: string[] = [];
+    expect(
+      resolveGround(corbitsDark, UNKNOWN_TERMINAL, (m) => lines.push(m)),
+    ).toBe(corbitsDark.ground);
+    expect(lines).toHaveLength(1);
+  });
+
+  test("24bit colorterm with a TERM hint counts as supported", () => {
+    const env: TransparentBackgroundEnv = {
+      CORBITS_TRANSPARENT_BACKGROUND: "on",
+      COLORTERM: "24bit",
+      TERM: "xterm-ghostty",
+    };
+    expect(resolveGround(corbitsDark, env)).toBe(TRANSPARENT_BACKGROUND);
+  });
+});
+
+describe("configureTransparentBackground", () => {
+  test("default leaves UI opaque", () => {
+    const lines: string[] = [];
+    expect(configureTransparentBackground({}, (m) => lines.push(m))).toBe(
+      false,
+    );
+    expect(UI.ground).toBe(corbitsDark.ground);
+    expect(lines).toHaveLength(0);
+  });
+
+  test("supported request publishes transparent on UI", () => {
+    expect(configureTransparentBackground(SUPPORTED)).toBe(true);
+    expect(UI.ground).toBe(TRANSPARENT_BACKGROUND);
+  });
+
+  test("default restores opaque ground after a transparent configuration", () => {
+    expect(configureTransparentBackground(SUPPORTED)).toBe(true);
+    expect(configureTransparentBackground({})).toBe(false);
+    expect(UI.ground).toBe(corbitsDark.ground);
+  });
+
+  test("unsupported request keeps UI opaque and logs once", () => {
+    const lines: string[] = [];
+    const onFallback = (m: string) => lines.push(m);
+    expect(configureTransparentBackground(NO_TRUECOLOR, onFallback)).toBe(
+      false,
+    );
+    expect(configureTransparentBackground(NO_TRUECOLOR, onFallback)).toBe(
+      false,
+    );
+    expect(UI.ground).toBe(corbitsDark.ground);
+    expect(lines).toHaveLength(1);
+  });
+
+  test("never mutates the dark theme's own ground", () => {
+    configureTransparentBackground(SUPPORTED);
+    expect(corbitsDark.ground).toBe(BRAND.ground);
+  });
+});

src/tui/theme.ts

@@ -100,5 +100,109 @@ export const corbitsDark: Theme = {
   error: ERROR_RED,
 };
 
+const activeTheme: Theme = corbitsDark;
+
 /** Semantic roles. Everything outside this file paints through these. */
-export const UI: Theme = corbitsDark;
+export const UI: Theme = { ...activeTheme };
+
+/**
+ * Background value that lets the host terminal show through. OpenTUI accepts
+ * it (its own defaults use it), so every `backgroundColor: UI.ground` site
+ * follows without per-surface edits once the configurator runs.
+ */
+export const TRANSPARENT_BACKGROUND = "transparent";
+
+const TRANSPARENT_BG_ENV_VAR = "CORBITS_TRANSPARENT_BACKGROUND";
+
+/** Terminals whose compositing path is known to show the host background. */
+const TRANSPARENT_BG_PROGRAMS = new Set([
+  "iterm.app",
+  "wezterm",
+  "kitty",
+  "ghostty",
+  "alacritty",
+  "foot",
+]);
+
+const TRANSPARENT_BG_TERM_HINTS = [
+  "kitty",
+  "ghostty",
+  "wezterm",
+  "alacritty",
+  "foot",
+];
+
+export interface TransparentBackgroundEnv {
+  readonly [key: string]: string | undefined;
+  readonly CORBITS_TRANSPARENT_BACKGROUND?: string;
+  readonly COLORTERM?: string;
+  readonly TERM?: string;
+  readonly TERM_PROGRAM?: string;
+}
+
+type TransparentFallbackLog = (message: string) => void;
+
+let transparentFallbackLogged = false;
+
+/** Re-arm the one-time fallback log; tests only. */
+export function resetTransparentBackgroundLogForTests(): void {
+  transparentFallbackLogged = false;
+}
+
+export function isTransparentBackgroundRequested(
+  env: TransparentBackgroundEnv = process.env,
+): boolean {
+  const raw = env[TRANSPARENT_BG_ENV_VAR]?.trim().toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+
+export function supportsTransparentBackground(
+  env: TransparentBackgroundEnv = process.env,
+): boolean {
+  const colorterm = env.COLORTERM?.trim().toLowerCase();
+  if (colorterm !== "truecolor" && colorterm !== "24bit") return false;
+  const program = (env.TERM_PROGRAM ?? "").trim().toLowerCase();
+  if (TRANSPARENT_BG_PROGRAMS.has(program)) return true;
+  const term = (env.TERM ?? "").trim().toLowerCase();
+  return TRANSPARENT_BG_TERM_HINTS.some((hint) => term.includes(hint));
+}
+
+/**
+ * The ground a theme paints with: `"transparent"` when requested and
+ * supported, otherwise the theme's opaque ground. Unsupported requests fall
+ * back to opaque with a single log line.
+ */
+export function resolveGround(
+  theme: Theme,
+  env: TransparentBackgroundEnv = process.env,
+  onFallback: TransparentFallbackLog = (message) => {
+    process.stderr.write(`${message}\n`);
+  },
+): string {
+  if (!isTransparentBackgroundRequested(env)) return theme.ground;
+  if (supportsTransparentBackground(env)) return TRANSPARENT_BACKGROUND;
+  if (!transparentFallbackLogged) {
+    transparentFallbackLogged = true;
+    onFallback(
+      "corbits: transparent background requested but unsupported here; using opaque ground",
+    );
+  }
+  return theme.ground;
+}
+
+/**
+ * Startup entry: resolves the active theme's ground once and publishes it on
+ * `UI` so all surfaces follow. Must run before any surface builds. Returns
+ * true when the shell paints transparent.
+ */
+export function configureTransparentBackground(
+  env: TransparentBackgroundEnv = process.env,
+  onFallback?: TransparentFallbackLog,
+): boolean {
+  const ground =
+    onFallback === undefined
+      ? resolveGround(activeTheme, env)
+      : resolveGround(activeTheme, env, onFallback);
+  Object.assign(UI, { ground });
+  return ground === TRANSPARENT_BACKGROUND;
+}