feat(ui): Introduce useUI Hook and UIContext (google-gemini#5488)

Co-authored-by: Jacob Richman <jacob314@gmail.com>

Author: 2 people

docs/mermaid/context.mmd

@@ -0,0 +1,103 @@
+graph LR
+    %% --- Style Definitions ---
+    classDef new fill:#98fb98,color:#000
+    classDef changed fill:#add8e6,color:#000
+    classDef unchanged fill:#f0f0f0,color:#000
+
+    %% --- Subgraphs ---
+    subgraph "Context Providers"
+        direction TB
+        A["gemini.tsx"]
+        B["AppContainer.tsx"]
+    end
+
+    subgraph "Contexts"
+        direction TB
+        CtxSession["SessionContext"]
+        CtxVim["VimModeContext"]
+        CtxSettings["SettingsContext"]
+        CtxApp["AppContext"]
+        CtxConfig["ConfigContext"]
+        CtxUIState["UIStateContext"]
+        CtxUIActions["UIActionsContext"]
+    end
+
+    subgraph "Component Consumers"
+        direction TB
+        ConsumerApp["App"]
+        ConsumerAppContainer["AppContainer"]
+        ConsumerAppHeader["AppHeader"]
+        ConsumerDialogManager["DialogManager"]
+        ConsumerHistoryItem["HistoryItemDisplay"]
+        ConsumerComposer["Composer"]
+        ConsumerMainContent["MainContent"]
+        ConsumerNotifications["Notifications"]
+    end
+
+    %% --- Provider -> Context Connections ---
+    A -.-> CtxSession
+    A -.-> CtxVim
+    A -.-> CtxSettings
+
+    B -.-> CtxApp
+    B -.-> CtxConfig
+    B -.-> CtxUIState
+    B -.-> CtxUIActions
+    B -.-> CtxSettings
+
+    %% --- Context -> Consumer Connections ---
+    CtxSession -.-> ConsumerAppContainer
+    CtxSession -.-> ConsumerApp
+
+    CtxVim -.-> ConsumerAppContainer
+    CtxVim -.-> ConsumerComposer
+    CtxVim -.-> ConsumerApp
+
+    CtxSettings -.-> ConsumerAppContainer
+    CtxSettings -.-> ConsumerAppHeader
+    CtxSettings -.-> ConsumerDialogManager
+    CtxSettings -.-> ConsumerApp
+
+    CtxApp -.-> ConsumerAppHeader
+    CtxApp -.-> ConsumerNotifications
+
+    CtxConfig -.-> ConsumerAppHeader
+    CtxConfig -.-> ConsumerHistoryItem
+    CtxConfig -.-> ConsumerComposer
+    CtxConfig -.-> ConsumerDialogManager
+
+
+
+    CtxUIState -.-> ConsumerApp
+    CtxUIState -.-> ConsumerMainContent
+    CtxUIState -.-> ConsumerComposer
+    CtxUIState -.-> ConsumerDialogManager
+
+    CtxUIActions -.-> ConsumerComposer
+    CtxUIActions -.-> ConsumerDialogManager
+
+    %% --- Apply Styles ---
+    %% New Elements (Green)
+    class B,CtxApp,CtxConfig,CtxUIState,CtxUIActions,ConsumerAppHeader,ConsumerDialogManager,ConsumerComposer,ConsumerMainContent,ConsumerNotifications new
+
+    %% Heavily Changed Elements (Blue)
+    class A,ConsumerApp,ConsumerAppContainer,ConsumerHistoryItem changed
+
+    %% Mostly Unchanged Elements (Gray)
+    class CtxSession,CtxVim,CtxSettings unchanged
+
+    %% --- Link Styles ---
+    %% CtxSession (Red)
+    linkStyle 0,8,9 stroke:#e57373,stroke-width:2px
+    %% CtxVim (Orange)
+    linkStyle 1,10,11,12 stroke:#ffb74d,stroke-width:2px
+    %% CtxSettings (Yellow)
+    linkStyle 2,7,13,14,15,16 stroke:#fff176,stroke-width:2px
+    %% CtxApp (Green)
+    linkStyle 3,17,18 stroke:#81c784,stroke-width:2px
+    %% CtxConfig (Blue)
+    linkStyle 4,19,20,21,22 stroke:#64b5f6,stroke-width:2px
+    %% CtxUIState (Indigo)
+    linkStyle 5,23,24,25,26 stroke:#7986cb,stroke-width:2px
+    %% CtxUIActions (Violet)
+    linkStyle 6,27,28 stroke:#ba68c8,stroke-width:2px

docs/mermaid/render-path.mmd

@@ -0,0 +1,64 @@
+graph TD
+    %% --- Style Definitions ---
+    classDef new fill:#98fb98,color:#000
+    classDef changed fill:#add8e6,color:#000
+    classDef unchanged fill:#f0f0f0,color:#000
+    classDef dispatcher fill:#f9e79f,color:#000,stroke:#333,stroke-width:1px
+    classDef container fill:#f5f5f5,color:#000,stroke:#ccc
+
+    %% --- Component Tree ---
+    subgraph "Entry Point"
+      A["gemini.tsx"]
+    end
+
+    subgraph "State & Logic Wrapper"
+      B["AppContainer.tsx"]
+    end
+
+    subgraph "Primary Layout"
+      C["App.tsx"]
+    end
+
+    A -.-> B
+    B -.-> C
+
+    subgraph "UI Containers"
+        direction LR
+        C -.-> D["MainContent"]
+        C -.-> G["Composer"]
+        C -.-> F["DialogManager"]
+        C -.-> E["Notifications"]
+    end
+
+    subgraph "MainContent"
+        direction TB
+        D -.-> H["AppHeader"]
+        D -.-> I["HistoryItemDisplay"]:::dispatcher
+        D -.-> L["ShowMoreLines"]
+    end
+
+    subgraph "Composer"
+        direction TB
+        G -.-> K_Prompt["InputPrompt"]
+        G -.-> K_Footer["Footer"]
+    end
+
+    subgraph "DialogManager"
+        F -.-> J["Various Dialogs<br>(Auth, Theme, Settings, etc.)"]
+    end
+
+    %% --- Apply Styles ---
+    class B,D,E,F,G,H,J,K_Prompt,L new
+    class A,C,I changed
+    class K_Footer unchanged
+
+    %% --- Link Styles ---
+    %% MainContent Branch (Blue)
+    linkStyle 2,6,7,8 stroke:#64b5f6,stroke-width:2px
+    %% Composer Branch (Green)
+    linkStyle 3,9,10 stroke:#81c784,stroke-width:2px
+    %% DialogManager Branch (Orange)
+    linkStyle 4,11 stroke:#ffb74d,stroke-width:2px
+    %% Notifications Branch (Violet)
+    linkStyle 5 stroke:#ba68c8,stroke-width:2px
+

package-lock.json

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  type AuthType,
+  type Config,
+  getErrorMessage,
+} from '@google/gemini-cli-core';
+
+/**
+ * Handles the initial authentication flow.
+ * @param config The application config.
+ * @param authType The selected auth type.
+ * @returns An error message if authentication fails, otherwise null.
+ */
+export async function performInitialAuth(
+  config: Config,
+  authType: AuthType | undefined,
+): Promise<string | null> {
+  if (!authType) {
+    return null;
+  }
+
+  try {
+    await config.refreshAuth(authType);
+    // The console.log is intentionally left out here.
+    // We can add a dedicated startup message later if needed.
+  } catch (e) {
+    return `Failed to login. Message: ${getErrorMessage(e)}`;
+  }
+
+  return null;
+}

