@socketsecurity/lib 2.10.4 → 3.0.0

package/dist/stdio/mask.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/stdio/mask.ts"],
-  "sourcesContent": ["/**\n * @fileoverview Interactive output masking utilities for CLI tools.\n * Provides output control with keyboard toggling (ctrl+o).\n *\n * ANSI Escape Sequences Used:\n * - '\\r': Carriage return - moves cursor to beginning of current line.\n * - '\\x1b[K' or '\\x1b[0K': CSI K (erase line) - clear from cursor to end of line.\n * - '\\x1b[2K': CSI 2K - erase entire line.\n * - '\\x1b[1A': CSI A - move cursor up 1 line.\n *\n * Terminal Control:\n * - Raw mode (setRawMode(true)): Captures keypresses immediately without buffering.\n * - TTY detection: Ensures terminal manipulation only occurs in interactive terminals.\n *\n * Key Features:\n * - Output buffering: Stores up to 1000 lines when masked to prevent memory issues.\n * - Graceful cleanup: Always restores terminal to normal mode on exit/error.\n * - Visual feedback: Uses spinner to indicate process is running when output is masked.\n */\n\nimport type { ChildProcess, SpawnOptions } from 'node:child_process'\nimport { spawn } from 'node:child_process'\nimport readline from 'node:readline'\nimport { spinner } from '../spinner.js'\nimport { clearLine } from './clear.js'\nimport { write } from './stdout.js'\n\nexport interface OutputMaskOptions {\n  /**\n   * Current working directory for spawned process.\n   * @default process.cwd()\n   */\n  cwd?: string | undefined\n  /**\n   * Environment variables for spawned process.\n   * @default process.env\n   */\n  env?: NodeJS.ProcessEnv | undefined\n  /**\n   * Filter output before displaying or buffering.\n   * Return `false` to skip the line, `true` to include it.\n   *\n   * Useful for filtering non-fatal warnings or noise from test runners.\n   * The filter runs on every chunk of output before display/buffering.\n   *\n   * @param text - The output text chunk (may include ANSI codes)\n   * @param stream - Whether this came from 'stdout' or 'stderr'\n   * @returns `true` to include this output, `false` to skip it\n   *\n   * @example\n   * ```ts\n   * filterOutput: (text, stream) => {\n   *   // Skip vitest worker termination errors\n   *   if (text.includes('Terminating worker thread')) return false\n   *   return true\n   * }\n   * ```\n   */\n  filterOutput?:\n    | ((text: string, stream: 'stdout' | 'stderr') => boolean)\n    | undefined\n  /**\n   * Progress message to display in spinner.\n   * @default 'Running\u2026'\n   */\n  message?: string | undefined\n  /**\n   * Override the exit code based on captured output.\n   *\n   * Useful for handling non-fatal errors that shouldn't fail the build.\n   * Called after the process exits with the original code and all captured output.\n   * Return a number to override the exit code, or `undefined` to keep original.\n   *\n   * @param code - Original exit code from the process\n   * @param stdout - All captured stdout (even filtered lines are captured)\n   * @param stderr - All captured stderr (even filtered lines are captured)\n   * @returns New exit code, or `undefined` to keep original\n   *\n   * @example\n   * ```ts\n   * overrideExitCode: (code, stdout, stderr) => {\n   *   // If only worker termination errors, treat as success\n   *   const output = stdout + stderr\n   *   const hasWorkerError = output.includes('Terminating worker thread')\n   *   const hasRealFailure = output.includes('FAIL')\n   *   if (code !== 0 && hasWorkerError && !hasRealFailure) {\n   *     return 0 // Override to success\n   *   }\n   *   return undefined // Keep original\n   * }\n   * ```\n   */\n  overrideExitCode?:\n    | ((code: number, stdout: string, stderr: string) => number | undefined)\n    | undefined\n  /**\n   * Start with output visible instead of masked.\n   * When `true`, output shows immediately without needing ctrl+o.\n   * @default false\n   */\n  showOutput?: boolean | undefined\n  /**\n   * Text to show after \"ctrl+o\" in spinner message.\n   * @default 'to see full output'\n   */\n  toggleText?: string | undefined\n}\n\nexport interface OutputMask {\n  /** Whether spinner is currently active */\n  isSpinning: boolean\n  /** Buffered output lines */\n  outputBuffer: string[]\n  /** All stderr captured (for exit code override) */\n  stderrCapture: string\n  /** All stdout captured (for exit code override) */\n  stdoutCapture: string\n  /** Whether output is currently visible */\n  verbose: boolean\n}\n\n/**\n * Create an output mask for controlling command output visibility.\n * The mask tracks whether output should be shown or hidden (buffered).\n * When hidden, output is buffered and a spinner is shown instead.\n */\nexport function createOutputMask(options: OutputMaskOptions = {}): OutputMask {\n  const { showOutput = false } = options\n\n  return {\n    isSpinning: !showOutput,\n    outputBuffer: [],\n    stderrCapture: '',\n    stdoutCapture: '',\n    verbose: showOutput,\n  }\n}\n\n/**\n * Create a keyboard handler for toggling output visibility.\n * Handles two key combinations:\n * - ctrl+o: Toggle between showing and hiding output.\n * - ctrl+c: Cancel the running process.\n * The handler manipulates terminal state using ANSI escape sequences.\n */\nexport function createKeyboardHandler(\n  mask: OutputMask,\n  child: ChildProcess,\n  options: OutputMaskOptions = {},\n): (_str: string, key: readline.Key) => void {\n  const { message = 'Running\u2026', toggleText = 'to see full output' } = options\n\n  return (_str, key) => {\n    // ctrl+o toggles verbose mode.\n    if (key?.ctrl && key.name === 'o') {\n      mask.verbose = !mask.verbose\n\n      if (mask.verbose) {\n        // Stop spinner and show buffered output.\n        if (mask.isSpinning) {\n          spinner.stop()\n          mask.isSpinning = false\n        }\n\n        // Clear the current line (removes spinner remnants).\n        clearLine()\n\n        // Show buffered output.\n        if (mask.outputBuffer.length > 0) {\n          console.log('--- Output (ctrl+o to hide) ---')\n          mask.outputBuffer.forEach(line => {\n            write(line)\n          })\n        }\n      } else {\n        // Hide output and show spinner.\n        // Clear all the output lines that were shown.\n        if (mask.outputBuffer.length > 0) {\n          // Calculate number of lines to clear (output + header line).\n          const lineCount = mask.outputBuffer.join('').split('\\n').length + 1\n          // Move up and clear each line using ANSI escape sequences:\n          // - '\\x1b[1A' (CSI A): Move cursor up 1 line.\n          // - '\\x1b[2K' (CSI K with param 2): Erase entire line.\n          // This combination effectively \"rewinds\" the terminal output.\n          for (let i = 0; i < lineCount; i += 1) {\n            process.stdout.write('\\x1b[1A\\x1b[2K')\n          }\n        }\n        clearLine()\n\n        // Clear the buffer and restart spinner.\n        mask.outputBuffer = []\n        if (!mask.isSpinning) {\n          spinner.start(`${message} (ctrl+o ${toggleText})`)\n          mask.isSpinning = true\n        }\n      }\n    }\n    // ctrl+c to cancel.\n    else if (key?.ctrl && key.name === 'c') {\n      // Gracefully terminate child process.\n      child.kill('SIGTERM')\n      // Restore terminal to normal mode before exiting.\n      if (process.stdin.isTTY) {\n        process.stdin.setRawMode(false)\n      }\n      throw new Error('Process cancelled by user')\n    }\n  }\n}\n\n/**\n * Attach output masking to a child process.\n * Returns a promise that resolves with the exit code.\n * This function:\n * - Sets up keyboard input handling in raw mode for immediate key capture.\n * - Buffers stdout/stderr when not in verbose mode.\n * - Shows a spinner when output is masked.\n * - Allows toggling between masked and unmasked output with ctrl+o.\n */\nexport function attachOutputMask(\n  child: ChildProcess,\n  options: OutputMaskOptions = {},\n): Promise<number> {\n  return new Promise((resolve, reject) => {\n    const { message = 'Running\u2026' } = options\n    const mask = createOutputMask(options)\n\n    // Start spinner if not verbose.\n    if (mask.isSpinning && process.stdout.isTTY) {\n      spinner.start(\n        `${message} (ctrl+o ${options.toggleText || 'to see full output'})`,\n      )\n    }\n\n    // Setup keyboard input handling.\n    // Raw mode is required to capture ctrl+o without waiting for Enter.\n    if (process.stdin.isTTY) {\n      readline.emitKeypressEvents(process.stdin)\n      process.stdin.setRawMode(true)\n\n      const keypressHandler = createKeyboardHandler(mask, child, options)\n      process.stdin.on('keypress', keypressHandler)\n\n      // Cleanup on exit: restore terminal to normal mode.\n      child.on('exit', () => {\n        if (process.stdin.isTTY) {\n          process.stdin.setRawMode(false)\n          process.stdin.removeListener('keypress', keypressHandler)\n        }\n      })\n    }\n\n    // Handle stdout: either show immediately or buffer for later.\n    if (child.stdout) {\n      child.stdout.on('data', data => {\n        const text = data.toString()\n\n        // Always capture for exit code override.\n        mask.stdoutCapture += text\n\n        // Apply filter if provided.\n        if (options.filterOutput && !options.filterOutput(text, 'stdout')) {\n          // Skip this output.\n          return undefined\n        }\n\n        if (mask.verbose) {\n          write(text)\n        } else {\n          // Buffer the output for later.\n          mask.outputBuffer.push(text)\n\n          // Keep buffer size reasonable (last 1000 lines).\n          // This prevents unbounded memory growth for long-running processes.\n          const lines = mask.outputBuffer.join('').split('\\n')\n          if (lines.length > 1000) {\n            mask.outputBuffer = [lines.slice(-1000).join('\\n')]\n          }\n        }\n        return undefined\n      })\n    }\n\n    // Handle stderr: same as stdout, but write to stderr stream when verbose.\n    if (child.stderr) {\n      child.stderr.on('data', data => {\n        const text = data.toString()\n\n        // Always capture for exit code override.\n        mask.stderrCapture += text\n\n        // Apply filter if provided.\n        if (options.filterOutput && !options.filterOutput(text, 'stderr')) {\n          // Skip this output.\n          return undefined\n        }\n\n        if (mask.verbose) {\n          process.stderr.write(text)\n        } else {\n          mask.outputBuffer.push(text)\n        }\n        return undefined\n      })\n    }\n\n    child.on('exit', code => {\n      // Cleanup keyboard if needed.\n      if (process.stdin.isTTY) {\n        process.stdin.setRawMode(false)\n      }\n\n      // Allow caller to override exit code based on output.\n      let finalCode = code || 0\n      if (options.overrideExitCode) {\n        const overridden = options.overrideExitCode(\n          finalCode,\n          mask.stdoutCapture,\n          mask.stderrCapture,\n        )\n        if (overridden !== undefined) {\n          finalCode = overridden\n        }\n      }\n\n      if (mask.isSpinning) {\n        if (finalCode === 0) {\n          spinner.successAndStop(`${message} completed`)\n        } else {\n          spinner.failAndStop(`${message} failed`)\n          // Show buffered output on failure so user can see what went wrong.\n          if (mask.outputBuffer.length > 0 && !mask.verbose) {\n            console.log('\\n--- Output ---')\n            mask.outputBuffer.forEach(line => {\n              write(line)\n            })\n          }\n        }\n      }\n\n      resolve(finalCode)\n    })\n\n    child.on('error', error => {\n      // Ensure terminal is restored to normal mode on error.\n      if (process.stdin.isTTY) {\n        process.stdin.setRawMode(false)\n      }\n\n      if (mask.isSpinning) {\n        spinner.failAndStop(`${message} error`)\n      }\n      reject(error)\n    })\n  })\n}\n\n/**\n * Run a command with interactive output masking.\n * Convenience wrapper around spawn + attachOutputMask.\n * Spawns a child process and attaches the output masking system to it.\n * stdin is inherited, stdout and stderr are piped for masking control.\n */\nexport async function runWithMask(\n  command: string,\n  args: string[] = [],\n  options: OutputMaskOptions & SpawnOptions = {},\n): Promise<number> {\n  const {\n    message = 'Running\u2026',\n    showOutput = false,\n    toggleText = 'to see output',\n    ...spawnOptions\n  } = options\n\n  const child = spawn(command, args, {\n    stdio: ['inherit', 'pipe', 'pipe'],\n    ...spawnOptions,\n  })\n\n  return await attachOutputMask(child, { message, showOutput, toggleText })\n}\n"],
-  "mappings": "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",
-  "names": ["mask_exports", "__export", "attachOutputMask", "createKeyboardHandler", "createOutputMask", "runWithMask", "__toCommonJS", "import_node_child_process", "import_node_readline", "import_spinner", "import_clear", "import_stdout", "options", "showOutput", "mask", "child", "message", "toggleText", "_str", "key", "line", "lineCount", "i", "resolve", "reject", "readline", "keypressHandler", "data", "text", "lines", "code", "finalCode", "overridden", "error", "command", "args", "spawnOptions"]
+  "sourcesContent": ["/**\n * @fileoverview Interactive output masking utilities for CLI tools.\n * Provides output control with keyboard toggling (ctrl+o).\n *\n * ANSI Escape Sequences Used:\n * - '\\r': Carriage return - moves cursor to beginning of current line.\n * - '\\x1b[K' or '\\x1b[0K': CSI K (erase line) - clear from cursor to end of line.\n * - '\\x1b[2K': CSI 2K - erase entire line.\n * - '\\x1b[1A': CSI A - move cursor up 1 line.\n *\n * Terminal Control:\n * - Raw mode (setRawMode(true)): Captures keypresses immediately without buffering.\n * - TTY detection: Ensures terminal manipulation only occurs in interactive terminals.\n *\n * Key Features:\n * - Output buffering: Stores up to 1000 lines when masked to prevent memory issues.\n * - Graceful cleanup: Always restores terminal to normal mode on exit/error.\n * - Visual feedback: Uses spinner to indicate process is running when output is masked.\n */\n\nimport type { ChildProcess, SpawnOptions } from 'child_process'\nimport { spawn } from 'child_process'\nimport readline from 'readline'\nimport { getDefaultSpinner } from '../spinner.js'\nimport { clearLine } from './clear.js'\nimport { write } from './stdout.js'\n\nexport interface OutputMaskOptions {\n  /**\n   * Current working directory for spawned process.\n   * @default process.cwd()\n   */\n  cwd?: string | undefined\n  /**\n   * Environment variables for spawned process.\n   * @default process.env\n   */\n  env?: NodeJS.ProcessEnv | undefined\n  /**\n   * Filter output before displaying or buffering.\n   * Return `false` to skip the line, `true` to include it.\n   *\n   * Useful for filtering non-fatal warnings or noise from test runners.\n   * The filter runs on every chunk of output before display/buffering.\n   *\n   * @param text - The output text chunk (may include ANSI codes)\n   * @param stream - Whether this came from 'stdout' or 'stderr'\n   * @returns `true` to include this output, `false` to skip it\n   *\n   * @example\n   * ```ts\n   * filterOutput: (text, stream) => {\n   *   // Skip vitest worker termination errors\n   *   if (text.includes('Terminating worker thread')) return false\n   *   return true\n   * }\n   * ```\n   */\n  filterOutput?:\n    | ((text: string, stream: 'stdout' | 'stderr') => boolean)\n    | undefined\n  /**\n   * Progress message to display in spinner.\n   * @default 'Running\u2026'\n   */\n  message?: string | undefined\n  /**\n   * Override the exit code based on captured output.\n   *\n   * Useful for handling non-fatal errors that shouldn't fail the build.\n   * Called after the process exits with the original code and all captured output.\n   * Return a number to override the exit code, or `undefined` to keep original.\n   *\n   * @param code - Original exit code from the process\n   * @param stdout - All captured stdout (even filtered lines are captured)\n   * @param stderr - All captured stderr (even filtered lines are captured)\n   * @returns New exit code, or `undefined` to keep original\n   *\n   * @example\n   * ```ts\n   * overrideExitCode: (code, stdout, stderr) => {\n   *   // If only worker termination errors, treat as success\n   *   const output = stdout + stderr\n   *   const hasWorkerError = output.includes('Terminating worker thread')\n   *   const hasRealFailure = output.includes('FAIL')\n   *   if (code !== 0 && hasWorkerError && !hasRealFailure) {\n   *     return 0 // Override to success\n   *   }\n   *   return undefined // Keep original\n   * }\n   * ```\n   */\n  overrideExitCode?:\n    | ((code: number, stdout: string, stderr: string) => number | undefined)\n    | undefined\n  /**\n   * Start with output visible instead of masked.\n   * When `true`, output shows immediately without needing ctrl+o.\n   * @default false\n   */\n  showOutput?: boolean | undefined\n  /**\n   * Text to show after \"ctrl+o\" in spinner message.\n   * @default 'to see full output'\n   */\n  toggleText?: string | undefined\n}\n\nexport interface OutputMask {\n  /** Whether spinner is currently active */\n  isSpinning: boolean\n  /** Buffered output lines */\n  outputBuffer: string[]\n  /** All stderr captured (for exit code override) */\n  stderrCapture: string\n  /** All stdout captured (for exit code override) */\n  stdoutCapture: string\n  /** Whether output is currently visible */\n  verbose: boolean\n}\n\n/**\n * Create an output mask for controlling command output visibility.\n * The mask tracks whether output should be shown or hidden (buffered).\n * When hidden, output is buffered and a spinner is shown instead.\n */\nexport function createOutputMask(options: OutputMaskOptions = {}): OutputMask {\n  const { showOutput = false } = options\n\n  return {\n    isSpinning: !showOutput,\n    outputBuffer: [],\n    stderrCapture: '',\n    stdoutCapture: '',\n    verbose: showOutput,\n  }\n}\n\n/**\n * Create a keyboard handler for toggling output visibility.\n * Handles two key combinations:\n * - ctrl+o: Toggle between showing and hiding output.\n * - ctrl+c: Cancel the running process.\n * The handler manipulates terminal state using ANSI escape sequences.\n */\nexport function createKeyboardHandler(\n  mask: OutputMask,\n  child: ChildProcess,\n  options: OutputMaskOptions = {},\n): (_str: string, key: readline.Key) => void {\n  const { message = 'Running\u2026', toggleText = 'to see full output' } = options\n\n  return (_str, key) => {\n    // ctrl+o toggles verbose mode.\n    if (key?.ctrl && key.name === 'o') {\n      mask.verbose = !mask.verbose\n\n      if (mask.verbose) {\n        // Stop spinner and show buffered output.\n        if (mask.isSpinning) {\n          getDefaultSpinner().stop()\n          mask.isSpinning = false\n        }\n\n        // Clear the current line (removes spinner remnants).\n        clearLine()\n\n        // Show buffered output.\n        if (mask.outputBuffer.length > 0) {\n          console.log('--- Output (ctrl+o to hide) ---')\n          mask.outputBuffer.forEach(line => {\n            write(line)\n          })\n        }\n      } else {\n        // Hide output and show spinner.\n        // Clear all the output lines that were shown.\n        if (mask.outputBuffer.length > 0) {\n          // Calculate number of lines to clear (output + header line).\n          const lineCount = mask.outputBuffer.join('').split('\\n').length + 1\n          // Move up and clear each line using ANSI escape sequences:\n          // - '\\x1b[1A' (CSI A): Move cursor up 1 line.\n          // - '\\x1b[2K' (CSI K with param 2): Erase entire line.\n          // This combination effectively \"rewinds\" the terminal output.\n          for (let i = 0; i < lineCount; i += 1) {\n            process.stdout.write('\\x1b[1A\\x1b[2K')\n          }\n        }\n        clearLine()\n\n        // Clear the buffer and restart spinner.\n        mask.outputBuffer = []\n        if (!mask.isSpinning) {\n          getDefaultSpinner().start(`${message} (ctrl+o ${toggleText})`)\n          mask.isSpinning = true\n        }\n      }\n    }\n    // ctrl+c to cancel.\n    else if (key?.ctrl && key.name === 'c') {\n      // Gracefully terminate child process.\n      child.kill('SIGTERM')\n      // Restore terminal to normal mode before exiting.\n      if (process.stdin.isTTY) {\n        process.stdin.setRawMode(false)\n      }\n      throw new Error('Process cancelled by user')\n    }\n  }\n}\n\n/**\n * Attach output masking to a child process.\n * Returns a promise that resolves with the exit code.\n * This function:\n * - Sets up keyboard input handling in raw mode for immediate key capture.\n * - Buffers stdout/stderr when not in verbose mode.\n * - Shows a spinner when output is masked.\n * - Allows toggling between masked and unmasked output with ctrl+o.\n */\nexport function attachOutputMask(\n  child: ChildProcess,\n  options: OutputMaskOptions = {},\n): Promise<number> {\n  return new Promise((resolve, reject) => {\n    const { message = 'Running\u2026' } = options\n    const mask = createOutputMask(options)\n\n    // Start spinner if not verbose.\n    if (mask.isSpinning && process.stdout.isTTY) {\n      getDefaultSpinner().start(\n        `${message} (ctrl+o ${options.toggleText || 'to see full output'})`,\n      )\n    }\n\n    // Setup keyboard input handling.\n    // Raw mode is required to capture ctrl+o without waiting for Enter.\n    if (process.stdin.isTTY) {\n      readline.emitKeypressEvents(process.stdin)\n      process.stdin.setRawMode(true)\n\n      const keypressHandler = createKeyboardHandler(mask, child, options)\n      process.stdin.on('keypress', keypressHandler)\n\n      // Cleanup on exit: restore terminal to normal mode.\n      child.on('exit', () => {\n        if (process.stdin.isTTY) {\n          process.stdin.setRawMode(false)\n          process.stdin.removeListener('keypress', keypressHandler)\n        }\n      })\n    }\n\n    // Handle stdout: either show immediately or buffer for later.\n    if (child.stdout) {\n      child.stdout.on('data', data => {\n        const text = data.toString()\n\n        // Always capture for exit code override.\n        mask.stdoutCapture += text\n\n        // Apply filter if provided.\n        if (options.filterOutput && !options.filterOutput(text, 'stdout')) {\n          // Skip this output.\n          return undefined\n        }\n\n        if (mask.verbose) {\n          write(text)\n        } else {\n          // Buffer the output for later.\n          mask.outputBuffer.push(text)\n\n          // Keep buffer size reasonable (last 1000 lines).\n          // This prevents unbounded memory growth for long-running processes.\n          const lines = mask.outputBuffer.join('').split('\\n')\n          if (lines.length > 1000) {\n            mask.outputBuffer = [lines.slice(-1000).join('\\n')]\n          }\n        }\n        return undefined\n      })\n    }\n\n    // Handle stderr: same as stdout, but write to stderr stream when verbose.\n    if (child.stderr) {\n      child.stderr.on('data', data => {\n        const text = data.toString()\n\n        // Always capture for exit code override.\n        mask.stderrCapture += text\n\n        // Apply filter if provided.\n        if (options.filterOutput && !options.filterOutput(text, 'stderr')) {\n          // Skip this output.\n          return undefined\n        }\n\n        if (mask.verbose) {\n          process.stderr.write(text)\n        } else {\n          mask.outputBuffer.push(text)\n        }\n        return undefined\n      })\n    }\n\n    child.on('exit', code => {\n      // Cleanup keyboard if needed.\n      if (process.stdin.isTTY) {\n        process.stdin.setRawMode(false)\n      }\n\n      // Allow caller to override exit code based on output.\n      let finalCode = code || 0\n      if (options.overrideExitCode) {\n        const overridden = options.overrideExitCode(\n          finalCode,\n          mask.stdoutCapture,\n          mask.stderrCapture,\n        )\n        if (overridden !== undefined) {\n          finalCode = overridden\n        }\n      }\n\n      if (mask.isSpinning) {\n        const spinner = getDefaultSpinner()\n        if (finalCode === 0) {\n          spinner.successAndStop(`${message} completed`)\n        } else {\n          spinner.failAndStop(`${message} failed`)\n          // Show buffered output on failure so user can see what went wrong.\n          if (mask.outputBuffer.length > 0 && !mask.verbose) {\n            console.log('\\n--- Output ---')\n            mask.outputBuffer.forEach(line => {\n              write(line)\n            })\n          }\n        }\n      }\n\n      resolve(finalCode)\n    })\n\n    child.on('error', error => {\n      // Ensure terminal is restored to normal mode on error.\n      if (process.stdin.isTTY) {\n        process.stdin.setRawMode(false)\n      }\n\n      if (mask.isSpinning) {\n        getDefaultSpinner().failAndStop(`${message} error`)\n      }\n      reject(error)\n    })\n  })\n}\n\n/**\n * Run a command with interactive output masking.\n * Convenience wrapper around spawn + attachOutputMask.\n * Spawns a child process and attaches the output masking system to it.\n * stdin is inherited, stdout and stderr are piped for masking control.\n */\nexport async function runWithMask(\n  command: string,\n  args: string[] = [],\n  options: OutputMaskOptions & SpawnOptions = {},\n): Promise<number> {\n  const {\n    message = 'Running\u2026',\n    showOutput = false,\n    toggleText = 'to see output',\n    ...spawnOptions\n  } = options\n\n  const child = spawn(command, args, {\n    stdio: ['inherit', 'pipe', 'pipe'],\n    ...spawnOptions,\n  })\n\n  return await attachOutputMask(child, { message, showOutput, toggleText })\n}\n"],
+  "mappings": ";6iBAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,sBAAAE,EAAA,0BAAAC,EAAA,qBAAAC,EAAA,gBAAAC,IAAA,eAAAC,EAAAN,GAqBA,IAAAO,EAAsB,yBACtBC,EAAqB,uBACrBC,EAAkC,yBAClCC,EAA0B,sBAC1BC,EAAsB,uBAqGf,SAASP,EAAiBQ,EAA6B,CAAC,EAAe,CAC5E,KAAM,CAAE,WAAAC,EAAa,EAAM,EAAID,EAE/B,MAAO,CACL,WAAY,CAACC,EACb,aAAc,CAAC,EACf,cAAe,GACf,cAAe,GACf,QAASA,CACX,CACF,CASO,SAASV,EACdW,EACAC,EACAH,EAA6B,CAAC,EACa,CAC3C,KAAM,CAAE,QAAAI,EAAU,gBAAY,WAAAC,EAAa,oBAAqB,EAAIL,EAEpE,MAAO,CAACM,EAAMC,IAAQ,CAEpB,GAAIA,GAAK,MAAQA,EAAI,OAAS,IAG5B,GAFAL,EAAK,QAAU,CAACA,EAAK,QAEjBA,EAAK,QAEHA,EAAK,gBACP,qBAAkB,EAAE,KAAK,EACzBA,EAAK,WAAa,OAIpB,aAAU,EAGNA,EAAK,aAAa,OAAS,IAC7B,QAAQ,IAAI,iCAAiC,EAC7CA,EAAK,aAAa,QAAQM,GAAQ,IAChC,SAAMA,CAAI,CACZ,CAAC,OAEE,CAGL,GAAIN,EAAK,aAAa,OAAS,EAAG,CAEhC,MAAMO,EAAYP,EAAK,aAAa,KAAK,EAAE,EAAE,MAAM;AAAA,CAAI,EAAE,OAAS,EAKlE,QAASQ,EAAI,EAAGA,EAAID,EAAWC,GAAK,EAClC,QAAQ,OAAO,MAAM,gBAAgB,CAEzC,IACA,aAAU,EAGVR,EAAK,aAAe,CAAC,EAChBA,EAAK,gBACR,qBAAkB,EAAE,MAAM,GAAGE,CAAO,YAAYC,CAAU,GAAG,EAC7DH,EAAK,WAAa,GAEtB,SAGOK,GAAK,MAAQA,EAAI,OAAS,IAEjC,MAAAJ,EAAM,KAAK,SAAS,EAEhB,QAAQ,MAAM,OAChB,QAAQ,MAAM,WAAW,EAAK,EAE1B,IAAI,MAAM,2BAA2B,CAE/C,CACF,CAWO,SAASb,EACda,EACAH,EAA6B,CAAC,EACb,CACjB,OAAO,IAAI,QAAQ,CAACW,EAASC,IAAW,CACtC,KAAM,CAAE,QAAAR,EAAU,eAAW,EAAIJ,EAC3BE,EAAOV,EAAiBQ,CAAO,EAWrC,GARIE,EAAK,YAAc,QAAQ,OAAO,UACpC,qBAAkB,EAAE,MAClB,GAAGE,CAAO,YAAYJ,EAAQ,YAAc,oBAAoB,GAClE,EAKE,QAAQ,MAAM,MAAO,CACvB,EAAAa,QAAS,mBAAmB,QAAQ,KAAK,EACzC,QAAQ,MAAM,WAAW,EAAI,EAE7B,MAAMC,EAAkBvB,EAAsBW,EAAMC,EAAOH,CAAO,EAClE,QAAQ,MAAM,GAAG,WAAYc,CAAe,EAG5CX,EAAM,GAAG,OAAQ,IAAM,CACjB,QAAQ,MAAM,QAChB,QAAQ,MAAM,WAAW,EAAK,EAC9B,QAAQ,MAAM,eAAe,WAAYW,CAAe,EAE5D,CAAC,CACH,CAGIX,EAAM,QACRA,EAAM,OAAO,GAAG,OAAQY,GAAQ,CAC9B,MAAMC,EAAOD,EAAK,SAAS,EAM3B,GAHAb,EAAK,eAAiBc,EAGlB,EAAAhB,EAAQ,cAAgB,CAACA,EAAQ,aAAagB,EAAM,QAAQ,GAKhE,GAAId,EAAK,WACP,SAAMc,CAAI,MACL,CAELd,EAAK,aAAa,KAAKc,CAAI,EAI3B,MAAMC,EAAQf,EAAK,aAAa,KAAK,EAAE,EAAE,MAAM;AAAA,CAAI,EAC/Ce,EAAM,OAAS,MACjBf,EAAK,aAAe,CAACe,EAAM,MAAM,IAAK,EAAE,KAAK;AAAA,CAAI,CAAC,EAEtD,CAEF,CAAC,EAICd,EAAM,QACRA,EAAM,OAAO,GAAG,OAAQY,GAAQ,CAC9B,MAAMC,EAAOD,EAAK,SAAS,EAG3Bb,EAAK,eAAiBc,EAGlB,EAAAhB,EAAQ,cAAgB,CAACA,EAAQ,aAAagB,EAAM,QAAQ,KAK5Dd,EAAK,QACP,QAAQ,OAAO,MAAMc,CAAI,EAEzBd,EAAK,aAAa,KAAKc,CAAI,EAG/B,CAAC,EAGHb,EAAM,GAAG,OAAQe,GAAQ,CAEnB,QAAQ,MAAM,OAChB,QAAQ,MAAM,WAAW,EAAK,EAIhC,IAAIC,EAAYD,GAAQ,EACxB,GAAIlB,EAAQ,iBAAkB,CAC5B,MAAMoB,EAAapB,EAAQ,iBACzBmB,EACAjB,EAAK,cACLA,EAAK,aACP,EACIkB,IAAe,SACjBD,EAAYC,EAEhB,CAEA,GAAIlB,EAAK,WAAY,CACnB,MAAMmB,KAAU,qBAAkB,EAC9BF,IAAc,EAChBE,EAAQ,eAAe,GAAGjB,CAAO,YAAY,GAE7CiB,EAAQ,YAAY,GAAGjB,CAAO,SAAS,EAEnCF,EAAK,aAAa,OAAS,GAAK,CAACA,EAAK,UACxC,QAAQ,IAAI;AAAA,eAAkB,EAC9BA,EAAK,aAAa,QAAQM,GAAQ,IAChC,SAAMA,CAAI,CACZ,CAAC,GAGP,CAEAG,EAAQQ,CAAS,CACnB,CAAC,EAEDhB,EAAM,GAAG,QAASmB,GAAS,CAErB,QAAQ,MAAM,OAChB,QAAQ,MAAM,WAAW,EAAK,EAG5BpB,EAAK,eACP,qBAAkB,EAAE,YAAY,GAAGE,CAAO,QAAQ,EAEpDQ,EAAOU,CAAK,CACd,CAAC,CACH,CAAC,CACH,CAQA,eAAsB7B,EACpB8B,EACAC,EAAiB,CAAC,EAClBxB,EAA4C,CAAC,EAC5B,CACjB,KAAM,CACJ,QAAAI,EAAU,gBACV,WAAAH,EAAa,GACb,WAAAI,EAAa,gBACb,GAAGoB,CACL,EAAIzB,EAEEG,KAAQ,SAAMoB,EAASC,EAAM,CACjC,MAAO,CAAC,UAAW,OAAQ,MAAM,EACjC,GAAGC,CACL,CAAC,EAED,OAAO,MAAMnC,EAAiBa,EAAO,CAAE,QAAAC,EAAS,WAAAH,EAAY,WAAAI,CAAW,CAAC,CAC1E",
+  "names": ["mask_exports", "__export", "attachOutputMask", "createKeyboardHandler", "createOutputMask", "runWithMask", "__toCommonJS", "import_child_process", "import_readline", "import_spinner", "import_clear", "import_stdout", "options", "showOutput", "mask", "child", "message", "toggleText", "_str", "key", "line", "lineCount", "i", "resolve", "reject", "readline", "keypressHandler", "data", "text", "lines", "code", "finalCode", "overridden", "spinner", "error", "command", "args", "spawnOptions"]
 }

