feat(izui): implement IZUI state machine for transient vs active window behavior

Centralized state management for IZUI (Invocable Zoom User Interface):
- IzuiStateCoordinator manages session-based transient/active tracking
- Fixes cmd bar stuck on "group" mode when invoked transiently
- Fixes ESC from overlay showing groups instead of returning to previous app
- Transient state propagates to child windows (cmd → overlay)
- Uses isFocused() for accurate system focus detection
- KeepLive windows re-evaluate transient state on each show
- Added api.izui.* renderer API for querying state
- 54 unit tests with dependency injection for testability

Files:
- backend/electron/izui-state.ts: State coordinator singleton
- backend/electron/izui-state.test.ts: Comprehensive unit tests
- backend/electron/ipc.ts: IZUI IPC handlers, transient propagation
- backend/electron/main.ts: Window lifecycle hooks
- backend/electron/windows.ts: ESC handler integration
- preload.js: api.izui.* namespace
- extensions/cmd/panel.js: Mode display based on transient state
- docs/izui.md: Full documentation

CHANGELOG.md

···
   - Respects system theme (dark/light)
   - Only applies when page doesn't set its own background
 - [x] fix(build): exclude tmp/ agent workspaces from electron-builder
+- [x] feat(izui): implement IZUI state machine for transient vs active window behavior
+  - Centralized `IzuiStateCoordinator` manages session-based state tracking
+  - Fixes cmd bar stuck on "group" mode when invoked transiently
+  - Fixes ESC from overlay showing groups instead of returning to previous app
+  - Transient state propagates to child windows (cmd → overlay)
+  - Uses `isFocused()` for accurate system focus detection
+  - KeepLive windows re-evaluate transient state on each show
+  - Added `api.izui.*` renderer API for querying state
+  - 54 unit tests with dependency injection for testability
+  - See `docs/izui.md` for full documentation
 
 Testing
 - [x] feat(tests): add Playwright browser extension e2e tests

DEVELOPMENT.md

···
 - Windows identified by keys for lifecycle management (e.g., `peek:${address}`)
 - Modal windows use `type: 'panel'` to return focus to previous app on close
 - Parameters: `modal`, `keepLive`, `persistState`, `transparent`, `height`, `width`, `key`
-- "Escape IZUI" design - ESC key always returns to previous context
+- **IZUI State Machine** - manages transient vs active window behavior. See `docs/izui.md`
+  - **Transient**: Invoked from another app (global hotkey) - ESC closes immediately
+  - **Active**: Invoked within Peek - ESC navigates internally, never closes
+  - Transient state propagates to child windows (e.g., cmd → overlay)
+  - Use `api.izui.isTransient()` to query current session state
 
 ### Data Storage
 

backend/electron/ipc.ts

···
   getProfileSession,
 } from './session-partition.js';
 
+import {
+  getIzuiCoordinator,
+} from './izui-state.js';
+
 // ============================================================================
 // Window Focus Tracking for Window-Targeted Commands
 // ============================================================================
···
     const { url, options } = msg;
 
     // IMPORTANT: Determine transient state BEFORE creating the window
