feat: add theme-aware default for label_color - Closes #489 (#491)

Author: tkhorik

configs/default-config.toml

@@ -248,7 +248,8 @@ keys = "uijk"
 line_color = "#FF8EE2FF"          # Color of grid lines (light blue, alpha FF = 100% opacity)
 line_width = 1                    # Width of grid lines
 highlight_color = "#4D00BFFF"     # Color for cell highlighting (deep sky blue, alpha 4D ≈ 30% opacity)
-label_color = "#FFFFFFFF"         # Color of cell labels (white, alpha FF = 100% opacity)
+# label_color = ""               # Theme-aware: auto white in Dark Mode, black in Light Mode
+                                  # Uncomment and set a value to override (e.g. "#FFFFFFFF")
 label_font_size = 10              # Font size for labels
 label_font_family = ""            # Font family for labels
 

docs/CONFIGURATION.md

@@ -702,13 +702,19 @@ j   →   k          j = Lower-left
 
 ### Visual Options
 
-| Option            | Type   | Default       | Description             |
-| ----------------- | ------ | ------------- | ----------------------- |
-| `line_color`      | string | `"#FF8EE2FF"` | Grid line color         |
-| `line_width`      | int    | `1`           | Line thickness          |
-| `highlight_color` | string | `"#4D00BFFF"` | Selected cell highlight |
-| `label_color`     | string | `"#FFFFFFFF"` | Cell label text         |
-| `label_font_size` | int    | `10`          | Label size              |
+| Option            | Type   | Default              | Description                                                                    |
+| ----------------- | ------ | -------------------- | ------------------------------------------------------------------------------ |
+| `line_color`      | string | `"#FF8EE2FF"`        | Grid line color                                                                |
+| `line_width`      | int    | `1`                  | Line thickness                                                                 |
+| `highlight_color` | string | `"#4D00BFFF"`        | Selected cell highlight                                                        |
+| `label_color`     | string | _(theme-aware)_      | Cell label text. Auto-adapts to macOS Dark/Light Mode if not explicitly set     |
+| `label_font_size` | int    | `10`                 | Label size                                                                     |
+
+> **Theme-aware `label_color`:** When `label_color` is not set in your config file,
+> Neru automatically uses white (`#FFFFFFFF`) in Dark Mode and black (`#FF000000`) in
+> Light Mode. The color updates in real time when you switch system themes — no restart
+> required. If you explicitly set `label_color`, your value is always used regardless
+> of the system theme.
 
 ---
 

internal/app/app_config.go