package/dist/stdio/stdout.js

@@ -1,4 +1,4 @@
 /* Socket Lib - Built with esbuild */
-var s=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var T=Object.prototype.hasOwnProperty;var x=(r,e)=>{for(var i in e)s(r,i,{get:e[i],enumerable:!0})},d=(r,e,i,c)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of p(e))!T.call(r,n)&&n!==i&&s(r,n,{get:()=>e[n],enumerable:!(c=f(e,n))||c.enumerable});return r};var w=r=>d(s({},"__esModule",{value:!0}),r);var I={};x(I,{clearLine:()=>l,clearScreenDown:()=>S,cursorTo:()=>v,ensureCursorOnExit:()=>h,getColumns:()=>b,getRows:()=>g,hideCursor:()=>C,isTTY:()=>Y,showCursor:()=>t,stdout:()=>o,write:()=>m,writeLine:()=>a});module.exports=w(I);var u=require("node:tty");const o=process.stdout;function a(r=""){o.write(`${r}
+var s=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var T=Object.prototype.hasOwnProperty;var x=(r,e)=>{for(var i in e)s(r,i,{get:e[i],enumerable:!0})},d=(r,e,i,c)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of p(e))!T.call(r,n)&&n!==i&&s(r,n,{get:()=>e[n],enumerable:!(c=f(e,n))||c.enumerable});return r};var w=r=>d(s({},"__esModule",{value:!0}),r);var I={};x(I,{clearLine:()=>l,clearScreenDown:()=>S,cursorTo:()=>v,ensureCursorOnExit:()=>h,getColumns:()=>b,getRows:()=>g,hideCursor:()=>C,isTTY:()=>Y,showCursor:()=>t,stdout:()=>o,write:()=>m,writeLine:()=>a});module.exports=w(I);var u=require("tty");const o=process.stdout;function a(r=""){o.write(`${r}
 `)}function m(r){o.write(r)}function l(){o.isTTY&&(o.cursorTo(0),o.clearLine(0))}function v(r,e){o.isTTY&&o.cursorTo(r,e)}function S(){o.isTTY&&o.clearScreenDown()}function Y(){return o.isTTY||!1}function b(){return o.columns||80}function g(){return o.rows||24}function C(){o.isTTY&&o instanceof u.WriteStream&&o.write("\x1B[?25l")}function t(){o.isTTY&&o instanceof u.WriteStream&&o.write("\x1B[?25h")}function h(){process.on("exit",t),process.on("SIGINT",()=>{t(),process.exit(130)}),process.on("SIGTERM",()=>{t(),process.exit(143)})}0&&(module.exports={clearLine,clearScreenDown,cursorTo,ensureCursorOnExit,getColumns,getRows,hideCursor,isTTY,showCursor,stdout,write,writeLine});
 //# sourceMappingURL=stdout.js.map

package/dist/stdio/stdout.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/stdio/stdout.ts"],
-  "sourcesContent": ["/**\n * @fileoverview Standard output stream utilities.\n * Provides utilities for writing to stdout with formatting and control.\n */\n\nimport { WriteStream } from 'node:tty'\n\n// Get the actual stdout stream\nconst stdout: NodeJS.WriteStream = process.stdout\n\n/**\n * Write a line to stdout with trailing newline.\n *\n * @param text - Text to write\n * @default text ''\n *\n * @example\n * ```ts\n * writeLine('Hello, world!')\n * writeLine() // Write empty line\n * ```\n */\nexport function writeLine(text: string = ''): void {\n  stdout.write(`${text}\\n`)\n}\n\n/**\n * Write text to stdout without adding a newline.\n *\n * @param text - Text to write\n *\n * @example\n * ```ts\n * write('Loading...')\n * // Later: clear and update\n * ```\n */\nexport function write(text: string): void {\n  stdout.write(text)\n}\n\n/**\n * Clear the current line on stdout.\n * Only works in TTY environments.\n *\n * @example\n * ```ts\n * write('Processing...')\n * clearLine()\n * write('Done!')\n * ```\n */\nexport function clearLine(): void {\n  if (stdout.isTTY) {\n    stdout.cursorTo(0)\n    stdout.clearLine(0)\n  }\n}\n\n/**\n * Move cursor to specific position on stdout.\n * Only works in TTY environments.\n *\n * @param x - Column position (0-based)\n * @param y - Row position (0-based, optional)\n *\n * @example\n * ```ts\n * cursorTo(0) // Move to start of line\n * cursorTo(10, 5) // Move to column 10, row 5\n * ```\n */\nexport function cursorTo(x: number, y?: number | undefined): void {\n  if (stdout.isTTY) {\n    stdout.cursorTo(x, y)\n  }\n}\n\n/**\n * Clear screen from cursor position down to bottom.\n * Only works in TTY environments.\n *\n * @example\n * ```ts\n * cursorTo(0, 5)\n * clearScreenDown() // Clear from row 5 to bottom\n * ```\n */\nexport function clearScreenDown(): void {\n  if (stdout.isTTY) {\n    stdout.clearScreenDown()\n  }\n}\n\n/**\n * Check if stdout is connected to a TTY (terminal).\n *\n * @returns `true` if stdout is a TTY, `false` if piped/redirected\n *\n * @example\n * ```ts\n * if (isTTY()) {\n *   // Show interactive UI\n * } else {\n *   // Use simple text output\n * }\n * ```\n */\nexport function isTTY(): boolean {\n  return stdout.isTTY || false\n}\n\n/**\n * Get the number of columns (width) in the terminal.\n *\n * @returns Terminal width in characters\n * @default 80\n *\n * @example\n * ```ts\n * const width = getColumns()\n * console.log(`Terminal is ${width} characters wide`)\n * ```\n */\nexport function getColumns(): number {\n  return stdout.columns || 80\n}\n\n/**\n * Get the number of rows (height) in the terminal.\n *\n * @returns Terminal height in lines\n * @default 24\n *\n * @example\n * ```ts\n * const height = getRows()\n * console.log(`Terminal is ${height} lines tall`)\n * ```\n */\nexport function getRows(): number {\n  return stdout.rows || 24\n}\n\n/**\n * Hide the cursor on stdout.\n * Useful for cleaner output during animations.\n *\n * @example\n * ```ts\n * hideCursor()\n * // Show animation\n * showCursor()\n * ```\n */\nexport function hideCursor(): void {\n  if (stdout.isTTY && stdout instanceof WriteStream) {\n    stdout.write('\\u001B[?25l')\n  }\n}\n\n/**\n * Show the cursor on stdout.\n * Should be called after `hideCursor()`.\n *\n * @example\n * ```ts\n * hideCursor()\n * // Show animation\n * showCursor()\n * ```\n */\nexport function showCursor(): void {\n  if (stdout.isTTY && stdout instanceof WriteStream) {\n    stdout.write('\\u001B[?25h')\n  }\n}\n\n/**\n * Register handlers to ensure cursor is shown on process exit.\n * Prevents hidden cursor after abnormal termination.\n * Handles SIGINT (Ctrl+C) and SIGTERM signals.\n *\n * @example\n * ```ts\n * ensureCursorOnExit()\n * hideCursor()\n * // Even if process crashes, cursor will be restored\n * ```\n */\nexport function ensureCursorOnExit(): void {\n  process.on('exit', showCursor)\n  process.on('SIGINT', () => {\n    showCursor()\n    // eslint-disable-next-line n/no-process-exit\n    process.exit(130)\n  })\n  process.on('SIGTERM', () => {\n    showCursor()\n    // eslint-disable-next-line n/no-process-exit\n    process.exit(143)\n  })\n}\n\n// Export the raw stream for advanced usage\nexport { stdout }\n"],
-  "mappings": ";4ZAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,eAAAE,EAAA,oBAAAC,EAAA,aAAAC,EAAA,uBAAAC,EAAA,eAAAC,EAAA,YAAAC,EAAA,eAAAC,EAAA,UAAAC,EAAA,eAAAC,EAAA,WAAAC,EAAA,UAAAC,EAAA,cAAAC,IAAA,eAAAC,EAAAd,GAKA,IAAAe,EAA4B,oBAG5B,MAAMJ,EAA6B,QAAQ,OAcpC,SAASE,EAAUG,EAAe,GAAU,CACjDL,EAAO,MAAM,GAAGK,CAAI;AAAA,CAAI,CAC1B,CAaO,SAASJ,EAAMI,EAAoB,CACxCL,EAAO,MAAMK,CAAI,CACnB,CAaO,SAASd,GAAkB,CAC5BS,EAAO,QACTA,EAAO,SAAS,CAAC,EACjBA,EAAO,UAAU,CAAC,EAEtB,CAeO,SAASP,EAASa,EAAWC,EAA8B,CAC5DP,EAAO,OACTA,EAAO,SAASM,EAAGC,CAAC,CAExB,CAYO,SAASf,GAAwB,CAClCQ,EAAO,OACTA,EAAO,gBAAgB,CAE3B,CAgBO,SAASF,GAAiB,CAC/B,OAAOE,EAAO,OAAS,EACzB,CAcO,SAASL,GAAqB,CACnC,OAAOK,EAAO,SAAW,EAC3B,CAcO,SAASJ,GAAkB,CAChC,OAAOI,EAAO,MAAQ,EACxB,CAaO,SAASH,GAAmB,CAC7BG,EAAO,OAASA,aAAkB,eACpCA,EAAO,MAAM,WAAa,CAE9B,CAaO,SAASD,GAAmB,CAC7BC,EAAO,OAASA,aAAkB,eACpCA,EAAO,MAAM,WAAa,CAE9B,CAcO,SAASN,GAA2B,CACzC,QAAQ,GAAG,OAAQK,CAAU,EAC7B,QAAQ,GAAG,SAAU,IAAM,CACzBA,EAAW,EAEX,QAAQ,KAAK,GAAG,CAClB,CAAC,EACD,QAAQ,GAAG,UAAW,IAAM,CAC1BA,EAAW,EAEX,QAAQ,KAAK,GAAG,CAClB,CAAC,CACH",
-  "names": ["stdout_exports", "__export", "clearLine", "clearScreenDown", "cursorTo", "ensureCursorOnExit", "getColumns", "getRows", "hideCursor", "isTTY", "showCursor", "stdout", "write", "writeLine", "__toCommonJS", "import_node_tty", "text", "x", "y"]
+  "sourcesContent": ["/**\n * @fileoverview Standard output stream utilities.\n * Provides utilities for writing to stdout with formatting and control.\n */\n\nimport { WriteStream } from 'tty'\n\n// Get the actual stdout stream\nconst stdout: NodeJS.WriteStream = process.stdout\n\n/**\n * Write a line to stdout with trailing newline.\n *\n * @param text - Text to write\n * @default text ''\n *\n * @example\n * ```ts\n * writeLine('Hello, world!')\n * writeLine() // Write empty line\n * ```\n */\nexport function writeLine(text: string = ''): void {\n  stdout.write(`${text}\\n`)\n}\n\n/**\n * Write text to stdout without adding a newline.\n *\n * @param text - Text to write\n *\n * @example\n * ```ts\n * write('Loading...')\n * // Later: clear and update\n * ```\n */\nexport function write(text: string): void {\n  stdout.write(text)\n}\n\n/**\n * Clear the current line on stdout.\n * Only works in TTY environments.\n *\n * @example\n * ```ts\n * write('Processing...')\n * clearLine()\n * write('Done!')\n * ```\n */\nexport function clearLine(): void {\n  if (stdout.isTTY) {\n    stdout.cursorTo(0)\n    stdout.clearLine(0)\n  }\n}\n\n/**\n * Move cursor to specific position on stdout.\n * Only works in TTY environments.\n *\n * @param x - Column position (0-based)\n * @param y - Row position (0-based, optional)\n *\n * @example\n * ```ts\n * cursorTo(0) // Move to start of line\n * cursorTo(10, 5) // Move to column 10, row 5\n * ```\n */\nexport function cursorTo(x: number, y?: number | undefined): void {\n  if (stdout.isTTY) {\n    stdout.cursorTo(x, y)\n  }\n}\n\n/**\n * Clear screen from cursor position down to bottom.\n * Only works in TTY environments.\n *\n * @example\n * ```ts\n * cursorTo(0, 5)\n * clearScreenDown() // Clear from row 5 to bottom\n * ```\n */\nexport function clearScreenDown(): void {\n  if (stdout.isTTY) {\n    stdout.clearScreenDown()\n  }\n}\n\n/**\n * Check if stdout is connected to a TTY (terminal).\n *\n * @returns `true` if stdout is a TTY, `false` if piped/redirected\n *\n * @example\n * ```ts\n * if (isTTY()) {\n *   // Show interactive UI\n * } else {\n *   // Use simple text output\n * }\n * ```\n */\nexport function isTTY(): boolean {\n  return stdout.isTTY || false\n}\n\n/**\n * Get the number of columns (width) in the terminal.\n *\n * @returns Terminal width in characters\n * @default 80\n *\n * @example\n * ```ts\n * const width = getColumns()\n * console.log(`Terminal is ${width} characters wide`)\n * ```\n */\nexport function getColumns(): number {\n  return stdout.columns || 80\n}\n\n/**\n * Get the number of rows (height) in the terminal.\n *\n * @returns Terminal height in lines\n * @default 24\n *\n * @example\n * ```ts\n * const height = getRows()\n * console.log(`Terminal is ${height} lines tall`)\n * ```\n */\nexport function getRows(): number {\n  return stdout.rows || 24\n}\n\n/**\n * Hide the cursor on stdout.\n * Useful for cleaner output during animations.\n *\n * @example\n * ```ts\n * hideCursor()\n * // Show animation\n * showCursor()\n * ```\n */\nexport function hideCursor(): void {\n  if (stdout.isTTY && stdout instanceof WriteStream) {\n    stdout.write('\\u001B[?25l')\n  }\n}\n\n/**\n * Show the cursor on stdout.\n * Should be called after `hideCursor()`.\n *\n * @example\n * ```ts\n * hideCursor()\n * // Show animation\n * showCursor()\n * ```\n */\nexport function showCursor(): void {\n  if (stdout.isTTY && stdout instanceof WriteStream) {\n    stdout.write('\\u001B[?25h')\n  }\n}\n\n/**\n * Register handlers to ensure cursor is shown on process exit.\n * Prevents hidden cursor after abnormal termination.\n * Handles SIGINT (Ctrl+C) and SIGTERM signals.\n *\n * @example\n * ```ts\n * ensureCursorOnExit()\n * hideCursor()\n * // Even if process crashes, cursor will be restored\n * ```\n */\nexport function ensureCursorOnExit(): void {\n  process.on('exit', showCursor)\n  process.on('SIGINT', () => {\n    showCursor()\n    // eslint-disable-next-line n/no-process-exit\n    process.exit(130)\n  })\n  process.on('SIGTERM', () => {\n    showCursor()\n    // eslint-disable-next-line n/no-process-exit\n    process.exit(143)\n  })\n}\n\n// Export the raw stream for advanced usage\nexport { stdout }\n"],
+  "mappings": ";4ZAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,eAAAE,EAAA,oBAAAC,EAAA,aAAAC,EAAA,uBAAAC,EAAA,eAAAC,EAAA,YAAAC,EAAA,eAAAC,EAAA,UAAAC,EAAA,eAAAC,EAAA,WAAAC,EAAA,UAAAC,EAAA,cAAAC,IAAA,eAAAC,EAAAd,GAKA,IAAAe,EAA4B,eAG5B,MAAMJ,EAA6B,QAAQ,OAcpC,SAASE,EAAUG,EAAe,GAAU,CACjDL,EAAO,MAAM,GAAGK,CAAI;AAAA,CAAI,CAC1B,CAaO,SAASJ,EAAMI,EAAoB,CACxCL,EAAO,MAAMK,CAAI,CACnB,CAaO,SAASd,GAAkB,CAC5BS,EAAO,QACTA,EAAO,SAAS,CAAC,EACjBA,EAAO,UAAU,CAAC,EAEtB,CAeO,SAASP,EAASa,EAAWC,EAA8B,CAC5DP,EAAO,OACTA,EAAO,SAASM,EAAGC,CAAC,CAExB,CAYO,SAASf,GAAwB,CAClCQ,EAAO,OACTA,EAAO,gBAAgB,CAE3B,CAgBO,SAASF,GAAiB,CAC/B,OAAOE,EAAO,OAAS,EACzB,CAcO,SAASL,GAAqB,CACnC,OAAOK,EAAO,SAAW,EAC3B,CAcO,SAASJ,GAAkB,CAChC,OAAOI,EAAO,MAAQ,EACxB,CAaO,SAASH,GAAmB,CAC7BG,EAAO,OAASA,aAAkB,eACpCA,EAAO,MAAM,WAAa,CAE9B,CAaO,SAASD,GAAmB,CAC7BC,EAAO,OAASA,aAAkB,eACpCA,EAAO,MAAM,WAAa,CAE9B,CAcO,SAASN,GAA2B,CACzC,QAAQ,GAAG,OAAQK,CAAU,EAC7B,QAAQ,GAAG,SAAU,IAAM,CACzBA,EAAW,EAEX,QAAQ,KAAK,GAAG,CAClB,CAAC,EACD,QAAQ,GAAG,UAAW,IAAM,CAC1BA,EAAW,EAEX,QAAQ,KAAK,GAAG,CAClB,CAAC,CACH",
+  "names": ["stdout_exports", "__export", "clearLine", "clearScreenDown", "cursorTo", "ensureCursorOnExit", "getColumns", "getRows", "hideCursor", "isTTY", "showCursor", "stdout", "write", "writeLine", "__toCommonJS", "import_tty", "text", "x", "y"]
 }

package/dist/themes/context.d.ts

@@ -0,0 +1,80 @@
+import type { Theme } from './types';
+import { type ThemeName } from './themes';
+/**
+ * Theme change event listener signature.
+ */
+export type ThemeChangeListener = (theme: Theme) => void;
+/**
+ * Set the global fallback theme.
+ *
+ * @param theme - Theme name or object
+ *
+ * @example
+ * ```ts
+ * setTheme('socket-firewall')
+ * ```
+ */
+export declare function setTheme(theme: Theme | ThemeName): void;
+/**
+ * Get the active theme from context.
+ *
+ * @returns Current theme
+ *
+ * @example
+ * ```ts
+ * const theme = getTheme()
+ * console.log(theme.displayName)
+ * ```
+ */
+export declare function getTheme(): Theme;
+/**
+ * Execute async operation with scoped theme.
+ * Theme automatically restored on completion.
+ *
+ * @template T - Return type
+ * @param theme - Scoped theme
+ * @param fn - Async operation
+ * @returns Operation result
+ *
+ * @example
+ * ```ts
+ * await withTheme('ultra', async () => {
+ *   // Operations use Ultra theme
+ * })
+ * ```
+ */
+export declare function withTheme<T>(theme: Theme | ThemeName, fn: () => Promise<T>): Promise<T>;
+/**
+ * Execute sync operation with scoped theme.
+ * Theme automatically restored on completion.
+ *
+ * @template T - Return type
+ * @param theme - Scoped theme
+ * @param fn - Sync operation
+ * @returns Operation result
+ *
+ * @example
+ * ```ts
+ * const result = withThemeSync('coana', () => {
+ *   return processData()
+ * })
+ * ```
+ */
+export declare function withThemeSync<T>(theme: Theme | ThemeName, fn: () => T): T;
+/**
+ * Subscribe to theme change events.
+ *
+ * @param listener - Change handler
+ * @returns Unsubscribe function
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = onThemeChange((theme) => {
+ *   console.log('Theme:', theme.displayName)
+ * })
+ *
+ * // Cleanup
+ * unsubscribe()
+ * ```
+ */
+export declare function onThemeChange(listener: ThemeChangeListener): () => void;

package/dist/themes/context.js

@@ -0,0 +1,3 @@
+/* Socket Lib - Built with esbuild */
+var m=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var u=Object.prototype.hasOwnProperty;var g=(e,t)=>{for(var n in t)m(e,n,{get:t[n],enumerable:!0})},y=(e,t,n,a)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of f(t))!u.call(e,r)&&r!==n&&m(e,r,{get:()=>t[r],enumerable:!(a=p(t,r))||a.enumerable});return e};var d=e=>y(m({},"__esModule",{value:!0}),e);var C={};g(C,{getTheme:()=>S,onThemeChange:()=>x,setTheme:()=>l,withTheme:()=>v,withThemeSync:()=>w});module.exports=d(C);var c=require("node:async_hooks"),o=require("./themes");const i=new c.AsyncLocalStorage;let T=o.SOCKET_THEME;const h=new Set;function l(e){T=typeof e=="string"?o.THEMES[e]:e,s(T)}function S(){return i.getStore()??T}async function v(e,t){const n=typeof e=="string"?o.THEMES[e]:e;return await i.run(n,async()=>(s(n),await t()))}function w(e,t){const n=typeof e=="string"?o.THEMES[e]:e;return i.run(n,()=>(s(n),t()))}function x(e){return h.add(e),()=>{h.delete(e)}}function s(e){for(const t of h)t(e)}0&&(module.exports={getTheme,onThemeChange,setTheme,withTheme,withThemeSync});
+//# sourceMappingURL=context.js.map

