core: auto-detect terminal background and apply light theme on first start

Detect the terminal background (via COLORFGBG or an OSC 11 query) before
GUI init and, on the first start, automatically apply the built-in
"light" theme when a light terminal is detected.

The function gui_term_theme_is_light returns an int (1 if light, 0 otherwise,
0 being the safe value when detection is unsure).

CHANGELOG.md

@@ -17,6 +17,7 @@ SPDX-License-Identifier: GPL-3.0-or-later
 ### Added
 
 - core: add `/theme` command with subcommands `list`, `apply`, `reset`, `save`, `delete`, `info`, automatic backup of current themable options before apply, and built-in "light" theme
+- core: detect terminal background on first start and automatically apply the built-in "light" theme when a light terminal is detected
 - core: add `themable` flag on configuration options (auto-set for color options; explicit opt-in for string options containing `${color:...}` references via the `type|themable` syntax)
 - core: add option weechat.look.theme (informational, set by `/theme apply`)
 - core: add option weechat.look.theme_backup (boolean, default `on`)

src/core/weechat.c

@@ -98,6 +98,7 @@ char *weechat_argv0 = NULL;            /* WeeChat binary file name (argv[0])*/
 int weechat_upgrading = 0;             /* =1 if WeeChat is upgrading        */
 int weechat_first_start = 0;           /* first start of WeeChat?           */
 time_t weechat_first_start_time = 0;   /* start time (used by /uptime cmd)  */
+int weechat_term_theme_light = 0;      /* 1 if light theme detected         */
 int weechat_upgrade_count = 0;         /* number of /upgrade done           */
 struct timeval weechat_current_start_timeval; /* start time used to display */
                                        /* duration of /upgrade              */
@@ -183,22 +184,34 @@ weechat_startup_message (void)
     if (weechat_first_start)
     {
         /* message on first run (when weechat.conf is created) */
-        gui_chat_printf (NULL, "");
+        gui_chat_printf (NULL, _("Welcome to WeeChat!"));
         gui_chat_printf (
             NULL,
-            _("Welcome to WeeChat!\n"
-              "\n"
-              "If you are discovering WeeChat, it is recommended to read at "
-              "least the quickstart guide, and the user's guide if you have "
-              "some time; they explain main WeeChat concepts.\n"
-              "All WeeChat docs are available at: https://weechat.org/doc/\n"
-              "\n"
-              "Moreover, there is inline help with /help on all commands and "
-              "options (use Tab key to complete the name).\n"
-              "The command /fset can help to customize WeeChat.\n"
-              "\n"
-              "You can add and connect to an IRC server with /server and "
+            _("If you are discovering WeeChat, it is recommended to "
+              "read at least the quickstart guide, and the user's guide if "
+              "you have some time; they explain main WeeChat concepts."));
+        gui_chat_printf (
+            NULL,
+            _("All WeeChat docs are available at: %s"),
+            WEECHAT_WEBSITE_DOC);
+        gui_chat_printf (
+            NULL,
+            _("Moreover, there is inline help with /help on all commands and "
+              "options (use Tab key to complete the name)."));
+        gui_chat_printf (
+            NULL,
+            _("The command /fset can help to customize WeeChat."));
+        gui_chat_printf (
+            NULL,
+            _("You can add and connect to an IRC server with /server and "
               "/connect commands (see /help server)."));
+        if (weechat_term_theme_light)
+        {
+            gui_chat_printf (
+                NULL,
+                _("The \"light\" theme will be automatically applied. "
+                "Use /theme reset to switch back to the default dark theme."));
+        }
         gui_chat_printf (NULL, "");
         gui_chat_printf (NULL, "---");
         gui_chat_printf (NULL, "");
@@ -369,6 +382,9 @@ weechat_init (int argc, char *argv[], void (*gui_init_cb)(void))
             * weechat_current_start_timeval.tv_usec)
            ^ getpid ());
 
+    /* detect the terminal theme, before initializing the GUI */
+    weechat_term_theme_light = gui_term_theme_is_light ();
+
     weeurl_init ();                     /* initialize URL                   */
     string_init ();                     /* initialize string                */
     signal_init ();                     /* initialize signals               */
@@ -426,6 +442,13 @@ weechat_init (int argc, char *argv[], void (*gui_init_cb)(void))
         weechat_doc_gen_ok = doc_generate (weechat_doc_gen_path);
         weechat_quit = 1;
     }
