feat(themes): follow macOS Appearance and auto-switch dark/light

[panosAthDBX]

Summary

Adds an opt-in feature that makes the sidebar track the macOS system Appearance setting: when the user toggles System Settings → Appearance between Light and Dark, the active theme flips to their configured dark/light pair within ~3 seconds, and every connected sidebar re-renders in sync.

macOS-gated — no-op on Linux/Windows.

Config (all opt-in)

{
  "autoThemeFollowsSystem": true,
  "darkTheme":  "catppuccin-mocha",
  "lightTheme": "catppuccin-latte"
}

• autoThemeFollowsSystem — enables the poller (default: off).
• darkTheme / lightTheme — any of the 20 built-in theme names; default to the catppuccin pair that best matches the existing default theme.

How it works

• New module packages/runtime/src/system-theme.ts exposes two helpers:
  • readMacSystemAppearance() — reads defaults read -g AppleInterfaceStyle via Bun.spawn, maps to "dark" or "light", short-circuits on non-darwin.
  • themeForSystemMode(mode, dark, light) — pure mapping.
• startServer() spawns a 3s setInterval that calls both helpers; when the desired theme differs from currentTheme, it takes the same path as the manual set-theme command: update local state → saveConfig → broadcastState. That means every connected sidebar picks up the switch through the existing WebSocket broadcast — no new wire format.
• Timer is cleared in cleanup() alongside the other interval timers, so it unwinds cleanly on SIGINT/SIGTERM.

macOS doesn't expose a CLI-visible change notification for Appearance, so polling is pragmatic; each poll is one cheap defaults subprocess.

Changes

• New: packages/runtime/src/system-theme.ts (42 lines) — pure helpers.
• New: packages/runtime/test/system-theme.test.ts — 5 tests covering the mapping + non-darwin short-circuit.
• packages/runtime/src/config.ts — three new optional fields on OpensessionsConfig.
• packages/runtime/src/server/index.ts — import, timer declaration, poller in startServer(), cleanup teardown.
• packages/runtime/test/config.test.ts — 2 tests for the new fields (round-trip + unset defaults).

Test plan

• bun test packages/runtime/test/system-theme.test.ts — 5/5 pass
• bun test packages/runtime/test/config.test.ts — 19/19 pass (2 new + 17 existing)
• bun test packages/runtime/test — 374/374 pass, no regressions
• Running locally on darwin 25.4 for a few hours — toggling Appearance in System Settings flips every open sidebar within 3s as expected; disabling the config puts the behavior back to manual

Happy to iterate on the 3s cadence, the default theme pair, or the config key names.

[inspect-review]

inspect review

Triage: 8 entities analyzed | 0 critical, 0 high, 2 medium, 6 low
Verdict: standard_review

Findings (1)

1. [low] Config test writes config.json into a directory that is never created, so Bun.write() will fail with ENOENT before loadConfig() is exercised. Evidence: const configDir = join(tmpDir, ".config", "opensessions"); await Bun.write(join(configDir, "config.json"), ...) with no mkdir/ensureDir for configDir.

---

Reviewed by inspect | Entity-level triage found 0 high-risk changes

[panosAthDBX]

Pushed a follow-up fix on top of the original commit:

fix(themes): persist manual override per system appearance

The original implementation had a bug where, with auto-follow on, a manual set-theme override was silently overwritten on the next 3s poll. The handler wrote to config.theme but the poll loop only consults darkTheme / lightTheme.

Changes:

• set-theme now writes to darkTheme or lightTheme based on the current observed appearance
• The poll loop re-reads darkTheme / lightTheme from disk each cycle so a manual override is picked up immediately
• Removed the saveConfig({ theme: desired }) write inside the poll loop (was clobbering the user's static-mode theme field)

All 374 tests still pass.

[inspect-review]

inspect review

Triage: 11 entities analyzed | 0 critical, 0 high, 3 medium, 8 low
Verdict: standard_review

Findings (2)

1. [low] Test bug: config round-trip test writes to a config path whose parent directories are never created, so Bun.write(join(configDir, "config.json"), ...) can fail before assertions. Evidence: const configDir = join(tmpDir, ".config", "opensessions"); await Bun.write(join(configDir, "config.json"), ...) with no mkdir for configDir.
2. [low] Test bug: system-theme.test attempts to redefine process.platform via Object.defineProperty. In many runtimes this property is non-configurable/read-only, so redefining it can throw and fail the test. Evidence: Object.defineProperty(process, "platform", { value: "linux", configurable: true }); and later restoring similarly.

---

Reviewed by inspect | Entity-level triage found 0 high-risk changes