package/dist/themes/context.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/themes/context.ts"],
+  "sourcesContent": ["/**\n * @fileoverview Elegant theme context management.\n * Async-aware theming with automatic context isolation via AsyncLocalStorage.\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks'\n\nimport type { Theme } from './types'\nimport { SOCKET_THEME, THEMES, type ThemeName } from './themes'\n\n/**\n * Theme change event listener signature.\n */\nexport type ThemeChangeListener = (theme: Theme) => void\n\n/**\n * AsyncLocalStorage for theme context isolation.\n */\nconst themeStorage = new AsyncLocalStorage<Theme>()\n\n/**\n * Fallback theme for global context.\n */\nlet fallbackTheme: Theme = SOCKET_THEME\n\n/**\n * Registered theme change listeners.\n */\nconst listeners: Set<ThemeChangeListener> = new Set()\n\n/**\n * Set the global fallback theme.\n *\n * @param theme - Theme name or object\n *\n * @example\n * ```ts\n * setTheme('socket-firewall')\n * ```\n */\nexport function setTheme(theme: Theme | ThemeName): void {\n  fallbackTheme = typeof theme === 'string' ? THEMES[theme] : theme\n  emitThemeChange(fallbackTheme)\n}\n\n/**\n * Get the active theme from context.\n *\n * @returns Current theme\n *\n * @example\n * ```ts\n * const theme = getTheme()\n * console.log(theme.displayName)\n * ```\n */\nexport function getTheme(): Theme {\n  return themeStorage.getStore() ?? fallbackTheme\n}\n\n/**\n * Execute async operation with scoped theme.\n * Theme automatically restored on completion.\n *\n * @template T - Return type\n * @param theme - Scoped theme\n * @param fn - Async operation\n * @returns Operation result\n *\n * @example\n * ```ts\n * await withTheme('ultra', async () => {\n *   // Operations use Ultra theme\n * })\n * ```\n */\nexport async function withTheme<T>(\n  theme: Theme | ThemeName,\n  fn: () => Promise<T>,\n): Promise<T> {\n  const resolvedTheme = typeof theme === 'string' ? THEMES[theme] : theme\n  return await themeStorage.run(resolvedTheme, async () => {\n    emitThemeChange(resolvedTheme)\n    return await fn()\n  })\n}\n\n/**\n * Execute sync operation with scoped theme.\n * Theme automatically restored on completion.\n *\n * @template T - Return type\n * @param theme - Scoped theme\n * @param fn - Sync operation\n * @returns Operation result\n *\n * @example\n * ```ts\n * const result = withThemeSync('coana', () => {\n *   return processData()\n * })\n * ```\n */\nexport function withThemeSync<T>(theme: Theme | ThemeName, fn: () => T): T {\n  const resolvedTheme = typeof theme === 'string' ? THEMES[theme] : theme\n  return themeStorage.run(resolvedTheme, () => {\n    emitThemeChange(resolvedTheme)\n    return fn()\n  })\n}\n\n/**\n * Subscribe to theme change events.\n *\n * @param listener - Change handler\n * @returns Unsubscribe function\n *\n * @example\n * ```ts\n * const unsubscribe = onThemeChange((theme) => {\n *   console.log('Theme:', theme.displayName)\n * })\n *\n * // Cleanup\n * unsubscribe()\n * ```\n */\nexport function onThemeChange(listener: ThemeChangeListener): () => void {\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\n/**\n * Emit theme change event to listeners.\n * @private\n */\nfunction emitThemeChange(theme: Theme): void {\n  for (const listener of listeners) {\n    listener(theme)\n  }\n}\n"],
+  "mappings": ";4ZAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,cAAAE,EAAA,kBAAAC,EAAA,aAAAC,EAAA,cAAAC,EAAA,kBAAAC,IAAA,eAAAC,EAAAP,GAKA,IAAAQ,EAAkC,4BAGlCC,EAAqD,oBAUrD,MAAMC,EAAe,IAAI,oBAKzB,IAAIC,EAAuB,eAK3B,MAAMC,EAAsC,IAAI,IAYzC,SAASR,EAASS,EAAgC,CACvDF,EAAgB,OAAOE,GAAU,SAAW,SAAOA,CAAK,EAAIA,EAC5DC,EAAgBH,CAAa,CAC/B,CAaO,SAAST,GAAkB,CAChC,OAAOQ,EAAa,SAAS,GAAKC,CACpC,CAkBA,eAAsBN,EACpBQ,EACAE,EACY,CACZ,MAAMC,EAAgB,OAAOH,GAAU,SAAW,SAAOA,CAAK,EAAIA,EAClE,OAAO,MAAMH,EAAa,IAAIM,EAAe,UAC3CF,EAAgBE,CAAa,EACtB,MAAMD,EAAG,EACjB,CACH,CAkBO,SAAST,EAAiBO,EAA0BE,EAAgB,CACzE,MAAMC,EAAgB,OAAOH,GAAU,SAAW,SAAOA,CAAK,EAAIA,EAClE,OAAOH,EAAa,IAAIM,EAAe,KACrCF,EAAgBE,CAAa,EACtBD,EAAG,EACX,CACH,CAkBO,SAASZ,EAAcc,EAA2C,CACvE,OAAAL,EAAU,IAAIK,CAAQ,EACf,IAAM,CACXL,EAAU,OAAOK,CAAQ,CAC3B,CACF,CAMA,SAASH,EAAgBD,EAAoB,CAC3C,UAAWI,KAAYL,EACrBK,EAASJ,CAAK,CAElB",
+  "names": ["context_exports", "__export", "getTheme", "onThemeChange", "setTheme", "withTheme", "withThemeSync", "__toCommonJS", "import_node_async_hooks", "import_themes", "themeStorage", "fallbackTheme", "listeners", "theme", "emitThemeChange", "fn", "resolvedTheme", "listener"]
+}

