feat: add useTheme hook for reactive theme detection

Added a new useTheme() hook that provides reactive access to the ChatGPT
theme and automatically updates when the theme changes.

Changes:
- Created useTheme hook that wraps useOpenAiGlobal('theme')
- Returns Theme | null ('light' | 'dark' | null)
- Added 3 comprehensive tests (14 total OpenAI hook tests now)
- Updated both READMEs with useTheme examples and complete hook list
- All 513 tests passing

Usage:
```tsx
import { useTheme } from '@ainativekit/ui';

function MyWidget() {
  const theme = useTheme();
  return <div className={theme === 'dark' ? 'dark-mode' : 'light-mode'} />;
}
```

Resolves: #5

Author: JakeLin

README.md

@@ -186,17 +186,45 @@ import { SettingsCog, Terminal, Star } from '@ainativekit/ui/icons';
 Utilities to integrate with the **ChatGPT Apps SDK** runtime.
 
 ```tsx
-import { useOpenAiGlobal, useWidgetState, useMaxHeight } from '@ainativekit/ui';
+import {
+  useOpenAiGlobal,
+  useWidgetState,
+  useMaxHeight,
+  useTheme,
+  useDisplayMode
+} from '@ainativekit/ui';
 
 function MyChatGPTWidget() {
-  const openai = useOpenAiGlobal(); // Access global OpenAI instance
-  const [state, setState] = useWidgetState({}); // Manage widget state
-  const maxHeight = useMaxHeight(); // Layout constraint from host
+  // Access specific OpenAI global values (reactive)
+  const theme = useTheme(); // 'light' | 'dark' | null
+  const displayMode = useDisplayMode(); // 'inline' | 'pip' | 'fullscreen' | null
+  const maxHeight = useMaxHeight(); // number | null
+
+  // Or access any global property directly
+  const locale = useOpenAiGlobal('locale'); // string | null
+
+  // Manage persistent widget state
+  const [state, setState] = useWidgetState({ count: 0 });
 
-  return <div style={{ maxHeight }}>{/* your widget */}</div>;
+  return (
+    <div
+      className={theme === 'dark' ? 'dark-mode' : 'light-mode'}
+      style={{ maxHeight: maxHeight ?? 600 }}
+    >
+      {/* your widget */}
+    </div>
+  );
 }
 ```
 
+**Available Hooks:**
+- `useTheme()` - Get current theme and listen for changes
+- `useDisplayMode()` - Get current display mode (inline/pip/fullscreen)
+- `useMaxHeight()` - Get maximum height constraint for layout
+- `useWidgetState(defaultState)` - Persistent state across ChatGPT sessions
+- `useOpenAiGlobal(key)` - Access any `window.openai` property reactively
+- `useWidgetProps(defaultProps)` - Get tool output data
+
 ## 📘 TypeScript Support
 
 AINativeKit UI exports comprehensive TypeScript definitions for the ChatGPT Apps SDK, giving you **full autocomplete and type safety** for `window.openai`.

packages/ui/README.md

@@ -187,17 +187,45 @@ import { SettingsCog, Terminal, Star } from '@ainativekit/ui/icons';
 Utilities to integrate with the **ChatGPT Apps SDK** runtime.
 
 ```tsx
-import { useOpenAiGlobal, useWidgetState, useMaxHeight } from '@ainativekit/ui';
+import {
+  useOpenAiGlobal,
+  useWidgetState,
+  useMaxHeight,
+  useTheme,
+  useDisplayMode
+} from '@ainativekit/ui';
 
 function MyChatGPTWidget() {
-  const openai = useOpenAiGlobal(); // Access global OpenAI instance
-  const [state, setState] = useWidgetState({}); // Manage widget state
-  const maxHeight = useMaxHeight(); // Layout constraint from host
+  // Access specific OpenAI global values (reactive)
+  const theme = useTheme(); // 'light' | 'dark' | null
+  const displayMode = useDisplayMode(); // 'inline' | 'pip' | 'fullscreen' | null
+  const maxHeight = useMaxHeight(); // number | null
+
+  // Or access any global property directly
+  const locale = useOpenAiGlobal('locale'); // string | null
+
+  // Manage persistent widget state
+  const [state, setState] = useWidgetState({ count: 0 });
 
-  return <div style={{ maxHeight }}>{/* your widget */}</div>;
+  return (
+    <div
+      className={theme === 'dark' ? 'dark-mode' : 'light-mode'}
+      style={{ maxHeight: maxHeight ?? 600 }}
+    >
+      {/* your widget */}
+    </div>
+  );
 }
 ```
 
+**Available Hooks:**
+- `useTheme()` - Get current theme and listen for changes
+- `useDisplayMode()` - Get current display mode (inline/pip/fullscreen)
+- `useMaxHeight()` - Get maximum height constraint for layout
+- `useWidgetState(defaultState)` - Persistent state across ChatGPT sessions
+- `useOpenAiGlobal(key)` - Access any `window.openai` property reactively
+- `useWidgetProps(defaultProps)` - Get tool output data
+
 ## 📘 TypeScript Support
 
 AINativeKit UI exports comprehensive TypeScript definitions for the ChatGPT Apps SDK, giving you **full autocomplete and type safety** for `window.openai`.

packages/ui/src/hooks/openai/index.ts

@@ -4,3 +4,4 @@ export { useWidgetProps } from './useWidgetProps';
 export { useWidgetState } from './useWidgetState';
 export { useMaxHeight } from './useMaxHeight';
 export { useDisplayMode } from './useDisplayMode';
+export { useTheme } from './useTheme';

packages/ui/src/hooks/openai/openai-hooks.test.ts

@@ -6,6 +6,7 @@ import {
   useWidgetState,
   useMaxHeight,
   useDisplayMode,
+  useTheme,
   SetGlobalsEvent,
   type OpenAiGlobals,
   type OpenAiApi,
@@ -198,4 +199,34 @@ describe('OpenAI Hooks', () => {
       expect(result.current).toBe('pip');
     });
   });
+
+  describe('useTheme', () => {
+    beforeEach(() => {
+      window.openai = createOpenAiMock();
+    });
+
+    it('returns the current theme from globals', () => {
+      const { result } = renderHook(() => useTheme());
+      expect(result.current).toBe('light');
+    });
+
+    it('updates when theme changes', () => {
+      const { result } = renderHook(() => useTheme());
+      expect(result.current).toBe('light');
+
+      act(() => {
+        window.openai.theme = 'dark';
+        dispatchGlobalsEvent({ theme: 'dark' });
+      });
+
+      expect(result.current).toBe('dark');
+    });
+
+    it('returns null when window.openai is not available', () => {
+      delete (window as { openai?: unknown }).openai;
+
+      const { result } = renderHook(() => useTheme());
+      expect(result.current).toBeNull();
+    });
+  });
 });

packages/ui/src/hooks/openai/useTheme.ts

@@ -0,0 +1,26 @@
+import { useOpenAiGlobal } from './useOpenAiGlobal';
+import type { Theme } from './types';
+
+/**
+ * Get the current ChatGPT theme and listen for changes
+ *
+ * @returns The current theme ('light' or 'dark'), or null if not in ChatGPT environment
+ *
+ * @example
+ * ```tsx
+ * import { useTheme } from '@ainativekit/ui';
+ *
+ * function MyComponent() {
+ *   const theme = useTheme();
+ *
+ *   return (
+ *     <div className={theme === 'dark' ? 'dark-mode' : 'light-mode'}>
+ *       Current theme: {theme ?? 'unknown'}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export const useTheme = (): Theme | null => {
+  return useOpenAiGlobal('theme');
+};