-    // A window is transient if opened when no Peek window was focused (e.g., via global hotkey)
-    // This must be checked before window creation because the new window will become focused
-    const focusedWindowBeforeCreate = BrowserWindow.getFocusedWindow();
-    const isTransient = !focusedWindowBeforeCreate || focusedWindowBeforeCreate.isDestroyed();
-    DEBUG && console.log('Transient detection:', { isTransient, focusedWindowId: focusedWindowBeforeCreate?.id });
+    // A window is transient if:
+    // 1. The current IZUI session is transient (user invoked from background), OR
+    // 2. No Peek window was focused when evaluated
+    // Check session state FIRST before evaluateOnShow() might change it
+    const coordinator = getIzuiCoordinator();
+    const sessionWasTransient = coordinator.isTransient();
+
+    // Now evaluate (this might update session state based on current focus)
+    const entryMode = coordinator.evaluateOnShow();
+
+    // Use session state if available, otherwise use evaluated state
+    const isTransient = sessionWasTransient || entryMode === 'transient';
+    DEBUG && console.log('[izui] Transient detection:', { sessionWasTransient, entryMode, isTransient });
 
     // Check if window with this key already exists
     if (options.key) {
       const existingWindow = findWindowByKey(msg.source, options.key);
       if (existingWindow) {
         DEBUG && console.log('Reusing existing window with key:', options.key);
+
+        // RE-EVALUATE transient state on show, not just creation
+        // This fixes keepLive windows (like cmd bar) being stuck with stale transient state
+        const coordinator = getIzuiCoordinator();
+        const newTransientState = coordinator.evaluateOnShow();
+        const existingData = existingWindow.data as { params: Record<string, unknown> };
+        existingData.params.transient = (newTransientState === 'transient');
+        DEBUG && console.log('Reused window transient re-evaluated:', newTransientState);
+
         if (!isHeadless()) {
           existingWindow.window.show();
         }
···
   ipcMain.handle('get-window-id', (ev) => {
     const win = BrowserWindow.fromWebContents(ev.sender);
     return win ? win.id : null;
+  });
+
+  // Check if current window is transient (opened when app wasn't focused)
+  // Used for IZUI policy: transient windows have different escape/mode behavior
+  ipcMain.handle('window-is-transient', (ev) => {
+    const win = BrowserWindow.fromWebContents(ev.sender);
+    if (!win) return false;
+    const windowData = getWindowInfo(win.id);
+    return windowData?.params?.transient === true;
+  });
+
+  // ============================================================================
+  // IZUI State Coordinator IPC Handlers
+  // ============================================================================
+  // Centralized IZUI state management for consistent transient detection,
+  // mode display, and ESC behavior across all windows.
+
+  // Check if IZUI session is in transient mode (app wasn't focused when invoked)
+  // Re-evaluates at query time, excluding the requesting window from focus check
+  // (since the cmd window itself has focus by the time it asks this question)
+  ipcMain.handle('izui-is-transient', (ev) => {
+    const coordinator = getIzuiCoordinator();
+    const requestingWindow = BrowserWindow.fromWebContents(ev.sender);
+    // Re-evaluate excluding the requesting window
+    const entryMode = coordinator.evaluateOnShow(requestingWindow?.id);
+    const result = entryMode === 'transient';
+    DEBUG && console.log('[izui] izui-is-transient:', result, 'windowId:', requestingWindow?.id);
+    return result;
+  });
+
+  // Get the effective mode for display
+  // Returns 'default' for transient sessions, 'active' otherwise (caller resolves actual mode)
+  ipcMain.handle('izui-get-effective-mode', () => {
+    const coordinator = getIzuiCoordinator();
+    return coordinator.getEffectiveMode();
+  });
+
+  // Get the current IZUI state (idle, transient, active, overlay)
+  ipcMain.handle('izui-get-state', () => {
+    const coordinator = getIzuiCoordinator();
+    return coordinator.getState();
   });
 
   // Get window position

backend/electron/izui-state.test.ts

···
+/**
+ * Unit tests for IZUI State Coordinator
+ * Tests the state machine managing transient vs active state for windows
+ *
+ * Key behaviors tested:
+ * - Transient detection based on window focus
+ * - Session lifecycle management
+ * - Window stack management
+ * - Overlay mode
+ * - Focus tracking
+ */
+
+import { describe, it, before, beforeEach } from 'node:test';
+import * as assert from 'node:assert';
+import type { WindowProvider } from './izui-state.js';
+
+// Mock window interface
+interface MockWindow {
+  id: number;
+  _destroyed: boolean;
+  _focused: boolean;
+  _visible: boolean;
+  isDestroyed: () => boolean;
+  isFocused: () => boolean;
+  show: () => void;
+}
+
+function createMockWindow(id: number, options: { focused?: boolean; destroyed?: boolean } = {}): MockWindow {
+  const win: MockWindow = {
+    id,
+    _destroyed: options.destroyed ?? false,
+    _focused: options.focused ?? false,
+    _visible: true,
+    isDestroyed: function() { return this._destroyed; },
+    isFocused: function() { return this._focused; },
+    show: function() { this._visible = true; },
+  };
+  return win;
+}
+
+// Create a mock window provider for testing
+function createMockWindowProvider(windows: MockWindow[]): WindowProvider {
+  return {
+    getAllWindows: () => windows,
+    fromId: (id: number) => windows.find(w => w.id === id) || null,
+  };
+}
+
+// Import will be done after build
+let izuiState: typeof import('./izui-state.js');
+
+describe('IZUI State Coordinator Tests', () => {
+  let mockWindows: MockWindow[];
+
+  before(async () => {
+    // Dynamic import of the compiled module
+    izuiState = await import('./izui-state.js');
+  });
+
+  beforeEach(() => {
+    // Clear mock windows before each test
+    mockWindows = [];
+    // End any existing session and reset window provider
+    const coordinator = izuiState.getIzuiCoordinator();
+    coordinator.endSession();
+    coordinator._setWindowProvider(createMockWindowProvider(mockWindows));
+  });
+
+  describe('evaluateOnShow', () => {
+    it('should return transient when no window has system focus', () => {
+      // Add unfocused windows
+      mockWindows.push(createMockWindow(1, { focused: false }));
+      mockWindows.push(createMockWindow(2, { focused: false }));
+
+      const coordinator = izuiState.getIzuiCoordinator();
+      const result = coordinator.evaluateOnShow();
+
+      assert.strictEqual(result, 'transient');
+    });
+
+    it('should return active when a window has system focus', () => {
+      // Add one focused window
+      mockWindows.push(createMockWindow(1, { focused: true }));
+      mockWindows.push(createMockWindow(2, { focused: false }));
+
+      const coordinator = izuiState.getIzuiCoordinator();
+      const result = coordinator.evaluateOnShow();
+
+      assert.strictEqual(result, 'active');
+    });
+
+    it('should correctly exclude the specified windowId from focus check', () => {
+      // The querying window (cmd panel) is focused, but should be excluded
+      const cmdPanelId = 100;
+      mockWindows.push(createMockWindow(cmdPanelId, { focused: true }));
+      mockWindows.push(createMockWindow(2, { focused: false }));
+
+      const coordinator = izuiState.getIzuiCoordinator();
+      const result = coordinator.evaluateOnShow(cmdPanelId);
+
+      // Should be transient because the only focused window is excluded
+      assert.strictEqual(result, 'transient');
+    });
+
+    it('should return active when another window has focus besides excluded one', () => {
+      const cmdPanelId = 100;
+      mockWindows.push(createMockWindow(cmdPanelId, { focused: true }));
+      mockWindows.push(createMockWindow(2, { focused: true })); // Another focused window
+
+      const coordinator = izuiState.getIzuiCoordinator();
+      const result = coordinator.evaluateOnShow(cmdPanelId);
+
+      // Should be active because window 2 has focus
+      assert.strictEqual(result, 'active');
+    });
+
+    it('should ignore destroyed windows in focus check', () => {
+      // Only window is focused but destroyed
+      mockWindows.push(createMockWindow(1, { focused: true, destroyed: true }));
+      mockWindows.push(createMockWindow(2, { focused: false }));
+
+      const coordinator = izuiState.getIzuiCoordinator();
+      const result = coordinator.evaluateOnShow();
+
+      // Destroyed focused window should be ignored, result is transient
+      assert.strictEqual(result, 'transient');
+    });
+
+    it('should update session.entryMode when called', () => {
+      mockWindows.push(createMockWindow(1, { focused: false }));
+
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.evaluateOnShow();
+
+      const session = coordinator.getSession();
+      assert.ok(session, 'Session should exist');
+      assert.strictEqual(session!.entryMode, 'transient');
+    });
+
+    it('should start a session if none exists', () => {
+      mockWindows.push(createMockWindow(1, { focused: true }));
+
+      const coordinator = izuiState.getIzuiCoordinator();
+      assert.strictEqual(coordinator.getSession(), null, 'No session should exist initially');
+
+      coordinator.evaluateOnShow();
+
+      assert.ok(coordinator.getSession(), 'Session should be created');
+    });
+
+    it('should update existing session entry mode without creating new session', () => {
+      mockWindows.push(createMockWindow(1, { focused: true }));
+
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      const originalSessionId = coordinator.getSession()!.id;
+
+      // Now simulate no focus
+      mockWindows[0]._focused = false;
+      coordinator.evaluateOnShow();
+
+      const session = coordinator.getSession();
+      assert.strictEqual(session!.id, originalSessionId, 'Should be same session');
+      assert.strictEqual(session!.entryMode, 'transient', 'Entry mode should be updated');
+    });
+  });
+
+  describe('isTransient', () => {
+    it('should return false when no session exists', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      assert.strictEqual(coordinator.isTransient(), false);
+    });
+
+    it('should return true when session.entryMode is transient', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('transient');
+      assert.strictEqual(coordinator.isTransient(), true);
+    });
+
+    it('should return false when session.entryMode is active', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      assert.strictEqual(coordinator.isTransient(), false);
+    });
+
+    it('should persist transient state even after windows open', () => {
+      mockWindows.push(createMockWindow(1, { focused: false }));
+
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.evaluateOnShow(); // Starts as transient
+      coordinator.pushWindow(1);
+
+      // Add another window
+      mockWindows.push(createMockWindow(2, { focused: false }));
+      coordinator.pushWindow(2);
+
+      // Session should still be transient
+      assert.strictEqual(coordinator.isTransient(), true);
+    });
+  });
+
+  describe('startSession and endSession', () => {
+    it('should create a new session with startSession', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+
+      const session = coordinator.getSession();
+      assert.ok(session, 'Session should exist');
+      assert.ok(session!.id.startsWith('izui-'), 'Session ID should have correct prefix');
+      assert.strictEqual(session!.entryMode, 'active');
+      assert.deepStrictEqual(session!.windowStack, []);
+      assert.strictEqual(session!.overlayWindowId, null);
+      assert.deepStrictEqual(session!.hiddenWindowIds, []);
+      assert.strictEqual(session!.focusedWindowId, null);
+    });
+
+    it('should not create a new session if one already exists', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      const firstSessionId = coordinator.getSession()!.id;
+
+      coordinator.startSession('transient'); // Should be ignored
+
+      assert.strictEqual(coordinator.getSession()!.id, firstSessionId);
+      assert.strictEqual(coordinator.getSession()!.entryMode, 'active'); // Not changed to transient
+    });
+
+    it('should clear session with endSession', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      assert.ok(coordinator.getSession());
+
+      coordinator.endSession();
+
+      assert.strictEqual(coordinator.getSession(), null);
+      assert.strictEqual(coordinator.getState(), 'idle');
+    });
+
+    it('should handle endSession when no session exists', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      // Should not throw
+      coordinator.endSession();
+      assert.strictEqual(coordinator.getSession(), null);
+    });
+
+    it('should set state to entryMode when starting session', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+
+      coordinator.startSession('transient');
+      assert.strictEqual(coordinator.getState(), 'transient');
+
+      coordinator.endSession();
+
+      coordinator.startSession('active');
+      assert.strictEqual(coordinator.getState(), 'active');
+    });
+  });
+
+  describe('pushWindow and popWindow', () => {
+    it('should add window to stack with pushWindow', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+
+      coordinator.pushWindow(1);
+      coordinator.pushWindow(2);
+
+      const session = coordinator.getSession()!;
+      assert.deepStrictEqual(session.windowStack, [1, 2]);
+    });
+
+    it('should not add duplicate windows to stack', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+
+      coordinator.pushWindow(1);
+      coordinator.pushWindow(1); // Duplicate
+
+      const session = coordinator.getSession()!;
+      assert.deepStrictEqual(session.windowStack, [1]);
+    });
+
+    it('should not add window without active session', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      // No session started
+      coordinator.pushWindow(1);
+
+      // Should not throw, but also no session to verify
+      assert.strictEqual(coordinator.getSession(), null);
+    });
+
+    it('should remove window from stack with popWindow', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      coordinator.pushWindow(1);
+      coordinator.pushWindow(2);
+      coordinator.pushWindow(3);
+
+      coordinator.popWindow(2);
+
+      const session = coordinator.getSession()!;
+      assert.deepStrictEqual(session.windowStack, [1, 3]);
+    });
+
+    it('should auto-end session when stack becomes empty', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      coordinator.pushWindow(1);
+      coordinator.pushWindow(2);
+
+      coordinator.popWindow(1);
+      assert.ok(coordinator.getSession(), 'Session should still exist');
+
+      coordinator.popWindow(2);
+      assert.strictEqual(coordinator.getSession(), null, 'Session should end when stack is empty');
+      assert.strictEqual(coordinator.getState(), 'idle');
+    });
+
+    it('should handle popping non-existent window', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      coordinator.pushWindow(1);
+
+      // Pop window that's not in stack - should not throw
+      coordinator.popWindow(99);
+
+      const session = coordinator.getSession()!;
+      assert.deepStrictEqual(session.windowStack, [1]);
+    });
+
+    it('should handle popWindow without session', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      // No session - should not throw
+      coordinator.popWindow(1);
+      assert.strictEqual(coordinator.getSession(), null);
+    });
+  });
+
+  describe('enterOverlay and exitOverlay', () => {
+    it('should enter overlay mode', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+
+      coordinator.enterOverlay(100, [1, 2, 3]);
+
+      assert.strictEqual(coordinator.getState(), 'overlay');
+      assert.strictEqual(coordinator.isOverlay(), true);
+
+      const session = coordinator.getSession()!;
+      assert.strictEqual(session.overlayWindowId, 100);
+      assert.deepStrictEqual(session.hiddenWindowIds, [1, 2, 3]);
+    });
+
+    it('should not enter overlay without active session', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      // No session
+
+      coordinator.enterOverlay(100, [1, 2, 3]);
+
+      assert.strictEqual(coordinator.isOverlay(), false);
+      assert.strictEqual(coordinator.getState(), 'idle');
+    });
+
+    it('should exit overlay mode and restore hidden windows', () => {
+      // Set up mock windows that will be "hidden"
+      const hiddenWindow1 = createMockWindow(1);
+      const hiddenWindow2 = createMockWindow(2);
+      hiddenWindow1._visible = false;
+      hiddenWindow2._visible = false;
+      mockWindows.push(hiddenWindow1, hiddenWindow2);
+
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      coordinator.enterOverlay(100, [1, 2]);
+
+      coordinator.exitOverlay();
+
+      assert.strictEqual(coordinator.isOverlay(), false);
+      assert.strictEqual(coordinator.getState(), 'active');
+      assert.ok(hiddenWindow1._visible, 'Window 1 should be shown');
+      assert.ok(hiddenWindow2._visible, 'Window 2 should be shown');
+
+      const session = coordinator.getSession()!;
+      assert.strictEqual(session.overlayWindowId, null);
+      assert.deepStrictEqual(session.hiddenWindowIds, []);
+    });
+
+    it('should return to transient state after overlay if session was transient', () => {
+      mockWindows.push(createMockWindow(1));
+
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('transient');
+      coordinator.enterOverlay(100, [1]);
+
+      assert.strictEqual(coordinator.getState(), 'overlay');
+
+      coordinator.exitOverlay();
+
+      assert.strictEqual(coordinator.getState(), 'transient');
+    });
+
+    it('should not exit overlay when not in overlay mode', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      // Not in overlay mode
+
+      coordinator.exitOverlay(); // Should not throw
+
+      assert.strictEqual(coordinator.getState(), 'active');
+    });
+
+    it('should handle exitOverlay with no session', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      // No session
+
+      coordinator.exitOverlay(); // Should not throw
+
+      assert.strictEqual(coordinator.getSession(), null);
+    });
+
+    it('should not restore destroyed windows on exitOverlay', () => {
+      const destroyedWindow = createMockWindow(1, { destroyed: true });
+      destroyedWindow._visible = false;
+      mockWindows.push(destroyedWindow);
+
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      coordinator.enterOverlay(100, [1]);
+
+      coordinator.exitOverlay();
+
+      // Destroyed window should not have show() called (and therefore still not visible)
+      assert.strictEqual(destroyedWindow._visible, false);
+    });
+  });
+
+  describe('isOverlay', () => {
+    it('should return false when not in overlay mode', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      assert.strictEqual(coordinator.isOverlay(), false);
+
+      coordinator.startSession('active');
+      assert.strictEqual(coordinator.isOverlay(), false);
+    });
+
+    it('should return true when in overlay mode', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      coordinator.enterOverlay(100, []);
+
+      assert.strictEqual(coordinator.isOverlay(), true);
+    });
+  });
+
+  describe('setFocusedWindow and clearFocusedWindow', () => {
+    it('should track focused window in session', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+
+      coordinator.setFocusedWindow(42);
+
+      const session = coordinator.getSession()!;
+      assert.strictEqual(session.focusedWindowId, 42);
+    });
+
+    it('should update focused window', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+
+      coordinator.setFocusedWindow(1);
+      coordinator.setFocusedWindow(2);
+
+      const session = coordinator.getSession()!;
+      assert.strictEqual(session.focusedWindowId, 2);
+    });
+
+    it('should not crash when setting focused window without session', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      // No session
+      coordinator.setFocusedWindow(1); // Should not throw
+    });
+
+    it('should clear focused window if it matches', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      coordinator.setFocusedWindow(42);
+
+      coordinator.clearFocusedWindow(42);
+
+      const session = coordinator.getSession()!;
+      assert.strictEqual(session.focusedWindowId, null);
+    });
+
+    it('should not clear focused window if it does not match', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      coordinator.setFocusedWindow(42);
+
+      coordinator.clearFocusedWindow(99); // Different ID
+
+      const session = coordinator.getSession()!;
+      assert.strictEqual(session.focusedWindowId, 42); // Unchanged
+    });
+
+    it('should not crash when clearing focused window without session', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      // No session
+      coordinator.clearFocusedWindow(1); // Should not throw
+    });
+
+    it('should return focused window ID via getFocusedWindowId', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      coordinator.setFocusedWindow(123);
+
+      assert.strictEqual(coordinator.getFocusedWindowId(), 123);
+    });
+
+    it('should return null from getFocusedWindowId when no session', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      assert.strictEqual(coordinator.getFocusedWindowId(), null);
+    });
+  });
+
+  describe('getState', () => {
+    it('should return idle initially', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.endSession(); // Ensure clean state
+      assert.strictEqual(coordinator.getState(), 'idle');
+    });
+
+    it('should return active when session started as active', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      assert.strictEqual(coordinator.getState(), 'active');
+    });
+
+    it('should return transient when session started as transient', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('transient');
+      assert.strictEqual(coordinator.getState(), 'transient');
+    });
+
+    it('should return overlay when in overlay mode', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      coordinator.enterOverlay(1, []);
+      assert.strictEqual(coordinator.getState(), 'overlay');
+    });
+
+    it('should return idle after session ends', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+      coordinator.endSession();
+      assert.strictEqual(coordinator.getState(), 'idle');
+    });
+  });
+
+  describe('getEffectiveMode', () => {
+    it('should return default for transient sessions', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('transient');
+
+      assert.strictEqual(coordinator.getEffectiveMode(), 'default');
+    });
+
+    it('should return active for active sessions', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      coordinator.startSession('active');
+
+      assert.strictEqual(coordinator.getEffectiveMode(), 'active');
+    });
+
+    it('should return active when no session (isTransient returns false)', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+      // No session - isTransient() returns false, so this returns 'active'
+      assert.strictEqual(coordinator.getEffectiveMode(), 'active');
+    });
+  });
+
+  describe('Session persistence across windows', () => {
+    it('should maintain transient mode when opening windows from transient session', () => {
+      // Simulate: user invokes cmd bar via global hotkey (no window focused)
+      mockWindows.push(createMockWindow(1, { focused: false }));
+
+      const coordinator = izuiState.getIzuiCoordinator();
+
+      // Cmd bar evaluates on show - detects transient
+      const entryMode = coordinator.evaluateOnShow();
+      assert.strictEqual(entryMode, 'transient');
+
+      // User opens a window from cmd bar
+      coordinator.pushWindow(100);
+
+      // Session is still transient
+      assert.strictEqual(coordinator.isTransient(), true);
+
+      // User opens another window from that window
+      coordinator.pushWindow(101);
+
+      // Session is still transient
+      assert.strictEqual(coordinator.isTransient(), true);
+
+      // ESC should close everything in transient mode
+      // (behavior tested in integration, but state persists)
+      assert.strictEqual(coordinator.getSession()!.entryMode, 'transient');
+    });
+
+    it('should maintain active mode when user is working within app', () => {
+      // Simulate: user is working in a Peek window, opens cmd bar
+      mockWindows.push(createMockWindow(50, { focused: true })); // User's active window
+
+      const coordinator = izuiState.getIzuiCoordinator();
+
+      // Cmd bar evaluates on show - detects active (window 50 is focused)
+      const entryMode = coordinator.evaluateOnShow(100); // Exclude cmd bar itself
+      assert.strictEqual(entryMode, 'active');
+
+      coordinator.pushWindow(100); // cmd bar
+
+      // Session is active
+      assert.strictEqual(coordinator.isTransient(), false);
+
+      // User opens a window from cmd bar
+      coordinator.pushWindow(200);
+
+      // Session is still active
+      assert.strictEqual(coordinator.isTransient(), false);
+    });
+  });
+
+  describe('Complex workflow scenarios', () => {
+    it('should handle full transient workflow: invoke, pick, close', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+
+      // 1. No windows focused - user invokes via global hotkey
+      mockWindows.push(createMockWindow(1, { focused: false }));
+
+      // 2. Cmd bar opens and evaluates state
+      const entryMode = coordinator.evaluateOnShow();
+      assert.strictEqual(entryMode, 'transient');
+      coordinator.pushWindow(10); // cmd bar window
+
+      // 3. User triggers windows picker (overlay)
+      const hiddenWindow = createMockWindow(10);
+      hiddenWindow._visible = false;
+      mockWindows.length = 0;
+      mockWindows.push(hiddenWindow);
+
+      coordinator.enterOverlay(20, [10]);
+      assert.strictEqual(coordinator.isOverlay(), true);
+      assert.strictEqual(coordinator.isTransient(), true); // Still transient at entry
+
+      // 4. User presses ESC - exit overlay
+      coordinator.exitOverlay();
+      assert.strictEqual(coordinator.isOverlay(), false);
+      assert.ok(hiddenWindow._visible, 'Cmd bar should be shown again');
+
+      // 5. User presses ESC again - close everything (in transient mode)
+      coordinator.popWindow(10);
+      assert.strictEqual(coordinator.getSession(), null);
+      assert.strictEqual(coordinator.getState(), 'idle');
+    });
+
+    it('should handle full active workflow: work, invoke, navigate back', () => {
+      const coordinator = izuiState.getIzuiCoordinator();
+
+      // 1. User has an active Peek window
+      mockWindows.push(createMockWindow(50, { focused: true }));
+      coordinator.startSession('active');
+      coordinator.pushWindow(50);
+
+      // 2. User invokes cmd bar (window 50 still focused initially)
+      const entryMode = coordinator.evaluateOnShow(100); // Exclude cmd bar
+      assert.strictEqual(entryMode, 'active');
+      coordinator.pushWindow(100);
+
+      // 3. User types and selects something, opening new window
+      coordinator.pushWindow(200);
+
+      // 4. ESC in active mode just navigates, doesn't close
+      // (state remains active)
+      assert.strictEqual(coordinator.isTransient(), false);
+      assert.strictEqual(coordinator.getState(), 'active');
+
+      // 5. User manually closes windows one by one
+      coordinator.popWindow(200);
+      assert.ok(coordinator.getSession());
+
+      coordinator.popWindow(100);
+      assert.ok(coordinator.getSession());
+
+      coordinator.popWindow(50);
+      // Session ends when last window closes
+      assert.strictEqual(coordinator.getSession(), null);
+    });
+  });
+
+  describe('getIzuiCoordinator singleton', () => {
+    it('should return the same instance', () => {
+      const coordinator1 = izuiState.getIzuiCoordinator();
+      const coordinator2 = izuiState.getIzuiCoordinator();
+      assert.strictEqual(coordinator1, coordinator2);
+    });
+  });
+});