package/dist/themes/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Elegant theming system for Socket libraries.
+ * Unified visual language across spinners, loggers, prompts, and links.
+ *
+ * @example
+ * ```ts
+ * import { setTheme, THEMES } from '@socketsecurity/lib/themes'
+ *
+ * // Set global theme
+ * setTheme('brick')
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { withTheme } from '@socketsecurity/lib/themes'
+ *
+ * // Scoped theme context
+ * await withTheme('ultra', async () => {
+ *   // All operations inherit Ultra theme
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { createTheme } from '@socketsecurity/lib/themes'
+ *
+ * // Custom theme creation
+ * const myTheme = createTheme({
+ *   name: 'custom',
+ *   displayName: 'Custom Theme',
+ *   colors: {
+ *     primary: [255, 100, 200],
+ *     success: 'greenBright',
+ *     error: 'redBright',
+ *     warning: 'yellowBright',
+ *     info: 'blueBright',
+ *     step: 'cyanBright',
+ *     text: 'white',
+ *     textDim: 'gray',
+ *     link: 'cyanBright',
+ *     prompt: 'primary'
+ *   }
+ * })
+ * ```
+ */
+// Type system
+export type { ColorReference, Theme, ThemeColors, ThemeEffects, ThemeMeta, } from './types';
+// Curated themes
+export { BRICK_THEME, LUSH_THEME, SOCKET_THEME, SUNSET_THEME, THEMES, ULTRA_THEME, type ThemeName, } from './themes';
+// Context management
+export { getTheme, onThemeChange, setTheme, withTheme, withThemeSync, type ThemeChangeListener, } from './context';
+// Composition utilities
+export { createTheme, extendTheme, resolveColor, resolveShimmerColor, } from './utils';

