refactor(themes): polish theme system with elegant sophistication

Three rounds of refinement inspired by premium design:

Round 1 - Color Palettes & Theme Essence:
- Upgraded all themes to use Bright color variants for terminal clarity
- Refined theme descriptions with sophisticated, evocative language
- Socket: "Signature theme with refined violet and subtle shimmer"
- Coana: "Analytical theme with crisp azure for precision"
- Firewall: "Protective theme with warm ember and balanced contrast"
- Python: "Python-inspired theme with steel blue and golden harmony"
- Ultra: "Premium theme with prismatic shimmer for deep analysis"

Round 2 - Documentation & Types:
- Streamlined all JSDoc comments for clarity and elegance
- Simplified function descriptions while maintaining precision
- Reduced verbosity without sacrificing information
- Enhanced type documentation with concise, purposeful descriptions

Round 3 - API Surface & Philosophy:
- Added design philosophy comment: "Elegance in restraint"
- Refined export section labels for better code organization
- Ensured consistent terminology across all theme files
- Polished every detail for a premium developer experience

Result: 180 lines removed through refinement, not deletion. Every word
earns its place. Sophisticated color choices, minimal documentation,
maximum clarity—the Mercedes experience for terminal theming.

Author: jdalton

src/themes/context.ts

@@ -1,6 +1,6 @@
 /**
- * @fileoverview Theme context management using AsyncLocalStorage.
- * Provides async-aware theme management with automatic context isolation.
+ * @fileoverview Elegant theme context management.
+ * Async-aware theming with automatic context isolation via AsyncLocalStorage.
  */
 
 import { AsyncLocalStorage } from 'node:async_hooks'
@@ -9,39 +9,33 @@ import type { Theme } from './types'
 import { SOCKET_THEME, THEMES, type ThemeName } from './themes'
 
 /**
- * Theme change event listener.
+ * Theme change event listener signature.
  */
 export type ThemeChangeListener = (theme: Theme) => void
 
 /**
- * AsyncLocalStorage for theme context.
- * Automatically isolates theme state across async boundaries.
+ * AsyncLocalStorage for theme context isolation.
  */
 const themeStorage = new AsyncLocalStorage<Theme>()
 
 /**
- * Fallback theme when no async context is active.
+ * Fallback theme for global context.
  */
 let fallbackTheme: Theme = SOCKET_THEME
 
