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

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
+▄▄▄▄▄▄▄▄▄▄"
+`;