package/dist/themes/index.js

@@ -0,0 +1,3 @@
+/* Socket Lib - Built with esbuild */
+var E=Object.defineProperty;var C=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var n=Object.prototype.hasOwnProperty;var s=(h,m)=>{for(var t in m)E(h,t,{get:m[t],enumerable:!0})},H=(h,m,t,p)=>{if(m&&typeof m=="object"||typeof m=="function")for(let r of f(m))!n.call(h,r)&&r!==t&&E(h,r,{get:()=>m[r],enumerable:!(p=C(m,r))||p.enumerable});return h};var M=h=>H(E({},"__esModule",{value:!0}),h);var S={};s(S,{BRICK_THEME:()=>e.BRICK_THEME,LUSH_THEME:()=>e.LUSH_THEME,SOCKET_THEME:()=>e.SOCKET_THEME,SUNSET_THEME:()=>e.SUNSET_THEME,THEMES:()=>e.THEMES,ULTRA_THEME:()=>e.ULTRA_THEME,createTheme:()=>o.createTheme,extendTheme:()=>o.extendTheme,getTheme:()=>T.getTheme,onThemeChange:()=>T.onThemeChange,resolveColor:()=>o.resolveColor,resolveShimmerColor:()=>o.resolveShimmerColor,setTheme:()=>T.setTheme,withTheme:()=>T.withTheme,withThemeSync:()=>T.withThemeSync});module.exports=M(S);var e=require("./themes"),T=require("./context"),o=require("./utils");0&&(module.exports={BRICK_THEME,LUSH_THEME,SOCKET_THEME,SUNSET_THEME,THEMES,ULTRA_THEME,createTheme,extendTheme,getTheme,onThemeChange,resolveColor,resolveShimmerColor,setTheme,withTheme,withThemeSync});
+//# sourceMappingURL=index.js.map

