numux 2.16.2 → 2.17.0

package/README.md

@@ -228,6 +228,7 @@ export default defineConfig({
 | `--no-watch` | Disable file watching even if config has watch patterns |
 | `-t,` `--timestamps` `[<format>]` | Add timestamps to output (default HH:mm:ss.SSS, or pass a format string) |
 | `--log-dir` `<path>` | Write per-process logs to directory |
+| `--theme` `<light|dark|auto>` | TUI theme (auto detects terminal background) |
 | `--debug` | Enable debug logging to .numux/debug.log |
 | `-h,` `--help` | Show this help |
 | `-v,` `--version` | Show version |
@@ -284,6 +285,7 @@ Top-level options apply to all processes (process-level settings override):
 | `killOthersOnFail` | `boolean` | Kill all processes when any one exits with a non-zero exit code |
 | `noWatch` | `boolean` | Disable file watching even if processes have watch patterns |
 | `logDir` | `string` | Directory to write per-process log files |
+| `theme` | `ThemePref` | TUI color theme. `'auto'` detects the terminal background via OSC 11 (falling back to `COLORFGBG` then dark). `'light'`/`'dark'` skip detection. |
 <!-- /generated:config-global -->
 
 ```ts

package/dist/man/numux.1

@@ -1,4 +1,4 @@
-.TH "NUMUX" "1" "May 2026" "2.16.2" "numux manual"
+.TH "NUMUX" "1" "May 2026" "2.17.0" "numux manual"
 .SH "NAME"
 \fBnumux\fR
 .P
@@ -349,6 +349,12 @@ Write per\-process logs to directory
 T}
 _
 T{
+\fB\-\-theme\fP `<light
+T}|T{
+dark
+T}
+_
+T{
 \fB\-\-debug\fP
 T}|T{
 Enable debug logging to \.numux/debug\.log
@@ -538,6 +544,14 @@ T}|T{
 T}|T{
 Directory to write per\-process log files
 T}
+_
+T{
+\fBtheme\fP
+T}|T{
+\fBThemePref\fP
+T}|T{
+TUI color theme\. \fB&#39;auto&#39;\fP detects the terminal background via OSC 11 (falling back to \fBCOLORFGBG\fP then dark)\. \fB&#39;light&#39;\fP/\fB&#39;dark&#39;\fP skip detection\.
+T}
 .TE
 <!\-\- /generated:config\-global \-\->
 

package/dist/numux.js

@@ -246,6 +246,7 @@ export default defineConfig({
 | \`--no-watch\` | Disable file watching even if config has watch patterns |
 | \`-t,\` \`--timestamps\` \`[<format>]\` | Add timestamps to output (default HH:mm:ss.SSS, or pass a format string) |
 | \`--log-dir\` \`<path>\` | Write per-process logs to directory |
+| \`--theme\` \`<light|dark|auto>\` | TUI theme (auto detects terminal background) |
 | \`--debug\` | Enable debug logging to .numux/debug.log |
 | \`-h,\` \`--help\` | Show this help |
 | \`-v,\` \`--version\` | Show version |
@@ -290,6 +291,7 @@ numux logs api | tail -f           # Follow process log output
 | \`killOthersOnFail\` | \`boolean\` | Kill all processes when any one exits with a non-zero exit code |
 | \`noWatch\` | \`boolean\` | Disable file watching even if processes have watch patterns |
 | \`logDir\` | \`string\` | Directory to write per-process log files |
+| \`theme\` | \`ThemePref\` | TUI color theme. \`'auto'\` detects the terminal background via OSC 11 (falling back to \`COLORFGBG\` then dark). \`'light'\`/\`'dark'\` skip detection. |
 <!-- /generated:config-global -->
 
 \`\`\`ts
@@ -548,7 +550,7 @@ var init_help = __esm(() => {
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "numux",
-    version: "2.16.2",
+    version: "2.17.0",
     description: "Terminal multiplexer with dependency orchestration",
     type: "module",
     license: "MIT",
@@ -876,6 +878,20 @@ var FLAGS = [
     valueName: "<path>",
     completionHint: "directory"
   },
+  {
+    type: "value",
+    long: "--theme",
+    key: "theme",
+    description: "TUI theme (auto detects terminal background)",
+    valueName: "<light|dark|auto>",
+    completionHint: "none",
+    parse(raw, flag) {
+      if (raw !== "light" && raw !== "dark" && raw !== "auto") {
+        throw new Error(`${flag} must be light, dark, or auto. Got "${raw}"`);
+      }
+      return raw;
+    }
+  },
   {
     type: "boolean",
     long: "--debug",
@@ -1704,10 +1720,11 @@ function resolveColor(color) {
     return color[0];
   return;
 }
-function buildProcessColorMap(names, config) {
+function buildProcessColorMap(names, config, palette = DEFAULT_PALETTE) {
   const map = new Map;
   if ("NO_COLOR" in process.env)
     return map;
+  const ansiPalette = palette === DEFAULT_PALETTE ? DEFAULT_ANSI_COLORS : palette.map(hexToAnsi);
   let paletteIndex = 0;
   for (const name of names) {
     const explicit = resolveColor(config.processes[name]?.color);
@@ -1716,15 +1733,15 @@ function buildProcessColorMap(names, config) {
       if (hex)
         map.set(name, hexToAnsi(hex));
       else
-        map.set(name, DEFAULT_ANSI_COLORS[paletteIndex++ % DEFAULT_ANSI_COLORS.length]);
+        map.set(name, ansiPalette[paletteIndex++ % ansiPalette.length]);
     } else {
-      map.set(name, DEFAULT_ANSI_COLORS[paletteIndex % DEFAULT_ANSI_COLORS.length]);
+      map.set(name, ansiPalette[paletteIndex % ansiPalette.length]);
       paletteIndex++;
     }
   }
   return map;
 }
-function buildProcessHexColorMap(names, config) {
+function buildProcessHexColorMap(names, config, palette = DEFAULT_PALETTE) {
   const map = new Map;
   if ("NO_COLOR" in process.env)
     return map;
@@ -1736,9 +1753,9 @@ function buildProcessHexColorMap(names, config) {
       if (hex)
         map.set(name, hex);
       else
-        map.set(name, DEFAULT_PALETTE[paletteIndex++ % DEFAULT_PALETTE.length]);
+        map.set(name, palette[paletteIndex++ % palette.length]);
     } else {
-      map.set(name, DEFAULT_PALETTE[paletteIndex % DEFAULT_PALETTE.length]);
+      map.set(name, palette[paletteIndex % palette.length]);
       paletteIndex++;
     }
   }
@@ -1783,6 +1800,7 @@ function validateConfig(raw, _warnings) {
   const killOthersOnFail = config.killOthersOnFail === true ? true : undefined;
   const noWatch = config.noWatch === true ? true : undefined;
   const logDir = typeof config.logDir === "string" && config.logDir.trim() ? config.logDir.trim() : undefined;
+  const theme = validateTheme(config.theme);
   const validated = {};
   for (const name of names) {
     let proc = processes[name];
@@ -1881,9 +1899,19 @@ function validateConfig(raw, _warnings) {
     ...killOthersOnFail ? { killOthersOnFail } : {},
     ...noWatch ? { noWatch } : {},
     ...logDir ? { logDir } : {},
+    ...theme ? { theme } : {},
     processes: validated
   };
 }
+var VALID_THEME_VALUES = new Set(["light", "dark", "auto"]);
+function validateTheme(value) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string" || !VALID_THEME_VALUES.has(value)) {
+    throw new Error(`theme must be one of: light, dark, auto. Got "${String(value)}"`);
+  }
+  return value;
+}
 function validateStringOrStringArray(value) {
   if (typeof value === "string")
     return value;
@@ -2949,6 +2977,178 @@ function setupShutdownHandlers(app, logWriter) {
   });
 }
 
+// src/utils/theme.ts
+var DARK_THEME = {
+  mode: "dark",
+  statusBarBg: "#1a1a1a",
+  statusBarText: "#cccccc",
+  helpBackdropBg: "#000000",
+  helpBoxBg: "#1a1a2e",
+  helpBorder: "#444444",
+  helpText: "#cccccc",
+  sidebarBg: "#1a1a1a",
+  sidebarBorder: "#444444",
+  tabSelectedBg: "#334455",
+  tabSelectedText: "#ffffff",
+  tabText: "#888888",
+  tabDescriptionText: "#888888",
+  tabSelectedDescriptionText: "#cccccc",
+  scrollTrackBg: "#252527",
+  scrollThumbBg: "#9a9ea3",
+  searchCurrentBg: "#b58900",
+  searchMatchBg: "#073642",
+  palette: ["#00cccc", "#cccc00", "#cc00cc", "#5577ff", "#00cc00", "#ff5555", "#ffa500", "#cc88ff"],
+  status: {
+    ready: "#00cc00",
+    failed: "#ff5555",
+    stopped: "#888888",
+    finished: "#66aa66",
+    skipped: "#888888"
+  },
+  inputWaiting: "#ffaa00",
+  errorIndicator: "#ff5555",
+  searchMatchTab: "#b58900",
+  iconDefault: "#888888"
+};
+var LIGHT_THEME = {
+  mode: "light",
+  statusBarBg: "#e8e8e8",
+  statusBarText: "#000000",
+  helpBackdropBg: "#ffffff",
+  helpBoxBg: "#f5f5f5",
+  helpBorder: "#aaaaaa",
+  helpText: "#1a1a1a",
+  sidebarBg: "#f0f0f0",
+  sidebarBorder: "#aaaaaa",
+  tabSelectedBg: "#7a9bbf",
+  tabSelectedText: "#ffffff",
+  tabText: "#444444",
+  tabDescriptionText: "#666666",
+  tabSelectedDescriptionText: "#e8e8e8",
+  scrollTrackBg: "#d0d0d0",
+  scrollThumbBg: "#888888",
+  searchCurrentBg: "#ffaa33",
+  searchMatchBg: "#d0e4b8",
+  palette: ["#008888", "#886600", "#880088", "#0033aa", "#006600", "#aa0000", "#cc5500", "#6622aa"],
+  status: {
+    ready: "#006600",
+    failed: "#aa0000",
+    stopped: "#666666",
+    finished: "#2a7a2a",
+    skipped: "#666666"
+  },
+  inputWaiting: "#cc7a00",
+  errorIndicator: "#aa0000",
+  searchMatchTab: "#cc7a00",
+  iconDefault: "#666666"
+};
+function themeFor(mode) {
+  return mode === "light" ? LIGHT_THEME : DARK_THEME;
+}
+function relativeLuminance(r, g, b) {
+  const norm = (c) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * norm(r) + 0.7152 * norm(g) + 0.0722 * norm(b);
+}
+function isLightRgb(r, g, b) {
+  return relativeLuminance(r, g, b) > 0.5;
+}
+function parseOSC11Response(data) {
+  const match = data.match(/rgb:([0-9a-f]+)\/([0-9a-f]+)\/([0-9a-f]+)/i);
+  if (!match)
+    return null;
+  const scale = (hex) => {
+    if (hex.length === 0 || hex.length > 4)
+      return Number.NaN;
+    const val = Number.parseInt(hex, 16);
+    if (Number.isNaN(val))
+      return Number.NaN;
+    const max = 16 ** hex.length - 1;
+    return Math.round(val / max * 255);
+  };
+  const r = scale(match[1]);
+  const g = scale(match[2]);
+  const b = scale(match[3]);
+  if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b))
+    return null;
+  return { r, g, b };
+}
+function parseColorFgBg(value) {
+  if (!value)
+    return null;
+  const parts = value.split(";");
+  if (parts.length < 2)
+    return null;
+  const bgRaw = parts[parts.length - 1].trim();
+  const bg = Number.parseInt(bgRaw, 10);
+  if (Number.isNaN(bg))
+    return null;
+  return bg >= 7 && bg <= 15 ? "light" : "dark";
+}
+function queryOSC11(timeoutMs = 100) {
+  const stdin = process.stdin;
+  const stdout = process.stdout;
+  if (!(stdin.isTTY && stdout.isTTY))
+    return Promise.resolve(null);
+  return new Promise((resolve8) => {
+    let settled = false;
+    let buf = "";
+    let timer = null;
+    const wasRaw = stdin.isRaw;
+    const finish = (result) => {
+      if (settled)
+        return;
+      settled = true;
+      if (timer)
+        clearTimeout(timer);
+      stdin.off("data", onData);
+      try {
+        if (!wasRaw)
+          stdin.setRawMode(false);
+      } catch {}
+      stdin.pause();
+      resolve8(result);
+    };
+    const onData = (chunk) => {
+      buf += chunk.toString("utf8");
+      const match = buf.match(/\x1b\]1[01];rgb:[0-9a-f/]+(?:\x07|\x1b\\)/i);
+      if (!match)
+        return;
+      const parsed = parseOSC11Response(match[0]);
+      if (!parsed) {
+        finish(null);
+        return;
+      }
+      finish(isLightRgb(parsed.r, parsed.g, parsed.b) ? "light" : "dark");
+    };
+    try {
+      stdin.setRawMode(true);
+      stdin.resume();
+      stdin.on("data", onData);
+      timer = setTimeout(() => finish(null), timeoutMs);
+      stdout.write("\x1B]11;?\x1B\\");
+    } catch {
+      finish(null);
+    }
+  });
+}
+async function detectThemeMode(timeoutMs = 100) {
+  const osc = await queryOSC11(timeoutMs);
+  if (osc)
+    return osc;
+  return parseColorFgBg(process.env.COLORFGBG);
+}
+async function resolveTheme(pref = "auto") {
+  if (pref === "light")
+    return LIGHT_THEME;
+  if (pref === "dark")
+    return DARK_THEME;
+  const detected = await detectThemeMode();
+  return themeFor(detected ?? "dark");
+}
+
 // src/ui/help-overlay.ts
 import { BoxRenderable, TextRenderable } from "@opentui/core";
 
@@ -3002,7 +3202,7 @@ var STATUS_BAR_TEXT = STATUS_HINTS_COMPACT.map((h) => {
 class HelpOverlay {
   renderable;
   textRenderable;
-  constructor(renderer) {
+  constructor(renderer, theme = DARK_THEME) {
     this.renderable = new BoxRenderable(renderer, {
       id: "help-overlay",
       position: "absolute",
@@ -3018,7 +3218,7 @@ class HelpOverlay {
       position: "absolute",
       width: "100%",
       height: "100%",
-      backgroundColor: "#000000",
+      backgroundColor: theme.helpBackdropBg,
       opacity: 0.7
     });
     const box = new BoxRenderable(renderer, {
@@ -3026,9 +3226,9 @@ class HelpOverlay {
       flexDirection: "column",
       padding: 1,
       paddingX: 5,
-      backgroundColor: "#1a1a2e",
+      backgroundColor: theme.helpBoxBg,
       border: true,
-      borderColor: "#444",
+      borderColor: theme.helpBorder,
       zIndex: 101
     });
     const lines = [
@@ -3045,7 +3245,7 @@ class HelpOverlay {
       id: "help-text",
       content: lines.join(`
 `),
-      fg: "#cccccc"
+      fg: theme.helpText
     });
     box.add(this.textRenderable);
     this.renderable.add(backdrop);
@@ -3576,8 +3776,10 @@ class Pane {
   _onScroll = null;
   _onCopy = null;
   _onLinkClick = null;
-  constructor(renderer, name, cols, rows, interactive = false) {
+  theme;
+  constructor(renderer, name, cols, rows, interactive = false, theme = DARK_THEME) {
     this.renderer = renderer;
+    this.theme = theme;
     this.scrollBox = new ScrollBoxRenderable(renderer, {
       id: `pane-${name}`,
       flexGrow: 1,
@@ -3585,7 +3787,13 @@ class Pane {
       stickyScroll: true,
       stickyStart: "bottom",
       visible: false,
-      onMouseScroll: () => this._onScroll?.()
+      onMouseScroll: () => this._onScroll?.(),
+      scrollbarOptions: {
+        trackOptions: {
+          backgroundColor: theme.scrollTrackBg,
+          foregroundColor: theme.scrollThumbBg
+        }
+      }
     });
     this.terminal = new TailingTerminal(renderer, {
       id: `term-${name}`,
@@ -3721,7 +3929,7 @@ class Pane {
         line: m.line,
         start: m.start,
         end: m.end,
-        backgroundColor: i === currentIndex ? "#b58900" : "#073642"
+        backgroundColor: i === currentIndex ? this.theme.searchCurrentBg : this.theme.searchMatchBg
       });
     }
     this.terminal.highlights = regions;
@@ -4026,11 +4234,11 @@ class StatusBar {
   _tempMessage = null;
   _tempTimer = null;
   _inputMode = false;
-  constructor(renderer) {
+  constructor(renderer, theme = DARK_THEME) {
     this.renderable = new BoxRenderable2(renderer, {
       id: "status-bar",
       width: "100%",
-      backgroundColor: "#1a1a1a",
+      backgroundColor: theme.statusBarBg,
       paddingX: 1,
       minHeight: 1
     });
@@ -4038,6 +4246,7 @@ class StatusBar {
       id: "status-bar-text",
       width: "100%",
       wrapMode: "word",
+      fg: theme.statusBarText,
       content: this.buildContent()
     });
     this.text.selectable = false;
@@ -4123,13 +4332,15 @@ var STATUS_ICONS = {
   failed: "\u2716",
   skipped: "\u2298"
 };
-var STATUS_ICON_HEX = {
-  ready: "#00cc00",
-  finished: "#66aa66",
-  failed: "#ff5555",
-  stopped: "#888888",
-  skipped: "#888888"
-};
+function getStatusIconHex(theme) {
+  return {
+    ready: theme.status.ready,
+    finished: theme.status.finished,
+    failed: theme.status.failed,
+    stopped: theme.status.stopped,
+    skipped: theme.status.skipped
+  };
+}
 var TERMINAL_STATUSES = new Set(["finished", "stopped", "failed", "skipped"]);
 function getDisplayOrder(originalNames, statuses) {
   const active = originalNames.filter((n) => !TERMINAL_STATUSES.has(statuses.get(n)));
@@ -4149,16 +4360,17 @@ function formatDescription(status, exitCode, restartCount) {
   }
   return desc;
 }
-function resolveOptionColors(names, statuses, processColors, inputWaiting, erroredProcesses, searchMatchProcesses) {
+function resolveOptionColors(names, statuses, processColors, inputWaiting, erroredProcesses, theme, searchMatchProcesses) {
+  const statusIconHex = getStatusIconHex(theme);
   return names.map((name) => {
     const status = statuses.get(name);
     const waiting = inputWaiting.has(name);
     const errored = erroredProcesses.has(name);
     const hasSearchMatch = searchMatchProcesses?.has(name);
-    const statusHex = hasSearchMatch ? "#b58900" : waiting ? "#ffaa00" : errored ? "#ff5555" : STATUS_ICON_HEX[status];
+    const statusHex = hasSearchMatch ? theme.searchMatchTab : waiting ? theme.inputWaiting : errored ? theme.errorIndicator : statusIconHex[status];
     const processHex = processColors.get(name);
     return {
-      iconHex: statusHex ?? processHex ?? "#888888",
+      iconHex: statusHex ?? processHex ?? theme.iconDefault,
       nameHex: processHex ?? null
     };
   });
@@ -4242,13 +4454,15 @@ class TabBar {
   inputWaiting = new Set;
   erroredProcesses = new Set;
   searchMatchCounts = new Map;
-  constructor(renderer, names, colors, reorderByStatus = false) {
+  theme;
+  constructor(renderer, names, colors, theme = DARK_THEME, reorderByStatus = false) {
     this.originalNames = names;
     this.names = [...names];
     this.reorderByStatus = reorderByStatus;
     this.statuses = new Map(names.map((n) => [n, "pending"]));
     this.baseDescriptions = new Map(names.map((n) => [n, "pending"]));
     this.processColors = colors ?? new Map;
+    this.theme = theme;
     this.renderable = new ColoredSelectRenderable(renderer, {
       id: "tab-bar",
       width: "100%",
@@ -4257,9 +4471,13 @@ class TabBar {
         name: formatTab(n, "pending"),
         description: "pending"
       })),
-      selectedBackgroundColor: "#334455",
-      selectedTextColor: "#fff",
-      textColor: "#888",
+      backgroundColor: theme.sidebarBg,
+      focusedBackgroundColor: theme.sidebarBg,
+      selectedBackgroundColor: theme.tabSelectedBg,
+      selectedTextColor: theme.tabSelectedText,
+      textColor: theme.tabText,
+      descriptionColor: theme.tabDescriptionText,
+      selectedDescriptionColor: theme.tabSelectedDescriptionText,
       showDescription: true,
       wrapSelection: true
     });
@@ -4343,7 +4561,7 @@ class TabBar {
   }
   updateOptionColors() {
     const searchProcesses = this.searchMatchCounts.size > 0 ? new Set(this.searchMatchCounts.keys()) : undefined;
-    const resolved = resolveOptionColors(this.names, this.statuses, this.processColors, this.inputWaiting, this.erroredProcesses, searchProcesses);
+    const resolved = resolveOptionColors(this.names, this.statuses, this.processColors, this.inputWaiting, this.erroredProcesses, this.theme, searchProcesses);
     const colors = resolved.map((c) => ({
       icon: parseColor(c.iconHex),
       name: c.nameHex ? parseColor(c.nameHex) : null
@@ -4376,6 +4594,7 @@ class App {
   sidebarWidth = 20;
   config;
   logWriter;
+  theme = DARK_THEME;
   resizeTimer = null;
   inputWaitTimers = new Map;
   awaitingInput = new Set;
@@ -4386,6 +4605,9 @@ class App {
     this.names = manager.getProcessNames();
   }
   async start() {
+    log(`theme detect: pref=${this.config.theme ?? "auto"} stdin.isTTY=${process.stdin.isTTY} stdout.isTTY=${process.stdout.isTTY} COLORFGBG=${process.env.COLORFGBG ?? "(unset)"}`);
+    this.theme = await resolveTheme(this.config.theme);
+    log(`theme resolved: ${this.theme.mode}`);
     this.renderer = await createCliRenderer({
       exitOnCtrlC: false,
       useMouse: true,
@@ -4404,8 +4626,8 @@ class App {
       height: "100%",
       border: false
     });
-    const processHexColors = buildProcessHexColorMap(this.names, this.config);
-    this.tabBar = new TabBar(this.renderer, this.names, processHexColors, this.config.sort === "status");
+    const processHexColors = buildProcessHexColorMap(this.names, this.config, this.theme.palette);
+    this.tabBar = new TabBar(this.renderer, this.names, processHexColors, this.theme, this.config.sort === "status");
     const contentRow = new BoxRenderable3(this.renderer, {
       id: "content-row",
       flexDirection: "row",
@@ -4418,7 +4640,8 @@ class App {
       width: this.sidebarWidth,
       height: "100%",
       border: ["right"],
-      borderColor: "#444"
+      borderColor: this.theme.sidebarBorder,
+      backgroundColor: this.theme.sidebarBg
     });
     sidebar.add(this.tabBar.renderable);
     const paneContainer = new BoxRenderable3(this.renderer, {
@@ -4426,8 +4649,8 @@ class App {
       flexGrow: 1,
       border: false
     });
-    this.statusBar = new StatusBar(this.renderer);
-    this.helpOverlay = new HelpOverlay(this.renderer);
+    this.statusBar = new StatusBar(this.renderer, this.theme);
+    this.helpOverlay = new HelpOverlay(this.renderer, this.theme);
     this.search = new SearchController({
       logWriter: this.logWriter,
       statusBar: this.statusBar,
@@ -4437,7 +4660,7 @@ class App {
     });
     for (const name of this.names) {
       const interactive = this.config.processes[name].interactive === true;
-      const pane = new Pane(this.renderer, name, termCols, termRows, interactive);
+      const pane = new Pane(this.renderer, name, termCols, termRows, interactive, this.theme);
       if (this.config.timestamps) {
         pane.setTimestamps(this.config.timestamps);
       }
@@ -5455,6 +5678,9 @@ async function main() {
   if (parsed.only || parsed.exclude) {
     config = filterConfig(config, parsed.only, parsed.exclude);
   }
+  if (parsed.theme) {
+    config.theme = parsed.theme;
+  }
   if (parsed.autoColors) {
     for (const [name, proc] of Object.entries(config.processes)) {
       if (!proc.color) {

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { Color } from './utils/color';
+import type { ThemePref } from './utils/theme';
 export interface NumuxProcessConfig<K extends string = string> {
     /** Shell command to run. Supports `$dep.group` references from dependency capture groups */
     command: string;
@@ -122,6 +123,12 @@ export interface NumuxConfig<K extends string = string> {
     noWatch?: boolean;
     /** Directory to write per-process log files */
     logDir?: string;
+    /**
+     * TUI color theme. `'auto'` detects the terminal background via OSC 11 (falling back
+     * to `COLORFGBG` then dark). `'light'`/`'dark'` skip detection.
+     * @default 'auto'
+     */
+    theme?: ThemePref;
     processes: Record<K, NumuxProcessConfig<K> | NumuxScriptPattern<K> | string | true>;
 }
 export type SortOrder = 'config' | 'alphabetical' | 'topological' | 'status';
@@ -138,6 +145,7 @@ export interface ResolvedNumuxConfig {
     killOthersOnFail?: boolean;
     noWatch?: boolean;
     logDir?: string;
+    theme?: ThemePref;
     processes: Record<string, ResolvedProcessConfig>;
 }
 export type ProcessStatus = 'pending' | 'starting' | 'ready' | 'running' | 'stopping' | 'stopped' | 'finished' | 'failed' | 'skipped';

package/dist/utils/color.d.ts

@@ -34,7 +34,7 @@ export declare const ANSI_RESET = "\u001B[0m";
 export declare function stripAnsi(str: string): string;
 /** Pick a deterministic color from the default palette based on the process name */
 export declare function colorFromName(name: string): Color;
-/** Build a map of process names to ANSI color codes, using explicit config colors or a default palette. */
-export declare function buildProcessColorMap(names: string[], config: ResolvedNumuxConfig): Map<string, string>;
+/** Build a map of process names to ANSI color codes, using explicit config colors or a palette. */
+export declare function buildProcessColorMap(names: string[], config: ResolvedNumuxConfig, palette?: readonly string[]): Map<string, string>;
 /** Build a map of process names to hex color strings (for StyledText rendering). */
-export declare function buildProcessHexColorMap(names: string[], config: ResolvedNumuxConfig): Map<string, string>;
+export declare function buildProcessHexColorMap(names: string[], config: ResolvedNumuxConfig, palette?: readonly string[]): Map<string, string>;

package/dist/utils/theme.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Light/dark theme resolution. Detects terminal background via OSC 11
+ * query, falling back to COLORFGBG env var, then to dark. Explicit
+ * user config (`theme: 'light' | 'dark'`) skips detection entirely.
+ */
+export type ThemeMode = 'light' | 'dark';
+export type ThemePref = ThemeMode | 'auto';
+export interface StatusColors {
+    ready: string;
+    failed: string;
+    stopped: string;
+    finished: string;
+    skipped: string;
+}
+export interface Theme {
+    mode: ThemeMode;
+    statusBarBg: string;
+    statusBarText: string;
+    helpBackdropBg: string;
+    helpBoxBg: string;
+    helpBorder: string;
+    helpText: string;
+    sidebarBg: string;
+    sidebarBorder: string;
+    tabSelectedBg: string;
+    tabSelectedText: string;
+    tabText: string;
+    tabDescriptionText: string;
+    tabSelectedDescriptionText: string;
+    scrollTrackBg: string;
+    scrollThumbBg: string;
+    searchCurrentBg: string;
+    searchMatchBg: string;
+    palette: readonly string[];
+    status: StatusColors;
+    inputWaiting: string;
+    errorIndicator: string;
+    searchMatchTab: string;
+    iconDefault: string;
+}
+export declare const DARK_THEME: Theme;
+export declare const LIGHT_THEME: Theme;
+export declare function themeFor(mode: ThemeMode): Theme;
+/** WCAG relative luminance (0–1). */
+export declare function relativeLuminance(r: number, g: number, b: number): number;
+export declare function isLightRgb(r: number, g: number, b: number): boolean;
+/**
+ * Parse OSC 11 response body. Accepts `rgb:RRRR/GGGG/BBBB` (4 hex digits,
+ * xterm/Ghostty/kitty/alacritty/iTerm2) or 2-digit short form. Returns null
+ * on malformed input.
+ */
+export declare function parseOSC11Response(data: string): {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+/**
+ * Parse COLORFGBG env var (e.g. `"15;0"` = white fg on black bg = dark).
+ * Convention: bg index ≥7 is light, otherwise dark. iTerm2 sometimes sets
+ * the middle field to `default`; we read the last segment as the bg.
+ */
+export declare function parseColorFgBg(value: string | undefined): ThemeMode | null;
+/**
+ * Query the terminal's background color via OSC 11. Resolves to `null` on
+ * non-TTY, timeout, or unparseable response. Runs synchronously-ish in under
+ * `timeoutMs` (default 100ms). Must be called before any renderer takes
+ * over stdin.
+ */
+export declare function queryOSC11(timeoutMs?: number): Promise<ThemeMode | null>;
+export declare function detectThemeMode(timeoutMs?: number): Promise<ThemeMode | null>;
+/**
+ * Resolve final theme. Explicit `'light'`/`'dark'` skips detection;
+ * `'auto'` (or undefined) runs detection, falling back to dark.
+ */
+export declare function resolveTheme(pref?: ThemePref | undefined): Promise<Theme>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "numux",
-  "version": "2.16.2",
+  "version": "2.17.0",
   "description": "Terminal multiplexer with dependency orchestration",
   "type": "module",
   "license": "MIT",