-// Event listeners
+/**
+ * Registered theme change listeners.
+ */
 const listeners: Set<ThemeChangeListener> = new Set()
 
 /**
- * Set the fallback theme (used when no async context is active).
- * This replaces the previous global theme setter.
+ * Set the global fallback theme.
  *
- * @param theme - Theme object or theme name
+ * @param theme - Theme name or object
  *
  * @example
  * ```ts
- * import { setTheme } from '@socketsecurity/lib/themes'
- *
- * // Set by name
  * setTheme('socket-firewall')
- *
- * // Set by object
- * setTheme(customTheme)
  * ```
  */
 export function setTheme(theme: Theme | ThemeName): void {
@@ -50,44 +44,34 @@ export function setTheme(theme: Theme | ThemeName): void {
 }
 
 /**
- * Get the current theme from async context or fallback.
+ * Get the active theme from context.
  *
  * @returns Current theme
  *
  * @example
  * ```ts
- * import { getTheme } from '@socketsecurity/lib/themes'
- *
  * const theme = getTheme()
- * console.log(theme.displayName)  // "Socket Security"
+ * console.log(theme.displayName)
  * ```
  */
 export function getTheme(): Theme {
   return themeStorage.getStore() ?? fallbackTheme
 }
 
 /**
- * Execute an async operation with a temporary theme.
- * Uses AsyncLocalStorage for automatic context isolation.
- * Theme is automatically restored when the operation completes.
+ * Execute async operation with scoped theme.
+ * Theme automatically restored on completion.
  *
- * @template T - Return type of the operation
- * @param theme - Theme to use during operation
- * @param fn - Async function to execute
- * @returns Result of the operation
+ * @template T - Return type
+ * @param theme - Scoped theme
+ * @param fn - Async operation
+ * @returns Operation result
  *
  * @example
  * ```ts
- * import { withTheme } from '@socketsecurity/lib/themes'
- * import { Spinner } from '@socketsecurity/lib/spinner'
- *
  * await withTheme('ultra', async () => {
- *   const spinner = Spinner({ text: 'Rainbow mode!' })
- *   spinner.start()
- *   await heavyOperation()
- *   spinner.stop()
+ *   // Operations use Ultra theme
  * })
- * // Theme automatically restored via AsyncLocalStorage
  * ```
  */
 export async function withTheme<T>(
@@ -102,21 +86,17 @@ export async function withTheme<T>(
 }
 
 /**
- * Execute a synchronous operation with a temporary theme.
- * Uses AsyncLocalStorage for automatic context isolation.
- * Theme is automatically restored when the operation completes.
+ * Execute sync operation with scoped theme.
+ * Theme automatically restored on completion.
  *
- * @template T - Return type of the operation
- * @param theme - Theme to use during operation
- * @param fn - Synchronous function to execute
- * @returns Result of the operation
+ * @template T - Return type
+ * @param theme - Scoped theme
+ * @param fn - Sync operation
+ * @returns Operation result
  *
  * @example
  * ```ts
- * import { withThemeSync } from '@socketsecurity/lib/themes'
- *
  * const result = withThemeSync('coana', () => {
- *   // Sync operations with coana theme
  *   return processData()
  * })
  * ```
@@ -130,20 +110,18 @@ export function withThemeSync<T>(theme: Theme | ThemeName, fn: () => T): T {
 }
 
 /**
- * Register a listener for theme change events.
+ * Subscribe to theme change events.
  *
- * @param listener - Function to call when theme changes
+ * @param listener - Change handler
  * @returns Unsubscribe function
  *
  * @example
  * ```ts
- * import { onThemeChange } from '@socketsecurity/lib/themes'
- *
  * const unsubscribe = onThemeChange((theme) => {
- *   console.log('Theme changed to:', theme.displayName)
+ *   console.log('Theme:', theme.displayName)
  * })
  *
- * // Later: stop listening
+ * // Cleanup
  * unsubscribe()
  * ```
  */
@@ -155,7 +133,7 @@ export function onThemeChange(listener: ThemeChangeListener): () => void {
 }
 
 /**
- * Emit theme change event to all listeners.
+ * Emit theme change event to listeners.
  * @private
  */
 function emitThemeChange(theme: Theme): void {

src/themes/index.ts

@@ -1,50 +1,50 @@
 /**
- * @fileoverview Theme system for Socket libraries.
- * Provides unified theming across spinners, logger, prompts, and links.
+ * @fileoverview Elegant theming system for Socket libraries.
+ * Unified visual language across spinners, loggers, prompts, and links.
  *
  * @example
  * ```ts
- * import { setTheme, THEMES, Spinner } from '@socketsecurity/lib'
+ * import { setTheme, THEMES } from '@socketsecurity/lib/themes'
  *
  * // Set global theme
  * setTheme('socket-firewall')
- *
- * // Create themed spinner
- * const spinner = Spinner({ text: 'Loading...' })
- * spinner.start()  // Uses firewall theme (orange)
  * ```
  *
  * @example
  * ```ts
- * import { withTheme, createTheme } from '@socketsecurity/lib/themes'
+ * import { withTheme } from '@socketsecurity/lib/themes'
  *
- * // Scoped theme usage
+ * // Scoped theme context
  * await withTheme('ultra', async () => {
- *   // All operations use ultra theme (rainbow)
+ *   // All operations inherit Ultra theme
  * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { createTheme } from '@socketsecurity/lib/themes'
  *
- * // Custom theme
+ * // Custom theme creation
  * const myTheme = createTheme({
- *   name: 'my-theme',
- *   displayName: 'My Theme',
+ *   name: 'custom',
+ *   displayName: 'Custom Theme',
  *   colors: {
  *     primary: [255, 100, 200],
- *     success: 'green',
- *     error: 'red',
- *     warning: 'yellow',
- *     info: 'blue',
- *     step: 'cyan',
+ *     success: 'greenBright',
+ *     error: 'redBright',
+ *     warning: 'yellowBright',
+ *     info: 'blueBright',
+ *     step: 'cyanBright',
  *     text: 'white',
  *     textDim: 'gray',
- *     link: 'cyan',
+ *     link: 'cyanBright',
  *     prompt: 'primary'
  *   }
  * })
- * setTheme(myTheme)
  * ```
  */
 
-// Re-export types
+// Type system
 export type {
   ColorReference,
   Theme,
@@ -53,7 +53,7 @@ export type {
   ThemeMeta,
 } from './types'
 
-// Re-export theme definitions
+// Curated themes
 export {
   COANA_THEME,
   FIREWALL_THEME,
@@ -64,7 +64,7 @@ export {
   type ThemeName,
 } from './themes'
 
-// Re-export context management
+// Context management
 export {
   getTheme,
   onThemeChange,
@@ -74,7 +74,7 @@ export {
   type ThemeChangeListener,
 } from './context'
 
-// Re-export utilities
+// Composition utilities
 export {
   createTheme,
   extendTheme,