package/dist/themes/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/themes/index.ts"],
+  "sourcesContent": ["/**\n * @fileoverview Elegant theming system for Socket libraries.\n * Unified visual language across spinners, loggers, prompts, and links.\n *\n * @example\n * ```ts\n * import { setTheme, THEMES } from '@socketsecurity/lib/themes'\n *\n * // Set global theme\n * setTheme('brick')\n * ```\n *\n * @example\n * ```ts\n * import { withTheme } from '@socketsecurity/lib/themes'\n *\n * // Scoped theme context\n * await withTheme('ultra', async () => {\n *   // All operations inherit Ultra theme\n * })\n * ```\n *\n * @example\n * ```ts\n * import { createTheme } from '@socketsecurity/lib/themes'\n *\n * // Custom theme creation\n * const myTheme = createTheme({\n *   name: 'custom',\n *   displayName: 'Custom Theme',\n *   colors: {\n *     primary: [255, 100, 200],\n *     success: 'greenBright',\n *     error: 'redBright',\n *     warning: 'yellowBright',\n *     info: 'blueBright',\n *     step: 'cyanBright',\n *     text: 'white',\n *     textDim: 'gray',\n *     link: 'cyanBright',\n *     prompt: 'primary'\n *   }\n * })\n * ```\n */\n\n// Type system\nexport type {\n  ColorReference,\n  Theme,\n  ThemeColors,\n  ThemeEffects,\n  ThemeMeta,\n} from './types'\n\n// Curated themes\nexport {\n  BRICK_THEME,\n  LUSH_THEME,\n  SOCKET_THEME,\n  SUNSET_THEME,\n  THEMES,\n  ULTRA_THEME,\n  type ThemeName,\n} from './themes'\n\n// Context management\nexport {\n  getTheme,\n  onThemeChange,\n  setTheme,\n  withTheme,\n  withThemeSync,\n  type ThemeChangeListener,\n} from './context'\n\n// Composition utilities\nexport {\n  createTheme,\n  extendTheme,\n  resolveColor,\n  resolveShimmerColor,\n} from './utils'\n"],
+  "mappings": ";4ZAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,sdAAAE,EAAAF,GAwDA,IAAAG,EAQO,oBAGPC,EAOO,qBAGPC,EAKO",
+  "names": ["themes_exports", "__export", "__toCommonJS", "import_themes", "import_context", "import_utils"]
+}

package/dist/themes/themes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Elegant theme definitions for Socket libraries.
+ * Sophisticated color palettes crafted for clarity and visual harmony.
+ *
+ * Philosophy: Every color choice serves a purpose. Bright variants ensure
+ * terminal legibility without compromising sophistication. Minimal emoji use,
+ * refined symbols with color—elegance in restraint.
+ */
+import type { Theme } from './types';
+/**
+ * Socket Security — The signature theme.
+ * Refined violet with subtle shimmer, designed for focus and elegance.
+ */
+export declare const SOCKET_THEME: Theme;
+/**
+ * Sunset — Crisp azure.
+ * Clean analytical theme with precise blue tones.
+ */
+export declare const SUNSET_THEME: Theme;
+/**
+ * Brick — Solid warmth.
+ * Rich terracotta and ember tones for grounded confidence.
+ */
+export declare const BRICK_THEME: Theme;
+/**
+ * Lush — Steel elegance.
+ * Python-inspired steel blue with golden accents.
+ */
+export declare const LUSH_THEME: Theme;
+/**
+ * Ultra — Premium intensity.
+ * Prismatic shimmer for deep analysis, where complexity meets elegance.
+ */
+export declare const ULTRA_THEME: Theme;
+/**
+ * Theme registry — Curated palette collection.
+ */
+export declare const THEMES: {
+    readonly __proto__: any;
+    readonly socket: Theme;
+    readonly sunset: Theme;
+    readonly brick: Theme;
+    readonly lush: Theme;
+    readonly ultra: Theme;
+};
+/**
+ * Available theme identifiers.
+ */
+export type ThemeName = keyof typeof THEMES;

package/dist/themes/themes.js

@@ -0,0 +1,3 @@
+/* Socket Lib - Built with esbuild */
+var o=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var l=Object.getOwnPropertyNames;var y=Object.prototype.hasOwnProperty;var g=(r,e)=>{for(var i in e)o(r,i,{get:e[i],enumerable:!0})},d=(r,e,i,s)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of l(e))!y.call(r,t)&&t!==i&&o(r,t,{get:()=>e[t],enumerable:!(s=p(e,t))||s.enumerable});return r};var B=r=>d(o({},"__esModule",{value:!0}),r);var f={};g(f,{BRICK_THEME:()=>c,LUSH_THEME:()=>m,SOCKET_THEME:()=>n,SUNSET_THEME:()=>a,THEMES:()=>u,ULTRA_THEME:()=>h});module.exports=B(f);const n={name:"socket",displayName:"Socket Security",colors:{primary:[140,82,255],success:"greenBright",error:"redBright",warning:"yellowBright",info:"blueBright",step:"cyanBright",text:"white",textDim:"gray",link:"cyanBright",prompt:"primary"},effects:{spinner:{color:"primary",style:"socket"},shimmer:{enabled:!0,color:"inherit",direction:"ltr",speed:.33}},meta:{description:"Signature theme with refined violet and subtle shimmer",version:"1.0.0"}},a={name:"sunset",displayName:"Sunset",colors:{primary:[100,200,255],secondary:[50,150,200],success:"greenBright",error:"redBright",warning:"yellowBright",info:"blueBright",step:"cyanBright",text:"white",textDim:"gray",link:"cyanBright",prompt:"primary"},effects:{spinner:{color:"primary",style:"dots"}},meta:{description:"Crisp azure theme for precision and clarity",version:"1.0.0"}},c={name:"brick",displayName:"Brick",colors:{primary:[255,100,50],secondary:[255,150,100],success:"greenBright",error:"redBright",warning:"yellowBright",info:"blueBright",step:"cyanBright",text:"white",textDim:"gray",link:"secondary",prompt:"primary"},effects:{spinner:{color:"primary",style:"socket"},shimmer:{enabled:!0,color:"inherit",direction:"ltr",speed:.5}},meta:{description:"Solid theme with rich terracotta and ember warmth",version:"1.0.0"}},m={name:"lush",displayName:"Lush",colors:{primary:[70,130,180],secondary:[255,215,0],success:"greenBright",error:"redBright",warning:"yellowBright",info:"blueBright",step:"cyanBright",text:"white",textDim:"gray",link:"cyanBright",prompt:"primary"},effects:{spinner:{color:"primary",style:"dots"}},meta:{description:"Elegant theme with steel blue and golden harmony",version:"1.0.0"}},h={name:"ultra",displayName:"Ultra",colors:{primary:[140,82,255],success:"greenBright",error:"redBright",warning:"yellowBright",info:"cyanBright",step:"magentaBright",text:"whiteBright",textDim:"gray",link:"cyanBright",prompt:"primary"},effects:{spinner:{color:"inherit",style:"socket"},shimmer:{enabled:!0,color:"rainbow",direction:"bi",speed:.5}},meta:{description:"Premium theme with prismatic shimmer for deep analysis",version:"1.0.0"}},u={__proto__:null,socket:n,sunset:a,brick:c,lush:m,ultra:h};0&&(module.exports={BRICK_THEME,LUSH_THEME,SOCKET_THEME,SUNSET_THEME,THEMES,ULTRA_THEME});
+//# sourceMappingURL=themes.js.map

