fix(tui): limit transparency to canvas surfaces

Author: TheGreatAxios

docs/TUI.md

@@ -248,6 +248,14 @@ and unknown environments fall back to dark. The macOS read has a 500 ms process
 timeout. Production does not query OSC 11 or switch themes after mount, so the
 first frame cannot mix palettes across transcript, prompt, borders, or overlays.
 
+Set `CORBITS_TRANSPARENT_BACKGROUND=1` (also `true`, `yes`, or `on`) to let the
+host terminal show through the root, transcript, landing, welcome, and provider
+canvases. This is an explicit OpenTUI canvas opt-in, not a guess based on
+terminal name or truecolor reporting. The detected or selected dark/light theme
+still owns every foreground color, while the prompt frame and input, decision
+surfaces, and focused or selected rows retain that theme's opaque ground so
+focus and text contrast do not depend on the host background.
+
 ## The live task list panel
 
 **Parked pending rebuild.** `formatChromeZones` (`src/tui/chrome-state.ts`)

src/tui/landing.ts

@@ -317,23 +317,23 @@ export function createLandingAbove(
     flexDirection: "column",
     justifyContent: "flex-end",
     paddingLeft: LANDING_MARGIN,
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
   });
   const hero = new BoxRenderable(ctx, {
     id: "shell-landing-hero",
     width: "100%",
     height: MARK_LARGE.rows,
     flexShrink: 0,
     flexDirection: "row",
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
   });
   const markColumn = new BoxRenderable(ctx, {
     id: "shell-landing-mark",
     width: MARK_LARGE.cols,
     flexShrink: 0,
     flexDirection: "column",
     justifyContent: "flex-end",
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
   });
   const markRows: TextRenderable[] = [];
   for (let row = 0; row < MARK_LARGE.rows; row++) {
@@ -380,7 +380,7 @@ function createHintBlock(ctx: CliRenderer): BoxRenderable {
     // empty beneath them, which reads as unfinished rather than composed.
     justifyContent: "center",
     paddingLeft: LANDING_HERO_GAP,
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
   });
   LANDING_HINTS.forEach((hint, index) => {
     const gap = " ".repeat(
@@ -452,7 +452,7 @@ export function createLandingBelow(
     flexShrink: 0,
     flexDirection: "column",
     paddingLeft: LANDING_MARGIN,
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
   });
   landingBelowRows(content).forEach((row, index) => {
     box.add(

src/tui/provider/surface.ts

@@ -119,7 +119,7 @@ export function createSurface(
     width: "100%",
     height: "100%",
     flexDirection: "column",
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
     paddingTop: 1,
     paddingLeft: margin,
     paddingRight: margin,
@@ -162,7 +162,7 @@ export function createSurface(
     flexDirection: "column",
     flexShrink: 0,
     paddingTop: 1,
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
   });
   const summarySlots = Array.from(
     { length: SUMMARY_SLOTS },
@@ -181,7 +181,7 @@ export function createSurface(
     flexDirection: "column",
     flexShrink: 0,
     paddingTop: 1,
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
   });
   const listSlots = Array.from(
     { length: PROVIDER_LIST_ROWS_MAX },
@@ -225,7 +225,7 @@ export function createSurface(
     flexDirection: "column",
     flexShrink: 0,
     paddingTop: 1,
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
     visible: false,
   });
   const loginSlots = Array.from(
@@ -257,7 +257,7 @@ export function createSurface(
     flexDirection: "column",
     flexShrink: 0,
     paddingTop: 1,
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
     visible: config.showTelemetryNotice,
   });
   const telemetrySlots = Array.from(

src/tui/shell/index.ts

@@ -124,7 +124,7 @@ export function createAppShell(
     width: "100%",
     height: "100%",
     flexDirection: "column",
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
     paddingLeft: layout.sideMargin,
     paddingRight: layout.sideMargin,
   });
@@ -136,7 +136,7 @@ export function createAppShell(
     width: "100%",
     height: 1,
     flexShrink: 0,
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
   });
 
   // Same gutter, other end: keeps the prompt box off the terminal's last row.
@@ -145,7 +145,7 @@ export function createAppShell(
     width: "100%",
     height: 1,
     flexShrink: 0,
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
   });
 
   // Persistent chrome, not part of the landing composition (`landing.ts`
@@ -164,7 +164,7 @@ export function createAppShell(
     flexShrink: 0,
     flexDirection: "row",
     justifyContent: "flex-end",
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
     visible: versionBadgeVisible(terminal.columns, terminal.rows),
   });
   const versionBadge = new TextRenderable(ctx, {
@@ -181,7 +181,7 @@ export function createAppShell(
     height: 1,
     flexShrink: 0,
     flexDirection: "column",
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
     visible: false,
   });
 
@@ -191,7 +191,7 @@ export function createAppShell(
     height: 1,
     flexShrink: 0,
     flexDirection: "column",
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
     visible: false,
   });
 
@@ -204,9 +204,9 @@ export function createAppShell(
     stickyStart: "bottom",
     scrollY: true,
     focusable: true,
-    rootOptions: { backgroundColor: UI.ground },
-    contentOptions: { backgroundColor: UI.ground },
-    viewportOptions: { backgroundColor: UI.ground },
+    rootOptions: { backgroundColor: UI.canvasGround },
+    contentOptions: { backgroundColor: UI.canvasGround },
+    viewportOptions: { backgroundColor: UI.canvasGround },
   });
   // The transcript scrolls with the keyboard, and the bar spent a column on
   // every row to say so. Position is legible from the content itself.
@@ -224,7 +224,7 @@ export function createAppShell(
     width: "100%",
     height: 0,
     flexShrink: 0,
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
   });
   transcript.add(transcriptSpacer);
 
@@ -260,7 +260,7 @@ export function createAppShell(
     height: Math.max(1, layout.heights.pending),
     flexShrink: 0,
     flexDirection: "column",
-    backgroundColor: UI.ground,
+    backgroundColor: UI.canvasGround,
     visible: layout.heights.pending > 0,
   });