packages/cli/src/core/auth.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { type Config } from '@google/gemini-cli-core';
+import { type LoadedSettings } from '../config/settings.js';
+import { performInitialAuth } from './auth.js';
+import { validateTheme } from './theme.js';
+
+export interface InitializationResult {
+  authError: string | null;
+  themeError: string | null;
+  shouldOpenAuthDialog: boolean;
+  geminiMdFileCount: number;
+}
+
+/**
+ * Orchestrates the application's startup initialization.
+ * This runs BEFORE the React UI is rendered.
+ * @param config The application config.
+ * @param settings The loaded application settings.
+ * @returns The results of the initialization.
+ */
+export async function initializeApp(
+  config: Config,
+  settings: LoadedSettings,
+): Promise<InitializationResult> {
+  const authError = await performInitialAuth(
+    config,
+    settings.merged.security?.auth?.selectedType,
+  );
+  const themeError = validateTheme(settings);
+
+  const shouldOpenAuthDialog =
+    settings.merged.security?.auth?.selectedType === undefined || !!authError;
+
+  return {
+    authError,
+    themeError,
+    shouldOpenAuthDialog,
+    geminiMdFileCount: config.getGeminiMdFileCount(),
+  };
+}

packages/cli/src/core/initializer.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { themeManager } from '../ui/themes/theme-manager.js';
+import { type LoadedSettings } from '../config/settings.js';
+
+/**
+ * Validates the configured theme.
+ * @param settings The loaded application settings.
+ * @returns An error message if the theme is not found, otherwise null.
+ */
+export function validateTheme(settings: LoadedSettings): string | null {
+  const effectiveTheme = settings.merged.ui?.theme;
+  if (effectiveTheme && !themeManager.findThemeByName(effectiveTheme)) {
+    return `Theme "${effectiveTheme}" not found.`;
+  }
+  return null;
+}

packages/cli/src/core/theme.ts

@@ -195,6 +195,7 @@ describe('gemini.tsx main function kitty protocol', () => {
       getIdeMode: () => false,
       getExperimentalZedIntegration: () => false,
       getScreenReader: () => false,
+      getGeminiMdFileCount: () => 0,
     } as unknown as Config);
     vi.mocked(loadSettings).mockReturnValue({
       errors: [],
@@ -323,11 +324,19 @@ describe('startInteractiveUI', () => {
     const { render } = await import('ink');
     const renderSpy = vi.mocked(render);
 
+    const mockInitializationResult = {
+      authError: null,
+      themeError: null,
+      shouldOpenAuthDialog: false,
+      geminiMdFileCount: 0,
+    };
+
     await startInteractiveUI(
       mockConfig,
       mockSettings,
       mockStartupWarnings,
       mockWorkspaceRoot,
+      mockInitializationResult,
     );
 
     // Verify render was called with correct options
@@ -349,11 +358,19 @@ describe('startInteractiveUI', () => {
     const { checkForUpdates } = await import('./ui/utils/updateCheck.js');
     const { registerCleanup } = await import('./utils/cleanup.js');
 
+    const mockInitializationResult = {
+      authError: null,
+      themeError: null,
+      shouldOpenAuthDialog: false,
+      geminiMdFileCount: 0,
+    };
+
     await startInteractiveUI(
       mockConfig,
       mockSettings,
       mockStartupWarnings,
       mockWorkspaceRoot,
+      mockInitializationResult,
     );
 
     // Verify all startup tasks were called