package/dist/themes/themes.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/themes/themes.ts"],
+  "sourcesContent": ["/**\n * @fileoverview Elegant theme definitions for Socket libraries.\n * Sophisticated color palettes crafted for clarity and visual harmony.\n *\n * Philosophy: Every color choice serves a purpose. Bright variants ensure\n * terminal legibility without compromising sophistication. Minimal emoji use,\n * refined symbols with color\u2014elegance in restraint.\n */\n\nimport type { Theme } from './types'\n\n/**\n * Socket Security \u2014 The signature theme.\n * Refined violet with subtle shimmer, designed for focus and elegance.\n */\nexport const SOCKET_THEME: Theme = {\n  name: 'socket',\n  displayName: 'Socket Security',\n  colors: {\n    primary: [140, 82, 255],\n    success: 'greenBright',\n    error: 'redBright',\n    warning: 'yellowBright',\n    info: 'blueBright',\n    step: 'cyanBright',\n    text: 'white',\n    textDim: 'gray',\n    link: 'cyanBright',\n    prompt: 'primary',\n  },\n  effects: {\n    spinner: {\n      color: 'primary',\n      style: 'socket',\n    },\n    shimmer: {\n      enabled: true,\n      color: 'inherit',\n      direction: 'ltr',\n      speed: 0.33,\n    },\n  },\n  meta: {\n    description: 'Signature theme with refined violet and subtle shimmer',\n    version: '1.0.0',\n  },\n}\n\n/**\n * Sunset \u2014 Crisp azure.\n * Clean analytical theme with precise blue tones.\n */\nexport const SUNSET_THEME: Theme = {\n  name: 'sunset',\n  displayName: 'Sunset',\n  colors: {\n    primary: [100, 200, 255],\n    secondary: [50, 150, 200],\n    success: 'greenBright',\n    error: 'redBright',\n    warning: 'yellowBright',\n    info: 'blueBright',\n    step: 'cyanBright',\n    text: 'white',\n    textDim: 'gray',\n    link: 'cyanBright',\n    prompt: 'primary',\n  },\n  effects: {\n    spinner: {\n      color: 'primary',\n      style: 'dots',\n    },\n  },\n  meta: {\n    description: 'Crisp azure theme for precision and clarity',\n    version: '1.0.0',\n  },\n}\n\n/**\n * Brick \u2014 Solid warmth.\n * Rich terracotta and ember tones for grounded confidence.\n */\nexport const BRICK_THEME: Theme = {\n  name: 'brick',\n  displayName: 'Brick',\n  colors: {\n    primary: [255, 100, 50],\n    secondary: [255, 150, 100],\n    success: 'greenBright',\n    error: 'redBright',\n    warning: 'yellowBright',\n    info: 'blueBright',\n    step: 'cyanBright',\n    text: 'white',\n    textDim: 'gray',\n    link: 'secondary',\n    prompt: 'primary',\n  },\n  effects: {\n    spinner: {\n      color: 'primary',\n      style: 'socket',\n    },\n    shimmer: {\n      enabled: true,\n      color: 'inherit',\n      direction: 'ltr',\n      speed: 0.5,\n    },\n  },\n  meta: {\n    description: 'Solid theme with rich terracotta and ember warmth',\n    version: '1.0.0',\n  },\n}\n\n/**\n * Lush \u2014 Steel elegance.\n * Python-inspired steel blue with golden accents.\n */\nexport const LUSH_THEME: Theme = {\n  name: 'lush',\n  displayName: 'Lush',\n  colors: {\n    primary: [70, 130, 180],\n    secondary: [255, 215, 0],\n    success: 'greenBright',\n    error: 'redBright',\n    warning: 'yellowBright',\n    info: 'blueBright',\n    step: 'cyanBright',\n    text: 'white',\n    textDim: 'gray',\n    link: 'cyanBright',\n    prompt: 'primary',\n  },\n  effects: {\n    spinner: {\n      color: 'primary',\n      style: 'dots',\n    },\n  },\n  meta: {\n    description: 'Elegant theme with steel blue and golden harmony',\n    version: '1.0.0',\n  },\n}\n\n/**\n * Ultra \u2014 Premium intensity.\n * Prismatic shimmer for deep analysis, where complexity meets elegance.\n */\nexport const ULTRA_THEME: Theme = {\n  name: 'ultra',\n  displayName: 'Ultra',\n  colors: {\n    primary: [140, 82, 255],\n    success: 'greenBright',\n    error: 'redBright',\n    warning: 'yellowBright',\n    info: 'cyanBright',\n    step: 'magentaBright',\n    text: 'whiteBright',\n    textDim: 'gray',\n    link: 'cyanBright',\n    prompt: 'primary',\n  },\n  effects: {\n    spinner: {\n      color: 'inherit',\n      style: 'socket',\n    },\n    shimmer: {\n      enabled: true,\n      color: 'rainbow',\n      direction: 'bi',\n      speed: 0.5,\n    },\n  },\n  meta: {\n    description: 'Premium theme with prismatic shimmer for deep analysis',\n    version: '1.0.0',\n  },\n}\n\n/**\n * Theme registry \u2014 Curated palette collection.\n */\nexport const THEMES = {\n  __proto__: null,\n  socket: SOCKET_THEME,\n  sunset: SUNSET_THEME,\n  brick: BRICK_THEME,\n  lush: LUSH_THEME,\n  ultra: ULTRA_THEME,\n} as const\n\n/**\n * Available theme identifiers.\n */\nexport type ThemeName = keyof typeof THEMES\n"],
+  "mappings": ";4ZAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,iBAAAE,EAAA,eAAAC,EAAA,iBAAAC,EAAA,iBAAAC,EAAA,WAAAC,EAAA,gBAAAC,IAAA,eAAAC,EAAAR,GAeO,MAAMI,EAAsB,CACjC,KAAM,SACN,YAAa,kBACb,OAAQ,CACN,QAAS,CAAC,IAAK,GAAI,GAAG,EACtB,QAAS,cACT,MAAO,YACP,QAAS,eACT,KAAM,aACN,KAAM,aACN,KAAM,QACN,QAAS,OACT,KAAM,aACN,OAAQ,SACV,EACA,QAAS,CACP,QAAS,CACP,MAAO,UACP,MAAO,QACT,EACA,QAAS,CACP,QAAS,GACT,MAAO,UACP,UAAW,MACX,MAAO,GACT,CACF,EACA,KAAM,CACJ,YAAa,yDACb,QAAS,OACX,CACF,EAMaC,EAAsB,CACjC,KAAM,SACN,YAAa,SACb,OAAQ,CACN,QAAS,CAAC,IAAK,IAAK,GAAG,EACvB,UAAW,CAAC,GAAI,IAAK,GAAG,EACxB,QAAS,cACT,MAAO,YACP,QAAS,eACT,KAAM,aACN,KAAM,aACN,KAAM,QACN,QAAS,OACT,KAAM,aACN,OAAQ,SACV,EACA,QAAS,CACP,QAAS,CACP,MAAO,UACP,MAAO,MACT,CACF,EACA,KAAM,CACJ,YAAa,8CACb,QAAS,OACX,CACF,EAMaH,EAAqB,CAChC,KAAM,QACN,YAAa,QACb,OAAQ,CACN,QAAS,CAAC,IAAK,IAAK,EAAE,EACtB,UAAW,CAAC,IAAK,IAAK,GAAG,EACzB,QAAS,cACT,MAAO,YACP,QAAS,eACT,KAAM,aACN,KAAM,aACN,KAAM,QACN,QAAS,OACT,KAAM,YACN,OAAQ,SACV,EACA,QAAS,CACP,QAAS,CACP,MAAO,UACP,MAAO,QACT,EACA,QAAS,CACP,QAAS,GACT,MAAO,UACP,UAAW,MACX,MAAO,EACT,CACF,EACA,KAAM,CACJ,YAAa,oDACb,QAAS,OACX,CACF,EAMaC,EAAoB,CAC/B,KAAM,OACN,YAAa,OACb,OAAQ,CACN,QAAS,CAAC,GAAI,IAAK,GAAG,EACtB,UAAW,CAAC,IAAK,IAAK,CAAC,EACvB,QAAS,cACT,MAAO,YACP,QAAS,eACT,KAAM,aACN,KAAM,aACN,KAAM,QACN,QAAS,OACT,KAAM,aACN,OAAQ,SACV,EACA,QAAS,CACP,QAAS,CACP,MAAO,UACP,MAAO,MACT,CACF,EACA,KAAM,CACJ,YAAa,mDACb,QAAS,OACX,CACF,EAMaI,EAAqB,CAChC,KAAM,QACN,YAAa,QACb,OAAQ,CACN,QAAS,CAAC,IAAK,GAAI,GAAG,EACtB,QAAS,cACT,MAAO,YACP,QAAS,eACT,KAAM,aACN,KAAM,gBACN,KAAM,cACN,QAAS,OACT,KAAM,aACN,OAAQ,SACV,EACA,QAAS,CACP,QAAS,CACP,MAAO,UACP,MAAO,QACT,EACA,QAAS,CACP,QAAS,GACT,MAAO,UACP,UAAW,KACX,MAAO,EACT,CACF,EACA,KAAM,CACJ,YAAa,yDACb,QAAS,OACX,CACF,EAKaD,EAAS,CACpB,UAAW,KACX,OAAQF,EACR,OAAQC,EACR,MAAOH,EACP,KAAMC,EACN,MAAOI,CACT",
+  "names": ["themes_exports", "__export", "BRICK_THEME", "LUSH_THEME", "SOCKET_THEME", "SUNSET_THEME", "THEMES", "ULTRA_THEME", "__toCommonJS"]
+}

package/dist/themes/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Elegant theme type system.
+ * Type-safe theming for spinners, loggers, prompts, and links.
+ */
+import type { ColorValue, SpinnerStyle } from '../spinner';
+import type { ShimmerDirection } from '../effects/text-shimmer';
+/**
+ * Color reference — direct value or semantic keyword.
+ * Keywords: 'primary', 'secondary', 'inherit', 'rainbow'
+ */
+export type ColorReference = ColorValue | 'primary' | 'secondary' | 'inherit' | 'rainbow';
+/**
+ * Theme color palette — semantic colors for visual harmony.
+ */
+export type ThemeColors = {
+    /** Primary brand identity */
+    primary: ColorValue;
+    /** Secondary accent (optional) */
+    secondary?: ColorValue | undefined;
+    /** Success indicator ✓ */
+    success: ColorValue;
+    /** Error indicator ✗ */
+    error: ColorValue;
+    /** Warning indicator ⚠ */
+    warning: ColorValue;
+    /** Information indicator ℹ */
+    info: ColorValue;
+    /** Progress indicator → */
+    step: ColorValue;
+    /** Primary text */
+    text: ColorValue;
+    /** Dimmed text */
+    textDim: ColorValue;
+    /** Hyperlinks */
+    link: ColorReference;
+    /** Interactive prompts */
+    prompt: ColorReference;
+};
+/**
+ * Theme effects — animations and visual enhancements.
+ */
+export type ThemeEffects = {
+    /** Spinner configuration */
+    spinner?: {
+        /** Color (supports theme references) */
+        color?: ColorReference | undefined;
+        /** Animation style */
+        style?: SpinnerStyle | string | undefined;
+    };
+    /** Shimmer configuration */
+    shimmer?: {
+        /** Enable shimmer */
+        enabled?: boolean | undefined;
+        /** Color (single, gradient, or keyword) */
+        color?: ColorReference | ColorValue[] | undefined;
+        /** Direction */
+        direction?: ShimmerDirection | undefined;
+        /** Speed (steps per frame) */
+        speed?: number | undefined;
+    };
+    /** Pulse configuration */
+    pulse?: {
+        /** Speed (milliseconds) */
+        speed?: number | undefined;
+    };
+};
+/**
+ * Theme metadata — descriptive information.
+ */
+export type ThemeMeta = {
+    /** Description */
+    description?: string | undefined;
+    /** Author */
+    author?: string | undefined;
+    /** Version */
+    version?: string | undefined;
+};
+/**
+ * Theme definition — complete visual identity.
+ */
+export type Theme = {
+    /** Unique identifier (kebab-case) */
+    name: string;
+    /** Display name */
+    displayName: string;
+    /** Color palette */
+    colors: ThemeColors;
+    /** Visual effects (optional) */
+    effects?: ThemeEffects | undefined;
+    /** Metadata (optional) */
+    meta?: ThemeMeta | undefined;
+};

package/dist/themes/types.js

@@ -0,0 +1,3 @@
+/* Socket Lib - Built with esbuild */
+var i=Object.defineProperty;var l=Object.getOwnPropertyDescriptor;var d=Object.getOwnPropertyNames;var s=Object.prototype.hasOwnProperty;var u=(r,e,t,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of d(e))!s.call(r,o)&&o!==t&&i(r,o,{get:()=>e[o],enumerable:!(n=l(e,o))||n.enumerable});return r};var f=r=>u(i({},"__esModule",{value:!0}),r);var m={};module.exports=f(m);
+//# sourceMappingURL=types.js.map

package/dist/themes/types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/themes/types.ts"],
+  "sourcesContent": ["/**\n * @fileoverview Elegant theme type system.\n * Type-safe theming for spinners, loggers, prompts, and links.\n */\n\nimport type { ColorValue, SpinnerStyle } from '../spinner'\nimport type { ShimmerDirection } from '../effects/text-shimmer'\n\n/**\n * Color reference \u2014 direct value or semantic keyword.\n * Keywords: 'primary', 'secondary', 'inherit', 'rainbow'\n */\nexport type ColorReference =\n  | ColorValue\n  | 'primary'\n  | 'secondary'\n  | 'inherit'\n  | 'rainbow'\n\n/**\n * Theme color palette \u2014 semantic colors for visual harmony.\n */\nexport type ThemeColors = {\n  /** Primary brand identity */\n  primary: ColorValue\n  /** Secondary accent (optional) */\n  secondary?: ColorValue | undefined\n\n  /** Success indicator \u2713 */\n  success: ColorValue\n  /** Error indicator \u2717 */\n  error: ColorValue\n  /** Warning indicator \u26A0 */\n  warning: ColorValue\n  /** Information indicator \u2139 */\n  info: ColorValue\n  /** Progress indicator \u2192 */\n  step: ColorValue\n\n  /** Primary text */\n  text: ColorValue\n  /** Dimmed text */\n  textDim: ColorValue\n  /** Hyperlinks */\n  link: ColorReference\n  /** Interactive prompts */\n  prompt: ColorReference\n}\n\n/**\n * Theme effects \u2014 animations and visual enhancements.\n */\nexport type ThemeEffects = {\n  /** Spinner configuration */\n  spinner?: {\n    /** Color (supports theme references) */\n    color?: ColorReference | undefined\n    /** Animation style */\n    style?: SpinnerStyle | string | undefined\n  }\n\n  /** Shimmer configuration */\n  shimmer?: {\n    /** Enable shimmer */\n    enabled?: boolean | undefined\n    /** Color (single, gradient, or keyword) */\n    color?: ColorReference | ColorValue[] | undefined\n    /** Direction */\n    direction?: ShimmerDirection | undefined\n    /** Speed (steps per frame) */\n    speed?: number | undefined\n  }\n\n  /** Pulse configuration */\n  pulse?: {\n    /** Speed (milliseconds) */\n    speed?: number | undefined\n  }\n}\n\n/**\n * Theme metadata \u2014 descriptive information.\n */\nexport type ThemeMeta = {\n  /** Description */\n  description?: string | undefined\n  /** Author */\n  author?: string | undefined\n  /** Version */\n  version?: string | undefined\n}\n\n/**\n * Theme definition \u2014 complete visual identity.\n */\nexport type Theme = {\n  /** Unique identifier (kebab-case) */\n  name: string\n  /** Display name */\n  displayName: string\n\n  /** Color palette */\n  colors: ThemeColors\n\n  /** Visual effects (optional) */\n  effects?: ThemeEffects | undefined\n\n  /** Metadata (optional) */\n  meta?: ThemeMeta | undefined\n}\n"],
+  "mappings": ";kWAAA,IAAAA,EAAA,kBAAAC,EAAAD",
+  "names": ["types_exports", "__toCommonJS"]
+}

package/dist/themes/utils.d.ts