+
+    if (weechat_first_start && isatty (STDOUT_FILENO) && !weechat_headless && !weechat_doc_gen)
+    {
+        /* switch to "light" theme if terminal background was detected as "light" */
+        if (weechat_term_theme_light)
+            theme_apply ("light");
+    }
 }
 
 /*

src/core/weechat.h

@@ -55,6 +55,7 @@
 
 #define WEECHAT_COPYRIGHT_DATE   "(C) 2003-2026"
 #define WEECHAT_WEBSITE          "https://weechat.org/"
+#define WEECHAT_WEBSITE_DOC      "https://weechat.org/doc/"
 #define WEECHAT_WEBSITE_DOWNLOAD "https://weechat.org/download/"
 #define WEECHAT_AUTHOR_NAME      "Sébastien Helleu"
 #define WEECHAT_AUTHOR_EMAIL     "flashcode@flashtux.org"

src/gui/gui-main.h

@@ -31,5 +31,6 @@ extern void gui_main_end (int clean_exit);
 
 /* terminal functions (GUI dependent) */
 extern void gui_term_set_eat_newline_glitch (int value);
+extern int gui_term_theme_is_light (void);
 
 #endif /* WEECHAT_GUI_MAIN_H */

tests/unit/CMakeLists.txt

@@ -114,6 +114,7 @@ set(LIB_WEECHAT_UNIT_TESTS_CORE_SRC
   gui/test-gui-nick.cpp
   gui/test-gui-nicklist.cpp
   gui/curses/test-gui-curses-mouse.cpp
+  gui/curses/test-gui-curses-term.cpp
   scripts/test-scripts.cpp
 )
 add_library(weechat_unit_tests_core STATIC ${LIB_WEECHAT_UNIT_TESTS_CORE_SRC})

tests/unit/gui/curses/test-gui-curses-term.cpp

@@ -0,0 +1,87 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Sébastien Helleu <flashcode@flashtux.org>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * This file is part of WeeChat, the extensible chat client.
+ *
+ * WeeChat is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * WeeChat is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with WeeChat.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/* Test terminal functions (Curses interface) */
+
+#include "CppUTest/TestHarness.h"
+
+extern "C"
+{
+#include <stdlib.h>
+#include <string.h>
+
+extern int gui_term_theme_is_light (void);
+}
+
+/*
+ * Asserts the value returned by gui_term_theme_is_light() when COLORFGBG
+ * is set to the given value (a definitive background index, so detection
+ * returns without falling back to the terminal query on /dev/tty).
+ */
+
+#define WEE_CHECK_THEME(__result, __colorfgbg)                          \
+    setenv ("COLORFGBG", __colorfgbg, 1);                               \
+    LONGS_EQUAL(__result, gui_term_theme_is_light ());
+
+TEST_GROUP(GuiCursesTerm)
+{
+};
+
+/*
+ * Test functions:
+ *   gui_term_theme_is_light
+ */
+
+TEST(GuiCursesTerm, ThemeIsLight)
+{
+    const char *saved_colorfgbg;
+    char *colorfgbg;
+
+    /* save COLORFGBG to restore it at the end of the test */
+    saved_colorfgbg = getenv ("COLORFGBG");
+    colorfgbg = (saved_colorfgbg) ? strdup (saved_colorfgbg) : NULL;
+
+    /* dark background ("fg;bg"): indices 0-6 and 8 */
+    WEE_CHECK_THEME(0, "15;0");
+    WEE_CHECK_THEME(0, "15;1");
+    WEE_CHECK_THEME(0, "15;6");
+    WEE_CHECK_THEME(0, "15;8");
+
+    /* light background ("fg;bg"): index 7 and 9-15 */
+    WEE_CHECK_THEME(1, "0;7");
+    WEE_CHECK_THEME(1, "0;9");
+    WEE_CHECK_THEME(1, "0;15");
+
+    /* "fg;default;bg" form: last component is the background */
+    WEE_CHECK_THEME(0, "0;default;0");
+    WEE_CHECK_THEME(1, "0;default;15");
+
+    /* restore COLORFGBG */
+    if (colorfgbg)
+    {
+        setenv ("COLORFGBG", colorfgbg, 1);
+        free (colorfgbg);
+    }
+    else
+    {
+        unsetenv ("COLORFGBG");
+    }
+}

tests/unit/tests.cpp

@@ -119,6 +119,7 @@ IMPORT_TEST_GROUP(GuiNick);
 IMPORT_TEST_GROUP(GuiNicklist);
 /* GUI - Curses */
 IMPORT_TEST_GROUP(GuiCursesMouse);
+IMPORT_TEST_GROUP(GuiCursesTerm);
 /* scripts */
 IMPORT_TEST_GROUP(Scripts);