backend/electron/izui-state.ts

···
+/**
+ * IZUI State Coordinator
+ *
+ * Centralized state machine for managing IZUI (Invocable Zoom User Interface) states.
+ * See docs/izui.md for comprehensive documentation.
+ *
+ * Problems solved:
+ * - Transient state frozen at creation for keepLive windows
+ * - No session concept for unified state
+ * - Stale focus trackers never cleaned up
+ *
+ * States:
+ * - IDLE: No visible windows, app in background
+ * - TRANSIENT: Invoked via global hotkey while unfocused
+ * - ACTIVE: User working within focused Peek windows
+ * - OVERLAY: Full-screen overlay (windows picker)
+ *
+ * Key Rules:
+ * | State     | Mode Display          | ESC Behavior                    |
+ * |-----------|----------------------|--------------------------------|
+ * | TRANSIENT | Always "default"     | Close immediately              |
+ * | ACTIVE    | Target window's mode | Internal nav only, never close |
+ * | OVERLAY   | Inherit from previous| Always close, restore hidden   |
+ */
+
+import { DEBUG } from './config.js';
+
+// Lazy-load Electron modules to allow testing without Electron
+let BrowserWindow: typeof import('electron').BrowserWindow | null = null;
+
+try {
+  const electron = await import('electron');
+  BrowserWindow = electron.BrowserWindow;
+} catch {
+  // Electron not available (e.g., in unit tests)
+  DEBUG && console.log('[izui-state] Running without Electron (test mode)');
+}
+
+export type IzuiState = 'idle' | 'transient' | 'active' | 'overlay';
+
+/**
+ * Window provider interface for dependency injection (enables testing)
+ */
+export interface WindowProvider {
+  getAllWindows(): Array<{ id: number; isDestroyed(): boolean; isFocused(): boolean }>;
+  fromId(id: number): { show(): void; isDestroyed(): boolean } | null;
+}
+
+/**
+ * Default window provider using Electron's BrowserWindow (or stub for testing)
+ */
+const defaultWindowProvider: WindowProvider = {
+  getAllWindows: () => BrowserWindow?.getAllWindows() ?? [],
+  fromId: (id: number) => BrowserWindow?.fromId(id) ?? null,
+};
+
+export interface IzuiSession {
+  id: string;
+  entryMode: 'active' | 'transient';
+  windowStack: number[];
+  overlayWindowId: number | null;
+  hiddenWindowIds: number[];
+  focusedWindowId: number | null;
+}
+
+/**
+ * Generate a unique session ID
+ */
+function generateSessionId(): string {
+  return `izui-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * IZUI State Coordinator singleton
+ */
+class IzuiStateCoordinator {
+  private state: IzuiState = 'idle';
+  private session: IzuiSession | null = null;
+  private windowProvider: WindowProvider = defaultWindowProvider;
+
+  /**
+   * Set custom window provider (for testing)
+   */
+  _setWindowProvider(provider: WindowProvider): void {
+    this.windowProvider = provider;
+  }
+
+  /**
+   * Reset to default window provider
+   */
+  _resetWindowProvider(): void {
+    this.windowProvider = defaultWindowProvider;
+  }
+
+  /**
+   * Start a new IZUI session when the first window opens
+   * @param entryMode How the session was started (active if app was focused, transient if not)
+   */
+  startSession(entryMode: 'active' | 'transient'): void {
+    if (this.session) {
+      DEBUG && console.log('[izui] Session already active, not starting new one');
+      return;
+    }
+
+    this.session = {
+      id: generateSessionId(),
+      entryMode,
+      windowStack: [],
+      overlayWindowId: null,
+      hiddenWindowIds: [],
+      focusedWindowId: null,
+    };
+
+    this.state = entryMode;
+    DEBUG && console.log('[izui] Started session:', this.session.id, 'entryMode:', entryMode);
+  }
+
+  /**
+   * End the current IZUI session when the last window closes
+   */
+  endSession(): void {
+    if (!this.session) {
+      DEBUG && console.log('[izui] No session to end');
+      return;
+    }
+
+    DEBUG && console.log('[izui] Ending session:', this.session.id);
+    this.session = null;
+    this.state = 'idle';
+  }
+
+  /**
+   * Re-evaluate transient state when a window is shown (for keepLive windows)
+   * This is the key fix for the cmd bar stuck on "group" mode issue.
+   * When a keepLive window is reused, we need to re-check if the app
+   * was focused when it was invoked.
+   *
+   * IMPORTANT: BrowserWindow.getFocusedWindow() returns Electron's internally
+   * tracked "focused window" which persists even when the app loses system focus.
+   * Instead, we check if ANY window actually has system focus via isFocused().
+   *
+   * @param excludeWindowId Optional window ID to exclude from focus check
+   *        (used when the querying window is already visible/focused)
+   * @returns 'active' if a Peek window has system focus, 'transient' if not
+   */
+  evaluateOnShow(excludeWindowId?: number): 'active' | 'transient' {
+    // Check if ANY Peek window currently has actual system focus
+    // Don't use getFocusedWindow() - it returns internal tracking, not system focus
+    // Exclude the specified window (e.g., the cmd window asking if it's transient)
+    const allWindows = this.windowProvider.getAllWindows();
+
+    const focusedWindow = allWindows.find(win =>
+      !win.isDestroyed() &&
+      win.isFocused() &&
+      win.id !== excludeWindowId
+    );
+    const hasActiveFocus = !!focusedWindow;
+
+    const result = hasActiveFocus ? 'active' : 'transient';
+    DEBUG && console.log('[izui] evaluateOnShow:', result, 'excludeWindowId:', excludeWindowId, 'focusedWindowId:', focusedWindow?.id);
+
+    // If we don't have a session, start one with the detected mode
+    if (!this.session) {
+      this.startSession(result);
+    } else {
+      // Update the session's entry mode for this invocation
+      this.session.entryMode = result;
+      this.state = result === 'transient' ? 'transient' : (this.state === 'overlay' ? 'overlay' : 'active');
+    }
+
+    return result;
+  }
+
+  /**
+   * Enter overlay mode (e.g., windows picker)
+   * @param windowId The overlay window's ID
+   * @param hiddenIds IDs of windows that were hidden for the overlay
+   */
+  enterOverlay(windowId: number, hiddenIds: number[]): void {
+    if (!this.session) {
+      DEBUG && console.log('[izui] Cannot enter overlay without active session');
+      return;
+    }
+
+    this.state = 'overlay';
+    this.session.overlayWindowId = windowId;
+    this.session.hiddenWindowIds = hiddenIds;
+    DEBUG && console.log('[izui] Entered overlay mode, windowId:', windowId, 'hidden:', hiddenIds.length);
+  }
+
+  /**
+   * Exit overlay mode and restore hidden windows
+   */
+  exitOverlay(): void {
+    if (!this.session || this.state !== 'overlay') {
+      DEBUG && console.log('[izui] Not in overlay mode');
+      return;
+    }
+
+    const hiddenIds = this.session.hiddenWindowIds;
+    DEBUG && console.log('[izui] Exiting overlay, restoring', hiddenIds.length, 'windows');
+
+    // Restore hidden windows
+    for (const id of hiddenIds) {
+      const win = this.windowProvider.fromId(id);
+      if (win && !win.isDestroyed()) {
+        win.show();
+      }
+    }
+
+    // Return to previous state based on entry mode
+    this.state = this.session.entryMode;
+    this.session.overlayWindowId = null;
+    this.session.hiddenWindowIds = [];
+  }
+
+  /**
+   * Track when a window gains focus
+   * @param windowId The window that gained focus
+   */
+  setFocusedWindow(windowId: number): void {
+    if (this.session) {
+      this.session.focusedWindowId = windowId;
+    }
+    DEBUG && console.log('[izui] Focused window set:', windowId);
+  }
+
+  /**
+   * Clear focus tracking when a window closes or loses focus
+   * This prevents stale window IDs from being tracked
+   * @param windowId The window to clear
+   */
+  clearFocusedWindow(windowId: number): void {
+    if (this.session && this.session.focusedWindowId === windowId) {
+      this.session.focusedWindowId = null;
+      DEBUG && console.log('[izui] Cleared focused window:', windowId);
+    }
+  }
+
+  /**
+   * Add a window to the session's window stack
+   * @param windowId The window to add
+   */
+  pushWindow(windowId: number): void {
+    if (!this.session) {
+      DEBUG && console.log('[izui] Cannot push window without active session');
+      return;
+    }
+
+    if (!this.session.windowStack.includes(windowId)) {
+      this.session.windowStack.push(windowId);
+      DEBUG && console.log('[izui] Pushed window:', windowId, 'stack size:', this.session.windowStack.length);
+    }
+  }
+
+  /**
+   * Remove a window from the session's window stack
+   * If this was the last window, end the session
+   * @param windowId The window to remove
+   */
+  popWindow(windowId: number): void {
+    if (!this.session) {
+      return;
+    }
+
+    const index = this.session.windowStack.indexOf(windowId);
+    if (index !== -1) {
+      this.session.windowStack.splice(index, 1);
+      DEBUG && console.log('[izui] Popped window:', windowId, 'remaining:', this.session.windowStack.length);
+    }
+
+    // End session if no more windows
+    if (this.session.windowStack.length === 0) {
+      this.endSession();
+    }
+  }
+
+  /**
+   * Check if currently in transient mode
+   * This is the primary query for determining mode display and ESC behavior
+   */
+  isTransient(): boolean {
+    if (!this.session) {
+      return false;
+    }
+    // Transient means opened without app focus
+    return this.session.entryMode === 'transient';
+  }
+
+  /**
+   * Get the current IZUI state
+   */
+  getState(): IzuiState {
+    return this.state;
+  }
+
+  /**
+   * Get the current session info (for debugging)
+   */
+  getSession(): IzuiSession | null {
+    return this.session;
+  }
+
+  /**
+   * Get the effective mode for display
+   * @param targetWindowId Optional window to get mode for
+   * @returns 'default' for transient sessions, actual mode otherwise
+   */
+  getEffectiveMode(targetWindowId?: number): string {
+    // In transient mode, always show "default"
+    if (this.isTransient()) {
+      return 'default';
+    }
+
+    // For active sessions, return the window's actual mode
+    // This will be resolved by the caller using the context API
+    return 'active';
+  }
+
+  /**
+   * Check if currently in overlay mode
+   */
+  isOverlay(): boolean {
+    return this.state === 'overlay';
+  }
+
+  /**
+   * Get the focused window ID from the session
+   */
+  getFocusedWindowId(): number | null {
+    return this.session?.focusedWindowId ?? null;
+  }
+}
+
+// Singleton instance
+const coordinator = new IzuiStateCoordinator();
+
+/**
+ * Get the IZUI State Coordinator singleton
+ */
+export function getIzuiCoordinator(): IzuiStateCoordinator {
+  return coordinator;
+}
+
+export { IzuiStateCoordinator };

backend/electron/main.ts

···
 import { APP_DEF_WIDTH, APP_DEF_HEIGHT, WEB_CORE_ADDRESS, getPreloadPath, isTestProfile, isDevProfile, isHeadless, getProfile, DEBUG } from './config.js';
 import { addEscHandler, winDevtoolsConfig, closeOrHideWindow, getSystemThemeBackgroundColor, getPrefs } from './windows.js';
 import { getProfileSession, getPartitionString, getCurrentProfileId } from './session-partition.js';
+import { getIzuiCoordinator } from './izui-state.js';
 
 // Configuration
 export interface AppConfig {
···
     window.on('closed', () => {
       const windowData = windowRegistry.get(windowId);
 
+      // Clean up IZUI coordinator state
+      const coordinator = getIzuiCoordinator();
+      coordinator.clearFocusedWindow(windowId);
+      coordinator.popWindow(windowId);
+
       if (windowData) {
         // If this was an overlay window, restore the windows that were hidden
+        // BUT: In transient mode, don't restore - just close and return to previous app
+        // Use the window's own transient param (not coordinator - session may be ended by popWindow)
         const hiddenWindowIds = windowData.params.overlayHiddenWindows as number[] | undefined;
-        if (hiddenWindowIds && hiddenWindowIds.length > 0) {
-          DEBUG && console.log('Overlay closed, restoring', hiddenWindowIds.length, 'windows');
+        const isTransient = windowData.params.transient === true;
+        if (hiddenWindowIds && hiddenWindowIds.length > 0 && !isTransient) {
+          DEBUG && console.log('[izui] Overlay closed (active mode), restoring', hiddenWindowIds.length, 'windows');
           for (const hiddenId of hiddenWindowIds) {
             const hiddenWin = BrowserWindow.fromId(hiddenId);
             if (hiddenWin && !hiddenWin.isDestroyed()) {
               hiddenWin.show();
             }
           }
+        } else if (isTransient && hiddenWindowIds && hiddenWindowIds.length > 0) {
+          DEBUG && console.log('[izui] Overlay closed in transient mode - not restoring', hiddenWindowIds.length, 'windows');
         }
 
         publish(windowData.source, scopes.GLOBAL, 'window:closed', {

backend/electron/windows.ts

···
   getChildWindows,
 } from './main.js';
 
+import {
+  getIzuiCoordinator,
+} from './izui-state.js';
+
 /**
  * Get the appropriate background color based on system theme
  * This helps prevent the "white flash" when opening windows in dark mode
···
 
       // For 'auto' mode, check if transient (no focused window when opened)
       if (escapeMode === 'auto') {
-        if (params.transient) {
-          // Transient mode - close immediately (user invoked via global hotkey)
-          console.log('[esc] Auto mode (transient) - closing directly');
+        // Use IZUI coordinator for consistent state management
+        const coordinator = getIzuiCoordinator();
+        const isCoordinatorOverlay = coordinator.isOverlay();
+
+        // Overlay windows always close on ESC (they're full-screen temporary views)
+        const isOverlay = isCoordinatorOverlay || params.overlay === true || params.overlayHiddenWindows;
+
+        // Check transient from coordinator (re-evaluated) or window params (fallback)
+        const isTransient = coordinator.isTransient() || params.transient === true;
+
+        if (isTransient || isOverlay) {
+          // Transient mode or overlay - close immediately
+          console.log('[esc] Auto mode (transient or overlay) - closing directly, coordinator.isTransient:', coordinator.isTransient());
         } else {
           // Active mode (Peek was focused when window opened)
           // IZUI Policy: ESC only navigates internal state, does NOT close

docs/api.md

···
 - [Commands (Command Palette)](#commands-command-palette)
 - [Theme](#theme)
 - [Escape Handling](#escape-handling)
+- [IZUI State](#izui-state)
 - [Logging](#logging)
 - [Debug Mode](#debug-mode)
 - [App Control](#app-control)
···
   }
   return { handled: false };   // Allow close
 });
+```
+
+---
+
+## IZUI State
+
+Query the IZUI state machine to determine if the current session is transient (invoked from another app) or active (invoked within Peek). See `docs/izui.md` for full details.
+
+### `window.app.izui.isTransient()`
+
+Check if the current session was invoked transiently (app wasn't focused).
+
+```javascript
+const isTransient = await window.app.izui.isTransient();
+if (isTransient) {
+  // User invoked from another app - show simplified UI
+  currentMode = 'default';
+} else {
+  // User is working within Peek - show contextual UI
+  currentMode = targetWindow.mode;
+}
+```
+
+### `window.app.izui.getEffectiveMode()`
+
+Get the effective mode for display. Returns `'default'` for transient sessions, `'active'` otherwise.
+
+```javascript
+const mode = await window.app.izui.getEffectiveMode();
+```
+
+### `window.app.izui.getState()`
+
+Get the current IZUI state.
+
+```javascript
+const state = await window.app.izui.getState();
+// Returns: 'idle' | 'transient' | 'active' | 'overlay'
 ```
 
 ---

docs/izui.md

···
+# IZUI (Invocable Zoom User Interface)
+
+IZUI is a state machine that manages how Peek windows behave based on how they were invoked. It ensures consistent UX whether the user invokes Peek from within the app or from another application.
+
+## Core Concept
+
+The key question IZUI answers: **Was the app focused when the user invoked a command?**
+
+- **Active mode**: User was working in Peek when they opened a window
+- **Transient mode**: User invoked Peek from another app (e.g., global hotkey)
+
+This distinction affects:
+1. What mode the cmd bar displays
+2. How ESC key behaves
+3. Whether hidden windows are restored when overlays close
+
+## States
+
+| State | Description | Mode Display | ESC Behavior |
+|-------|-------------|--------------|--------------|
+| `idle` | No visible windows, app in background | N/A | N/A |
+| `transient` | Invoked via global hotkey while unfocused | Always "default" | Close immediately, return to previous app |
+| `active` | User working within focused Peek windows | Target window's mode | Internal navigation only, never closes |
+| `overlay` | Full-screen overlay (e.g., windows picker) | Inherit from previous | Always close, restore hidden windows (if active) |
+
+## Session Tracking
+
+IZUI uses sessions to track state across multiple windows opened in a single interaction.
+
+```
+User in Safari → Global hotkey → Cmd opens (transient session starts)
+                              → User runs "windows" command
+                              → Windows overlay opens (inherits transient)
+                              → User hits ESC
+                              → Everything closes, back to Safari
+```
+
+Key behaviors:
+- **Session persists** until all windows in the interaction are closed
+- **Child windows inherit** transient state from their parent session
+- **KeepLive windows** re-evaluate transient state each time they're shown
+
+## Implementation
+
+### State Coordinator
+
+The `IzuiStateCoordinator` class (`backend/electron/izui-state.ts`) is the central manager:
+
+```typescript
+class IzuiStateCoordinator {
+  // Query current state
+  isTransient(): boolean;
+  getState(): IzuiState;
+  isOverlay(): boolean;
+
+  // Evaluate focus state (excludes requesting window)
+  evaluateOnShow(excludeWindowId?: number): 'active' | 'transient';
+
+  // Session lifecycle
+  startSession(entryMode: 'active' | 'transient'): void;
+  endSession(): void;
+
+  // Window stack (auto-ends session when empty)
+  pushWindow(windowId: number): void;
+  popWindow(windowId: number): void;
+
+  // Overlay mode
+  enterOverlay(windowId: number, hiddenIds: number[]): void;
+  exitOverlay(): void;
+
+  // Focus tracking cleanup
+  setFocusedWindow(windowId: number): void;
+  clearFocusedWindow(windowId: number): void;
+}
+```
+
+### Focus Detection
+
+Transient detection uses `BrowserWindow.isFocused()` (not `getFocusedWindow()`) to check actual system focus:
+
+```typescript
+evaluateOnShow(excludeWindowId?: number): 'active' | 'transient' {
+  const allWindows = BrowserWindow.getAllWindows();
+  const focusedWindow = allWindows.find(win =>
+    !win.isDestroyed() &&
+    win.isFocused() &&
+    win.id !== excludeWindowId  // Exclude the window asking the question
+  );
+  return focusedWindow ? 'active' : 'transient';
+}
+```
+
+**Why exclude the requesting window?** When the cmd panel asks "am I transient?", it already has focus. We need to check if any *other* window had focus before cmd opened.
+
+### Transient Propagation
+
+When opening a new window, transient state propagates from the session:
+
+```typescript
+// In window-open IPC handler
+const sessionWasTransient = coordinator.isTransient();
+const entryMode = coordinator.evaluateOnShow();
+const isTransient = sessionWasTransient || entryMode === 'transient';
+```
+
+This ensures windows opened FROM a transient session are also transient.
+
+### Overlay Close Behavior
+
+When an overlay closes, it only restores hidden windows if NOT in transient mode:
+
+```typescript
+// In window 'closed' handler
+const isTransient = windowData.params.transient === true;
+if (hiddenWindowIds && hiddenWindowIds.length > 0 && !isTransient) {
+  // Active mode: restore hidden windows
+  for (const id of hiddenWindowIds) {
+    BrowserWindow.fromId(id)?.show();
+  }
+}
+// Transient mode: don't restore, just close and return to previous app
+```
+
+## Renderer API
+
+Extensions can query IZUI state via the preload API:
+
+```javascript
+// Check if current session is transient
+const isTransient = await api.izui.isTransient();
+
+// Get the effective mode ('default' for transient, 'active' otherwise)
+const effectiveMode = await api.izui.getEffectiveMode();
+
+// Get current IZUI state ('idle', 'transient', 'active', 'overlay')
+const state = await api.izui.getState();
+```
+
+### Usage in Cmd Panel
+
+The cmd panel uses `api.izui.isTransient()` to determine what mode to display:
+
+```javascript
+const loadCommandContext = async () => {
+  const isTransient = await api.izui.isTransient();
+  if (isTransient) {
+    // Don't show target window's mode, show "default"
+    currentMode = 'default';
+    updateModeIndicator();
+    return;
+  }
+  // Active mode: show target window's actual mode
+  // ...
+};
+```
+
+## ESC Key Handling
+
+ESC behavior is determined by `escapeMode` parameter and transient state:
+
+| escapeMode | Transient | Behavior |
+|------------|-----------|----------|
+| `auto` | Yes | Close immediately |
+| `auto` | No | Ask renderer to handle (internal nav), never close |
+| `close` | Any | Always close |
+| `navigate` | Any | Ask renderer first, close if not handled |
+| `ignore` | Any | Do nothing |
+
+See `backend/electron/windows.ts` `addEscHandler()` for implementation.
+
+## Testing
+
+The IZUI state coordinator has comprehensive unit tests in `backend/electron/izui-state.test.ts`:
+
+```bash
+# Run IZUI tests
+yarn build && node --test dist/backend/electron/izui-state.test.js
+```
+
+Tests cover:
+- Transient detection with various focus states
+- Session lifecycle and persistence
+- Window exclusion in focus checks
+- Overlay mode and window restoration
+- Complex multi-window workflows
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `backend/electron/izui-state.ts` | State coordinator singleton |
+| `backend/electron/izui-state.test.ts` | Unit tests (54 test cases) |
+| `backend/electron/ipc.ts` | IZUI IPC handlers, transient propagation |
+| `backend/electron/main.ts` | Window lifecycle hooks, overlay close |
+| `backend/electron/windows.ts` | ESC handler with IZUI integration |
+| `preload.js` | `api.izui.*` namespace for renderers |
+| `extensions/cmd/panel.js` | Mode display based on transient state |
+
+## Common Scenarios
+
+### Scenario 1: Transient Cmd Invocation
+1. User is in Safari
+2. Presses global hotkey to open cmd
+3. Cmd opens, session starts as `transient`
+4. Cmd shows "default" mode (not target window's mode)
+5. User types command and presses Enter
+6. User presses ESC
+7. Everything closes, focus returns to Safari
+
+### Scenario 2: Active Cmd Invocation
+1. User is working in Peek (Groups window focused)
+2. Presses Cmd+K to open cmd
+3. Cmd opens, session starts as `active`
+4. Cmd shows "group" mode (target window's mode)
+5. User runs command
+6. User presses ESC
+7. Cmd closes, Groups window remains focused
+
+### Scenario 3: Transient with Overlay
+1. User is in Safari
+2. Presses global hotkey, runs "windows" command
+3. Windows overlay opens, hides other Peek windows
+4. User presses ESC
+5. Overlay closes, hidden windows NOT restored (transient mode)
+6. Focus returns to Safari

extensions/cmd/panel.js

···
  */
 const loadCommandContext = async () => {
   try {
+    // IZUI Policy: If invoked transiently (app wasn't focused when invoked),
+    // use "default" mode since we're not targeting a specific window context.
+    // Use api.izui.isTransient() which re-evaluates on each call (not frozen at creation)
+    // This fixes keepLive windows being stuck with stale transient state.
+    const isTransient = await api.izui.isTransient();
+    if (isTransient) {
+      log('cmd:panel', 'Transient invocation - using default mode');
+      currentMode = 'default';
+      currentModeMetadata = {};
+      updateModeIndicator();
+      // Still load command context for backwards compat, but don't use its mode
+      const result = await api.modes.getCommandContext();
+      if (result.success) {
+        commandContext = result.data;
+      }
+      return;
+    }
+
     // Use context API to get mode for the target window
     // First get the focused visible window ID
     const targetWindowId = await api.window.getFocusedVisibleWindowId();
···
 async function initModeIndicator() {
   // Use commandContext which has the target window's mode (not the cmd panel's mode)
   // commandContext is loaded by loadCommandContext() before this is called
-  if (commandContext?.mode?.major) {
+  // BUT: Don't override if loadCommandContext already set 'default' (transient mode)
+  if (currentMode === 'default') {
+    // Already set by transient detection - don't override
+    updateModeIndicator();
+  } else if (commandContext?.mode?.major) {
     currentMode = commandContext.mode.major;
+    updateModeIndicator();
+  } else {
+    updateModeIndicator();
   }
-  updateModeIndicator();
 
   // Set up click handler for cycling
   const indicator = document.getElementById('mode-indicator');

preload.js

···
    */
   getWindowId: () => {
     return ipcRenderer.invoke('get-window-id');
+  },
+  /**
+   * Check if this window was opened transiently (app wasn't focused when opened)
+   * Used for IZUI policy: transient windows use different escape/mode behavior
+   * @returns {Promise<boolean>} True if window is transient
+   */
+  isTransient: () => {
+    return ipcRenderer.invoke('window-is-transient');
+  }
+};
+
+// ============================================================================
+// IZUI State Coordinator API
+// ============================================================================
+// Centralized IZUI state management. Preferred over api.window.isTransient()
+// because it re-evaluates state on each invocation, fixing keepLive windows
+// that would otherwise be stuck with stale transient state.
+api.izui = {
+  /**
+   * Check if the current IZUI session is in transient mode
+   * Re-evaluates on each call (unlike window.isTransient which is frozen at creation)
+   * @returns {Promise<boolean>} True if session is transient (app wasn't focused when invoked)
+   */
+  isTransient: () => {
+    return ipcRenderer.invoke('izui-is-transient');
+  },
+
+  /**
+   * Get the effective mode for display
+   * Returns 'default' for transient sessions, 'active' for focused sessions
+   * @returns {Promise<string>} 'default' or 'active'
+   */
+  getEffectiveMode: () => {
+    return ipcRenderer.invoke('izui-get-effective-mode');
+  },
+
+  /**
+   * Get the current IZUI state
+   * @returns {Promise<string>} 'idle' | 'transient' | 'active' | 'overlay'
+   */
+  getState: () => {
+    return ipcRenderer.invoke('izui-get-state');
   }
 };