@@ -49,9 +49,6 @@ func (a *App) prepareForConfigUpdate() {
 
 // applyAppSpecificConfigUpdates applies app-specific configuration updates.
 func (a *App) applyAppSpecificConfigUpdates(loadResult *config.LoadResult) {
-	a.config = loadResult.Config
-	a.ConfigPath = loadResult.ConfigPath
-
 	if loadResult.Config.Hints.Enabled {
 		a.logger.Info("Updating clickable roles",
 			zap.Int("count", len(loadResult.Config.Hints.ClickableRoles)))
@@ -61,6 +58,12 @@ func (a *App) applyAppSpecificConfigUpdates(loadResult *config.LoadResult) {
 
 // reconfigureAfterUpdate reconfigures components and services after config update.
 func (a *App) reconfigureAfterUpdate(loadResult *config.LoadResult) {
+	// Update the config pointer under configMu so that concurrent readers
+	// (e.g. screen-change handlers, theme observer) see a consistent value.
+	a.configMu.Lock()
+	a.config = loadResult.Config
+	a.ConfigPath = loadResult.ConfigPath
+	a.configMu.Unlock()
 	a.configureEventTapHotkeys(loadResult.Config, a.logger)
 
 	if a.hintsComponent != nil {

internal/app/app_getters.go

@@ -10,6 +10,17 @@ import (
 	"go.uber.org/zap"
 )
 
+// configSnapshot returns the current config pointer under a read lock.
+// Callers should use the returned pointer for all reads within a single
+// logical operation to avoid seeing a partially-updated config.
+func (a *App) configSnapshot() *config.Config {
+	a.configMu.RLock()
+	cfg := a.config
+	a.configMu.RUnlock()
+
+	return cfg
+}
+
 // SetEnabled sets the enabled state of the application.
 func (a *App) SetEnabled(v bool) {
 	a.appState.SetEnabled(v)
@@ -27,22 +38,28 @@ func (a *App) ToggleEnabled() {
 
 // HintsEnabled returns true if hints are enabled.
 func (a *App) HintsEnabled() bool {
-	return a.config != nil && a.config.Hints.Enabled
+	cfg := a.configSnapshot()
+
+	return cfg != nil && cfg.Hints.Enabled
 }
 
 // GridEnabled returns true if grid is enabled.
 func (a *App) GridEnabled() bool {
-	return a.config != nil && a.config.Grid.Enabled
+	cfg := a.configSnapshot()
+
+	return cfg != nil && cfg.Grid.Enabled
 }
 
 // RecursiveGridEnabled returns true if recursive-grid is enabled.
 func (a *App) RecursiveGridEnabled() bool {
-	return a.config != nil && a.config.RecursiveGrid.Enabled
+	cfg := a.configSnapshot()
+
+	return cfg != nil && cfg.RecursiveGrid.Enabled
 }
 
 // Config returns the application configuration.
 func (a *App) Config() *config.Config {
-	return a.config
+	return a.configSnapshot()
 }
 
 // Logger returns the application logger.
@@ -71,7 +88,11 @@ func (a *App) Renderer() *ui.OverlayRenderer {
 
 // GetConfigPath returns the config path.
 func (a *App) GetConfigPath() string {
-	return a.ConfigPath
+	a.configMu.RLock()
+	p := a.ConfigPath
+	a.configMu.RUnlock()
+
+	return p
 }
 
 // SetHintOverlayNeedsRefresh sets the hint overlay needs refresh flag.

internal/app/app_initialization_steps.go

@@ -193,7 +193,10 @@ func initializeRendererAndOverlays(app *App) {
 		recursiveGridStyle = app.recursiveGridComponent.Style
 	} else {
 		// Fallback to default style if component is nil
-		recursiveGridStyle = recursivegrid.BuildStyle(config.DefaultConfig().RecursiveGrid)
+		recursiveGridStyle = recursivegrid.BuildStyle(
+			config.DefaultConfig().RecursiveGrid,
+			defaultThemeProvider,
+		)
 	}
 
 	app.renderer = ui.NewOverlayRenderer(
@@ -300,6 +303,7 @@ func initializeModeHandler(app *App) {
 		deps.callbacks.enableEventTap,
 		deps.callbacks.disableEventTap,
 		deps.callbacks.refreshHotkeys,
+		defaultThemeProvider,
 	)
 }
 

internal/app/app_types.go

@@ -56,6 +56,10 @@ type App struct {
 	stopChan chan struct{}
 	stopOnce sync.Once
 
+	// configMu serializes access to config-dependent component state between
+	// concurrent writers (theme change observer, IPC config reload, systray reload).
+	configMu sync.RWMutex
+
 	// New Architecture Services
 	hintService          *services.HintService
 	gridService          *services.GridService

internal/app/component_factory.go

@@ -243,9 +243,10 @@ func (f *ComponentFactory) CreateRecursiveGridComponent(
 	}
 
 	return &components.RecursiveGridComponent{
-		Overlay: recursiveGridOverlay,
-		Context: &recursivegrid.Context{},
-		Style:   recursivegrid.BuildStyle(f.config.RecursiveGrid),
+		Overlay:       recursiveGridOverlay,
+		Context:       &recursivegrid.Context{},
+		Style:         recursivegrid.BuildStyle(f.config.RecursiveGrid, defaultThemeProvider),
+		ThemeProvider: defaultThemeProvider,
 	}, nil
 }
 

internal/app/components/recursivegrid/overlay.go

@@ -439,12 +439,14 @@ func (s Style) LabelFontFamily() string {
 }
 
 // BuildStyle creates a Style from RecursiveGridConfig.
-func BuildStyle(cfg config.RecursiveGridConfig) Style {
+// The theme parameter is used to resolve the label color when it is not
+// explicitly specified in the configuration (empty string = theme-aware default).
+func BuildStyle(cfg config.RecursiveGridConfig, theme config.ThemeProvider) Style {
 	return Style{
 		lineColor:       cfg.LineColor,
 		lineWidth:       cfg.LineWidth,
 		highlightColor:  cfg.HighlightColor,
-		labelColor:      cfg.LabelColor,
+		labelColor:      config.ResolvedLabelColor(cfg.LabelColor, theme),
 		labelFontSize:   cfg.LabelFontSize,
 		labelFontFamily: cfg.LabelFontFamily,
 	}

internal/app/components/types.go

@@ -106,16 +106,17 @@ func (m *ModeIndicatorComponent) UpdateConfig(cfg *config.Config, _ *zap.Logger)
 
 // RecursiveGridComponent encapsulates all recursive-grid-related functionality.
 type RecursiveGridComponent struct {
-	Manager *domainRecursiveGrid.Manager
-	Overlay *recursivegrid.Overlay
-	Context *recursivegrid.Context
-	Style   recursivegrid.Style
+	Manager       *domainRecursiveGrid.Manager
+	Overlay       *recursivegrid.Overlay
+	Context       *recursivegrid.Context
+	Style         recursivegrid.Style
+	ThemeProvider config.ThemeProvider
 }
 
 // UpdateConfig updates the recursive-grid component with new configuration.
 func (q *RecursiveGridComponent) UpdateConfig(cfg *config.Config, _ *zap.Logger) {
 	if cfg.RecursiveGrid.Enabled {
-		q.Style = recursivegrid.BuildStyle(cfg.RecursiveGrid)
+		q.Style = recursivegrid.BuildStyle(cfg.RecursiveGrid, q.ThemeProvider)
 		if q.Overlay != nil {
 			q.Overlay.SetConfig(cfg.RecursiveGrid)
 		}

internal/app/hotkeys.go

@@ -14,7 +14,9 @@ import (
 
 // registerHotkeys registers all global hotkeys defined in the configuration.
 func (a *App) registerHotkeys() {
-	for key, value := range a.config.Hotkeys.Bindings {
+	cfg := a.configSnapshot()
+
+	for key, value := range cfg.Hotkeys.Bindings {
 		trimmedKey := strings.TrimSpace(key)
 
 		actionStr := strings.TrimSpace(value)
@@ -27,15 +29,15 @@ func (a *App) registerHotkeys() {
 			mode = parts[0]
 		}
 
-		if mode == domain.ModeString(domain.ModeHints) && !a.config.Hints.Enabled {
+		if mode == domain.ModeString(domain.ModeHints) && !cfg.Hints.Enabled {
 			continue
 		}
 
-		if mode == domain.ModeString(domain.ModeGrid) && !a.config.Grid.Enabled {
+		if mode == domain.ModeString(domain.ModeGrid) && !cfg.Grid.Enabled {
 			continue
 		}
 
-		if mode == domain.ModeString(domain.ModeRecursiveGrid) && !a.config.RecursiveGrid.Enabled {
+		if mode == domain.ModeString(domain.ModeRecursiveGrid) && !cfg.RecursiveGrid.Enabled {
 			continue
 		}
 
@@ -182,7 +184,9 @@ func (a *App) refreshHotkeysForAppOrCurrent(bundleID string) {
 		}
 	}
 
-	if a.config.IsAppExcluded(bundleID) {
+	cfg := a.configSnapshot()
+
+	if cfg.IsAppExcluded(bundleID) {
 		if a.appState.HotkeysRegistered() {
 			a.logger.Info("Focused app excluded; unregistering global hotkeys",
 				zap.String("bundle_id", bundleID))