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,198 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import {
+  BRAND,
+  configureTransparentBackground,
+  corbitsDark,
+  corbitsLight,
+  resetTransparentBackgroundLogForTests,
+  resolveGround,
+  setTheme,
+  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",
+};
+
+afterEach(() => {
+  configureTransparentBackground({});
+  setTheme("corbits-dark");
+  resetTransparentBackgroundLogForTests();
+});
+
+describe("resolveGround", () => {
+  test("default stays opaque without logging", () => {
+    let logged = 0;
+    for (const theme of [corbitsDark, corbitsLight]) {
+      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(corbitsLight, 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(corbitsLight, NO_TRUECOLOR, (m) => lines.push(m)),
+    ).toBe(corbitsLight.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);
+  });
+});
+
+describe("theme and transparency composition", () => {
+  const matrix: [string, Theme, TransparentBackgroundEnv, string][] = [
+    ["corbits-dark", corbitsDark, {}, corbitsDark.ground],
+    ["corbits-dark", corbitsDark, SUPPORTED, TRANSPARENT_BACKGROUND],
+    ["corbits-light", corbitsLight, {}, corbitsLight.ground],
+    ["corbits-light", corbitsLight, SUPPORTED, TRANSPARENT_BACKGROUND],
+  ];
+
+  for (const [name, theme, env, expectedGround] of matrix) {
+    const background =
+      expectedGround === TRANSPARENT_BACKGROUND ? "transparent" : "default";
+    test(`${name} with ${background} background`, () => {
+      setTheme(name);
+      configureTransparentBackground(env);
+      expect(UI.name).toBe(theme.name);
+      expect(UI.text).toBe(theme.text);
+      expect(UI.ground).toBe(expectedGround);
+    });
+  }
+
+  test("sync setTheme preserves the transparency overlay", () => {
+    configureTransparentBackground(SUPPORTED);
+    setTheme("corbits-light");
+    expect(UI.name).toBe("corbits-light");
+    expect(UI.text).toBe(corbitsLight.text);
+    expect(UI.ground).toBe(TRANSPARENT_BACKGROUND);
+  });
+
+  test("configure after setTheme uses the selected theme fallback", () => {
+    setTheme("corbits-light");
+    configureTransparentBackground({});
+    expect(UI.ground).toBe(corbitsLight.ground);
+  });
+
+  test("async-equivalent theme transition preserves transparency", async () => {
+    configureTransparentBackground(SUPPORTED);
+    await Promise.resolve();
+    setTheme("corbits-light");
+    expect(UI.name).toBe("corbits-light");
+    expect(UI.text).toBe(corbitsLight.text);
+    expect(UI.ground).toBe(TRANSPARENT_BACKGROUND);
+  });
+
+  test("disabling transparency restores the selected light ground", () => {
+    setTheme("corbits-light");
+    configureTransparentBackground(SUPPORTED);
+    configureTransparentBackground({});
+    expect(UI.name).toBe("corbits-light");
+    expect(UI.ground).toBe(corbitsLight.ground);
+  });
+});

src/tui/theme.ts

@@ -149,11 +149,120 @@ export function resolveThemeName(name: string): Theme {
  */
 export const UI: Theme = { ...corbitsDark };
 
+let activeTheme: Theme = corbitsDark;
+let transparentBackgroundEnabled = false;
+
+function publishTheme(): Theme {
+  Object.assign(UI, activeTheme, {
+    ground: transparentBackgroundEnabled
+      ? TRANSPARENT_BACKGROUND
+      : activeTheme.ground,
+  });
+  return UI;
+}
+
 /** Switch the live `UI` binding to the named theme, keeping the reference. */
 export function setTheme(name: ThemeName | string): Theme {
-  const next = resolveThemeName(name);
-  Object.assign(UI, next);
-  return UI;
+  activeTheme = resolveThemeName(name);
+  return publishTheme();
+}
+
+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);
+  transparentBackgroundEnabled = ground === TRANSPARENT_BACKGROUND;
+  publishTheme();
+  return transparentBackgroundEnabled;
 }
 
 // Known-divergent follow-up: `semantic-theme.ts` still carries its own