@@ -0,0 +1,78 @@
+import type { ColorValue } from '../spinner';
+import type { ShimmerColorGradient } from '../effects/text-shimmer';
+import type { Theme, ThemeColors, ColorReference } from './types';
+/**
+ * Resolve color reference to concrete value.
+ * Handles semantic keywords: 'primary', 'secondary', 'rainbow', 'inherit'
+ *
+ * @param value - Color reference
+ * @param colors - Theme palette
+ * @returns Resolved color
+ *
+ * @example
+ * ```ts
+ * resolveColor('primary', theme.colors)
+ * resolveColor([255, 0, 0], theme.colors)
+ * ```
+ */
+export declare function resolveColor(value: ColorReference | ColorValue, colors: ThemeColors): ColorValue | 'inherit' | ShimmerColorGradient;
+/**
+ * Resolve shimmer color with gradient support.
+ *
+ * @param value - Shimmer color
+ * @param theme - Theme context
+ * @returns Resolved color
+ *
+ * @example
+ * ```ts
+ * resolveShimmerColor('rainbow', theme)
+ * resolveShimmerColor('primary', theme)
+ * ```
+ */
+export declare function resolveShimmerColor(value: ColorReference | ColorValue[] | undefined, theme: Theme): ColorValue | ShimmerColorGradient | 'inherit';
+/**
+ * Extend existing theme with custom overrides.
+ * Deep merge of colors and effects.
+ *
+ * @param base - Base theme
+ * @param overrides - Custom overrides
+ * @returns Extended theme
+ *
+ * @example
+ * ```ts
+ * const custom = extendTheme(SOCKET_THEME, {
+ *   name: 'custom',
+ *   colors: { primary: [255, 100, 200] }
+ * })
+ * ```
+ */
+export declare function extendTheme(base: Theme, overrides: Partial<Omit<Theme, 'colors'>> & {
+    colors?: Partial<ThemeColors> | undefined;
+}): Theme;
+/**
+ * Create new theme from complete specification.
+ *
+ * @param config - Theme configuration
+ * @returns Theme object
+ *
+ * @example
+ * ```ts
+ * const theme = createTheme({
+ *   name: 'custom',
+ *   displayName: 'Custom',
+ *   colors: {
+ *     primary: [255, 100, 200],
+ *     success: 'greenBright',
+ *     error: 'redBright',
+ *     warning: 'yellowBright',
+ *     info: 'blueBright',
+ *     step: 'cyanBright',
+ *     text: 'white',
+ *     textDim: 'gray',
+ *     link: 'cyanBright',
+ *     prompt: 'primary'
+ *   }
+ * })
+ * ```
+ */
+export declare function createTheme(config: Pick<Theme, 'name' | 'displayName' | 'colors'> & Partial<Omit<Theme, 'name' | 'displayName' | 'colors'>>): Theme;

package/dist/themes/utils.js

@@ -0,0 +1,3 @@
+/* Socket Lib - Built with esbuild */
+var n=Object.defineProperty;var i=Object.getOwnPropertyDescriptor;var s=Object.getOwnPropertyNames;var _=Object.prototype.hasOwnProperty;var p=(e,r)=>{for(var o in r)n(e,o,{get:r[o],enumerable:!0})},h=(e,r,o,f)=>{if(r&&typeof r=="object"||typeof r=="function")for(let t of s(r))!_.call(e,t)&&t!==o&&n(e,t,{get:()=>r[t],enumerable:!(f=i(r,t))||f.enumerable});return e};var u=e=>h(n({},"__esModule",{value:!0}),e);var y={};p(y,{createTheme:()=>C,extendTheme:()=>c,resolveColor:()=>l,resolveShimmerColor:()=>a});module.exports=u(y);var m=require("../effects/ultra");function l(e,r){return typeof e=="string"?e==="primary"?r.primary:e==="secondary"?r.secondary??r.primary:e==="inherit"?"inherit":e==="rainbow"?m.RAINBOW_GRADIENT:e:e}function a(e,r){return e?e==="rainbow"?m.RAINBOW_GRADIENT:e==="inherit"?"inherit":Array.isArray(e)?(e.length>0&&Array.isArray(e[0]),e):l(e,r.colors):"inherit"}function c(e,r){return{__proto__:null,...e,...r,colors:{__proto__:null,...e.colors,...r.colors},effects:r.effects?{__proto__:null,...e.effects,...r.effects,spinner:r.effects.spinner!==void 0?{__proto__:null,...e.effects?.spinner,...r.effects.spinner}:e.effects?.spinner,shimmer:r.effects.shimmer!==void 0?{__proto__:null,...e.effects?.shimmer,...r.effects.shimmer}:e.effects?.shimmer,pulse:r.effects.pulse!==void 0?{__proto__:null,...e.effects?.pulse,...r.effects.pulse}:e.effects?.pulse}:e.effects,meta:r.meta?{__proto__:null,...e.meta,...r.meta}:e.meta}}function C(e){return{__proto__:null,name:e.name,displayName:e.displayName,colors:{__proto__:null,...e.colors},effects:e.effects?{__proto__:null,...e.effects}:void 0,meta:e.meta?{__proto__:null,...e.meta}:void 0}}0&&(module.exports={createTheme,extendTheme,resolveColor,resolveShimmerColor});
+//# sourceMappingURL=utils.js.map

package/dist/themes/utils.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/themes/utils.ts"],
+  "sourcesContent": ["/**\n * @fileoverview Theme utilities \u2014 color resolution and composition.\n */\n\nimport { RAINBOW_GRADIENT } from '../effects/ultra'\nimport type { ColorValue } from '../spinner'\nimport type { ShimmerColorGradient } from '../effects/text-shimmer'\nimport type { Theme, ThemeColors, ColorReference } from './types'\n\n/**\n * Resolve color reference to concrete value.\n * Handles semantic keywords: 'primary', 'secondary', 'rainbow', 'inherit'\n *\n * @param value - Color reference\n * @param colors - Theme palette\n * @returns Resolved color\n *\n * @example\n * ```ts\n * resolveColor('primary', theme.colors)\n * resolveColor([255, 0, 0], theme.colors)\n * ```\n */\nexport function resolveColor(\n  value: ColorReference | ColorValue,\n  colors: ThemeColors,\n): ColorValue | 'inherit' | ShimmerColorGradient {\n  if (typeof value === 'string') {\n    if (value === 'primary') {\n      return colors.primary\n    }\n    if (value === 'secondary') {\n      return colors.secondary ?? colors.primary\n    }\n    if (value === 'inherit') {\n      return 'inherit'\n    }\n    if (value === 'rainbow') {\n      return RAINBOW_GRADIENT\n    }\n    return value as ColorValue\n  }\n  return value as ColorValue\n}\n\n/**\n * Resolve shimmer color with gradient support.\n *\n * @param value - Shimmer color\n * @param theme - Theme context\n * @returns Resolved color\n *\n * @example\n * ```ts\n * resolveShimmerColor('rainbow', theme)\n * resolveShimmerColor('primary', theme)\n * ```\n */\nexport function resolveShimmerColor(\n  value: ColorReference | ColorValue[] | undefined,\n  theme: Theme,\n): ColorValue | ShimmerColorGradient | 'inherit' {\n  if (!value) {\n    return 'inherit'\n  }\n  if (value === 'rainbow') {\n    return RAINBOW_GRADIENT\n  }\n  if (value === 'inherit') {\n    return 'inherit'\n  }\n  if (Array.isArray(value)) {\n    if (value.length > 0 && Array.isArray(value[0])) {\n      // Gradient\n      return value as ShimmerColorGradient\n    }\n    // Single RGB\n    return value as unknown as ColorValue\n  }\n  return resolveColor(value as ColorReference, theme.colors)\n}\n\n/**\n * Extend existing theme with custom overrides.\n * Deep merge of colors and effects.\n *\n * @param base - Base theme\n * @param overrides - Custom overrides\n * @returns Extended theme\n *\n * @example\n * ```ts\n * const custom = extendTheme(SOCKET_THEME, {\n *   name: 'custom',\n *   colors: { primary: [255, 100, 200] }\n * })\n * ```\n */\nexport function extendTheme(\n  base: Theme,\n  overrides: Partial<Omit<Theme, 'colors'>> & {\n    colors?: Partial<ThemeColors> | undefined\n  },\n): Theme {\n  return {\n    __proto__: null,\n    ...base,\n    ...overrides,\n    colors: {\n      __proto__: null,\n      ...base.colors,\n      ...overrides.colors,\n    } as ThemeColors,\n    effects: overrides.effects\n      ? {\n          __proto__: null,\n          ...base.effects,\n          ...overrides.effects,\n          spinner:\n            overrides.effects.spinner !== undefined\n              ? {\n                  __proto__: null,\n                  ...base.effects?.spinner,\n                  ...overrides.effects.spinner,\n                }\n              : base.effects?.spinner,\n          shimmer:\n            overrides.effects.shimmer !== undefined\n              ? {\n                  __proto__: null,\n                  ...base.effects?.shimmer,\n                  ...overrides.effects.shimmer,\n                }\n              : base.effects?.shimmer,\n          pulse:\n            overrides.effects.pulse !== undefined\n              ? {\n                  __proto__: null,\n                  ...base.effects?.pulse,\n                  ...overrides.effects.pulse,\n                }\n              : base.effects?.pulse,\n        }\n      : base.effects,\n    meta: overrides.meta\n      ? {\n          __proto__: null,\n          ...base.meta,\n          ...overrides.meta,\n        }\n      : base.meta,\n  } as Theme\n}\n\n/**\n * Create new theme from complete specification.\n *\n * @param config - Theme configuration\n * @returns Theme object\n *\n * @example\n * ```ts\n * const theme = createTheme({\n *   name: 'custom',\n *   displayName: 'Custom',\n *   colors: {\n *     primary: [255, 100, 200],\n *     success: 'greenBright',\n *     error: 'redBright',\n *     warning: 'yellowBright',\n *     info: 'blueBright',\n *     step: 'cyanBright',\n *     text: 'white',\n *     textDim: 'gray',\n *     link: 'cyanBright',\n *     prompt: 'primary'\n *   }\n * })\n * ```\n */\nexport function createTheme(\n  config: Pick<Theme, 'name' | 'displayName' | 'colors'> &\n    Partial<Omit<Theme, 'name' | 'displayName' | 'colors'>>,\n): Theme {\n  return {\n    __proto__: null,\n    name: config.name,\n    displayName: config.displayName,\n    colors: { __proto__: null, ...config.colors } as ThemeColors,\n    effects: config.effects\n      ? { __proto__: null, ...config.effects }\n      : undefined,\n    meta: config.meta ? { __proto__: null, ...config.meta } : undefined,\n  } as Theme\n}\n"],
+  "mappings": ";4ZAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,iBAAAE,EAAA,gBAAAC,EAAA,iBAAAC,EAAA,wBAAAC,IAAA,eAAAC,EAAAN,GAIA,IAAAO,EAAiC,4BAmB1B,SAASH,EACdI,EACAC,EAC+C,CAC/C,OAAI,OAAOD,GAAU,SACfA,IAAU,UACLC,EAAO,QAEZD,IAAU,YACLC,EAAO,WAAaA,EAAO,QAEhCD,IAAU,UACL,UAELA,IAAU,UACL,mBAEFA,EAEFA,CACT,CAeO,SAASH,EACdG,EACAE,EAC+C,CAC/C,OAAKF,EAGDA,IAAU,UACL,mBAELA,IAAU,UACL,UAEL,MAAM,QAAQA,CAAK,GACjBA,EAAM,OAAS,GAAK,MAAM,QAAQA,EAAM,CAAC,CAAC,EAErCA,GAKJJ,EAAaI,EAAyBE,EAAM,MAAM,EAhBhD,SAiBX,CAkBO,SAASP,EACdQ,EACAC,EAGO,CACP,MAAO,CACL,UAAW,KACX,GAAGD,EACH,GAAGC,EACH,OAAQ,CACN,UAAW,KACX,GAAGD,EAAK,OACR,GAAGC,EAAU,MACf,EACA,QAASA,EAAU,QACf,CACE,UAAW,KACX,GAAGD,EAAK,QACR,GAAGC,EAAU,QACb,QACEA,EAAU,QAAQ,UAAY,OAC1B,CACE,UAAW,KACX,GAAGD,EAAK,SAAS,QACjB,GAAGC,EAAU,QAAQ,OACvB,EACAD,EAAK,SAAS,QACpB,QACEC,EAAU,QAAQ,UAAY,OAC1B,CACE,UAAW,KACX,GAAGD,EAAK,SAAS,QACjB,GAAGC,EAAU,QAAQ,OACvB,EACAD,EAAK,SAAS,QACpB,MACEC,EAAU,QAAQ,QAAU,OACxB,CACE,UAAW,KACX,GAAGD,EAAK,SAAS,MACjB,GAAGC,EAAU,QAAQ,KACvB,EACAD,EAAK,SAAS,KACtB,EACAA,EAAK,QACT,KAAMC,EAAU,KACZ,CACE,UAAW,KACX,GAAGD,EAAK,KACR,GAAGC,EAAU,IACf,EACAD,EAAK,IACX,CACF,CA4BO,SAAST,EACdW,EAEO,CACP,MAAO,CACL,UAAW,KACX,KAAMA,EAAO,KACb,YAAaA,EAAO,YACpB,OAAQ,CAAE,UAAW,KAAM,GAAGA,EAAO,MAAO,EAC5C,QAASA,EAAO,QACZ,CAAE,UAAW,KAAM,GAAGA,EAAO,OAAQ,EACrC,OACJ,KAAMA,EAAO,KAAO,CAAE,UAAW,KAAM,GAAGA,EAAO,IAAK,EAAI,MAC5D,CACF",
+  "names": ["utils_exports", "__export", "createTheme", "extendTheme", "resolveColor", "resolveShimmerColor", "__toCommonJS", "import_ultra", "value", "colors", "theme", "base", "overrides", "config"]
+}