Fix iterm alternate buffer mode issue rendering backgrounds (#17634)

packages/cli/src/test-utils/render.tsx

@@ -40,6 +40,7 @@ vi.mock('../utils/persistentState.js', () => ({
 vi.mock('../ui/utils/terminalUtils.js', () => ({
   isLowColorDepth: vi.fn(() => false),
   getColorDepth: vi.fn(() => 24),
+  isITerm2: vi.fn(() => false),
 }));
 
 // Wrapper around ink-testing-library's render that ensures act() is called

packages/cli/src/ui/components/shared/HalfLinePaddedBox.test.tsx

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { renderWithProviders } from '../../../test-utils/render.js';
+import { HalfLinePaddedBox } from './HalfLinePaddedBox.js';
+import { Text } from 'ink';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { isITerm2 } from '../../utils/terminalUtils.js';
+
+describe('<HalfLinePaddedBox />', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('renders standard background and blocks when not iTerm2', async () => {
+    vi.mocked(isITerm2).mockReturnValue(false);
+
+    const { lastFrame, unmount } = renderWithProviders(
+      <HalfLinePaddedBox backgroundBaseColor="blue" backgroundOpacity={0.5}>
+        <Text>Content</Text>
+      </HalfLinePaddedBox>,
+      { width: 10 },
+    );
+
+    expect(lastFrame()).toMatchSnapshot();
+
+    unmount();
+  });
+
+  it('renders iTerm2-specific blocks when iTerm2 is detected', async () => {
+    vi.mocked(isITerm2).mockReturnValue(true);
+
+    const { lastFrame, unmount } = renderWithProviders(
+      <HalfLinePaddedBox backgroundBaseColor="blue" backgroundOpacity={0.5}>
+        <Text>Content</Text>
+      </HalfLinePaddedBox>,
+      { width: 10 },
+    );
+
+    expect(lastFrame()).toMatchSnapshot();
+
+    unmount();
+  });
+
+  it('renders nothing when useBackgroundColor is false', async () => {
+    const { lastFrame, unmount } = renderWithProviders(
+      <HalfLinePaddedBox
+        backgroundBaseColor="blue"
+        backgroundOpacity={0.5}
+        useBackgroundColor={false}
+      >
+        <Text>Content</Text>
+      </HalfLinePaddedBox>,
+      { width: 10 },
+    );
+
+    expect(lastFrame()).toMatchSnapshot();
+
+    unmount();
+  });
+});

packages/cli/src/ui/components/shared/HalfLinePaddedBox.tsx

@@ -13,7 +13,7 @@ import {
   resolveColor,
   getSafeLowColorBackground,
 } from '../../themes/color-utils.js';
-import { isLowColorDepth } from '../../utils/terminalUtils.js';
+import { isLowColorDepth, isITerm2 } from '../../utils/terminalUtils.js';
 
 export interface HalfLinePaddedBoxProps {
   /**
@@ -77,6 +77,35 @@ const HalfLinePaddedBoxInternal: React.FC<HalfLinePaddedBoxProps> = ({
     return <>{children}</>;
   }
 
+  const isITerm = isITerm2();
+
+  if (isITerm) {
+    return (
+      <Box
+        width={terminalWidth}
+        flexDirection="column"
+        alignItems="stretch"
+        minHeight={1}
+        flexShrink={0}
+      >
+        <Box width={terminalWidth} flexDirection="row">
+          <Text color={backgroundColor}>{'▄'.repeat(terminalWidth)}</Text>
+        </Box>
+        <Box
+          width={terminalWidth}
+          flexDirection="column"
+          alignItems="stretch"
+          backgroundColor={backgroundColor}
+        >
+          {children}
+        </Box>
+        <Box width={terminalWidth} flexDirection="row">
+          <Text color={backgroundColor}>{'▀'.repeat(terminalWidth)}</Text>
+        </Box>
+      </Box>
+    );
+  }
+
   return (
     <Box
       width={terminalWidth}

packages/cli/src/ui/components/shared/__snapshots__/HalfLinePaddedBox.test.tsx.snap

@@ -0,0 +1,15 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`<HalfLinePaddedBox /> > renders iTerm2-specific blocks when iTerm2 is detected 1`] = `
+"▄▄▄▄▄▄▄▄▄▄
+Content
+▀▀▀▀▀▀▀▀▀▀"
+`;
+
+exports[`<HalfLinePaddedBox /> > renders nothing when useBackgroundColor is false 1`] = `"Content"`;
+
+exports[`<HalfLinePaddedBox /> > renders standard background and blocks when not iTerm2 1`] = `
+"▀▀▀▀▀▀▀▀▀▀
+Content
+▄▄▄▄▄▄▄▄▄▄"
+`;

packages/cli/src/ui/utils/terminalUtils.test.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { isITerm2, resetITerm2Cache } from './terminalUtils.js';
+
+describe('terminalUtils', () => {
+  beforeEach(() => {
+    vi.stubEnv('TERM_PROGRAM', '');
+    vi.stubEnv('ITERM_SESSION_ID', '');
+    resetITerm2Cache();
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.restoreAllMocks();
+  });
+
+  it('should detect iTerm2 via TERM_PROGRAM', () => {
+    vi.stubEnv('TERM_PROGRAM', 'iTerm.app');
+    expect(isITerm2()).toBe(true);
+  });
+
+  it('should detect iTerm2 via ITERM_SESSION_ID', () => {
+    vi.stubEnv('ITERM_SESSION_ID', 'w0t0p0:6789...');
+    expect(isITerm2()).toBe(true);
+  });
+
+  it('should return false if not iTerm2', () => {
+    vi.stubEnv('TERM_PROGRAM', 'vscode');
+    expect(isITerm2()).toBe(false);
+  });
+
+  it('should cache the result', () => {
+    vi.stubEnv('TERM_PROGRAM', 'iTerm.app');
+    expect(isITerm2()).toBe(true);
+
+    // Change env but should still be true due to cache
+    vi.stubEnv('TERM_PROGRAM', 'vscode');
+    expect(isITerm2()).toBe(true);
+
+    resetITerm2Cache();
+    expect(isITerm2()).toBe(false);
+  });
+});

packages/cli/src/ui/utils/terminalUtils.ts

@@ -20,3 +20,28 @@ export function getColorDepth(): number {
 export function isLowColorDepth(): boolean {
   return getColorDepth() < 24;
 }
+
+let cachedIsITerm2: boolean | undefined;
+
+/**
+ * Returns true if the current terminal is iTerm2.
+ */
+export function isITerm2(): boolean {
+  if (cachedIsITerm2 !== undefined) {
+    return cachedIsITerm2;
+  }
+
+  cachedIsITerm2 =
+    process.env['TERM_PROGRAM'] === 'iTerm.app' ||
+    !!process.env['ITERM_SESSION_ID'];
+
+  return cachedIsITerm2;
+}
+
+/**
+ * Resets the cached iTerm2 detection value.
+ * Primarily used for testing.
+ */
+export function resetITerm2Cache(): void {
+  cachedIsITerm2 = undefined;
+}