Use globals for color variables, react to light/dark mode

Implicitly-universal variables have some downsides:
- It's surprising that "set fish_color_normal ..."
  and "set fish_key_bindings fish_vi_key_bindings" propagate to other
  shells and persist, especially since all other variables (and other
  shells) would use the global scope.
- they don't play well with tracking configuration in Git.
- we don't know how to roll out updates to the default theme (which is
  problematic since can look bad depending on terminal background
  color scheme).

It's sort of possible to use only globals and unset universal variables
(because fish only sets them at first startup), but that requires
knowledge of fish internals; I don't think many people do that.

So:
- Set all color variables that are not already set as globals.
  - To enable this do the following, once, after upgrading:
    copy any existing universal color variables to globals, and:
    - if existing universal color variables exactly match
      the previous default theme, and pretend they didn't exist.
    - else migrate the universals to ~/.config/fish/conf.d/fish_frozen_theme.fish,
      which is a less surprising way of persisting this.
    - either way, delete all universals to do the right thing for most users.
- Make sure that webconfig's "Set Theme" continues to:
  - instantly update all running shells
    - This is achieved by a new universal variable (but only for
      notifying shells, so this doesn't actually need to be persisted).
      In future, we could use any other IPC mechanism such as "kill -SIGUSR1"
      or if we go for a new feature, "varsave" or "set --broadcast", see
      https://github.com/fish-shell/fish-shell/issues/7317#issuecomment-701165897
      https://github.com/fish-shell/fish-shell/pull/8455#discussion_r757837137.
  - persist the theme updates, completely overriding any previous theme.
    Use the same "fish_frozen_theme.fish" snippet as for migration (see above).
    It's not meant to be edited directly. If people want flexibility
    the should delete it.
    It could be a universal variable instead of a conf snippet file;
    but I figured that the separate file looks nicer
    (we can have better comments etc.)
- Ask the terminal whether it's using dark or light mode, and use an
  optimized default. Add dark/light variants to themes,
  and the "unknown" variant for the default theme.
  Other themes don't need the "unknown" variant;
  webconfig already has a background color in context,
  and CLI can require the user to specify variant explicitly if
  terminal doesn't advertise colors.
- Every variable that is set as part of fish's default behavior
  gets a "--label=default" tacked onto it.

  This is to allow our fish_terminal_color_theme event handler to
  know which variables it is allowed to update. It's also necessary
  until we revert 7e3fac561d (Query terminal only just before reading
  from it, 2025-09-25) because since commit, we need to wait until
  the first reader_push() to get query results.  By this time, the
  user's config.fish may already have set variables.

  If the user sets variables via either webconfig, "fish_config theme
  {choose,save}", or directly via "set fish_color_...", they'd almost
  always remove this label.
- For consistency, make default fish_key_bindings global
  (note that, for better or worse, fish_add_path still remains as
  one place that implicitly sets universal variables, but it's not
  something we inject by default)
- Have "fish_config theme choose" and webconfig equivalents reset
  all color variables. This makes much more sense than keeping a
  hardcoded subset of "known colors"; and now that we don't really
  expect to be deleting universals this way, it's actually possible
  to make this change without much fear.

Should have split this into two commits (the changelog entries are
intertwined though).

Closes #11580
Closes #11435
Closes #7317
Ref: https://github.com/fish-shell/fish-shell/issues/12096#issuecomment-3632065704

doc_src/cmds/fish_config.rst

@@ -8,7 +8,12 @@ Synopsis
 
     fish_config [browse]
     fish_config prompt (choose | list | save | show)
-    fish_config theme (choose | demo | dump | list | save | show)
+    fish_config theme
+    fish_config theme choose THEME [ --color-theme=(dark | light) ]
+    fish_config theme demo
+    fish_config theme dump
+    fish_config theme list
+    fish_config theme show [THEME...]
 
 Description
 -----------
@@ -33,14 +38,17 @@ With the ``theme`` command ``fish_config`` can be used to view and choose a them
 Available subcommands for the ``theme`` command:
 
 - ``choose`` loads a theme in the current session.
+  To override :envvar:`fish_terminal_color_theme`, pass the ``--color-theme`` argument.
 - ``demo`` displays some sample text in the current theme.
 - ``dump`` prints the current theme in a loadable format.
 - ``list`` lists the names of the available themes.
-- ``save`` saves the given theme to :ref:`universal variables <variables-universal>`.
 - ``show`` shows what the given themes (or all) would look like.
+- *(deprecated, avoid use)* ``save`` saves the given theme to :ref:`universal variables <variables-universal>`.
 
 The **-h** or **--help** option displays help about using this command.
 
+.. _fish-config-theme-files:
+
 Theme Files
 -----------
 
@@ -60,22 +68,36 @@ The format looks like this:
 
 ::
 
-   # name: 'Cool Beans'
-   # preferred_background: black
+    # name: 'My Theme'
 
-   fish_color_autosuggestion 666
-   fish_color_cancel -r
-   fish_color_command normal
-   fish_color_comment '888'  '--italics'
-   fish_color_cwd 0A0
-   fish_color_cwd_root A00
-   fish_color_end 009900
+    [light]
+    # preferred_background: ffffff
+    fish_color_normal 000000
+    fish_color_autosuggestion 7f7f7f
+    fish_color_command 0000ee
 
-The two comments at the beginning are the name and background that the web config tool shows.
+    [dark]
+    # preferred_background: 000000
+    fish_color_normal ffffff
+    fish_color_autosuggestion 7f7f7f
+    fish_color_command 5c5cff
+
+    [unknown]
+    fish_color_normal normal
+    fish_color_autosuggestion brblack
+    fish_color_cancel -r
+    fish_color_command normal
+
+The comments provide name and background color to the web config tool.
+
+Themes can have three variants,
+one for light mode,
+one for dark mode,
+and one for terminals that don't :ref:`report colors <term-compat-query-background-color>` (where :envvar:`fish_terminal_color_theme` is set to ``unknown``).
 
 The other lines are just like ``set variable value``, except that no expansions are allowed. Quotes are, but aren't necessary.
 
-Any color variable fish knows about that the theme doesn't set will be set to empty when it is loaded, so the old theme is completely overwritten.
+.. _fish_config-color-variables:
 
 Other than that, .theme files can contain any variable with a name that matches the regular expression ``'^fish_(?:pager_)?color_.*$'`` - starts with ``fish_``, an optional ``pager_``, then ``color_`` and then anything.
 

doc_src/cmds/fish_hg_prompt.rst

@@ -23,7 +23,7 @@ The fish_hg_prompt function displays information about the current Mercurial rep
 
 By default, only the current branch is shown because ``hg status`` can be slow on a large repository. You can enable a more informative prompt by setting the variable ``$fish_prompt_hg_show_informative_status``, for example::
 
-    set --universal fish_prompt_hg_show_informative_status
+    set fish_prompt_hg_show_informative_status
 
 If you enabled the informative status, there are numerous customization options, which can be controlled with fish variables.
 

doc_src/cmds/set_color.rst

@@ -57,6 +57,15 @@ The following options are available:
 **-u** or **--underline**, or **-uSTYLE** or **--underline=STYLE**
     Set the underline mode; supported styles are **single** (default), **double**, **curly**, **dotted** and **dashed**.
 
+**--theme=THEME**
+    Ignored.
+    :ref:`Color variables <variables-color>` that contain only this option are treated like missing / empty color variables,
+    i.e. fish will use the fallback color instead.
+    :doc:`fish_config theme choose <fish_config>` erases all :ref:`color variable <fish_config-color-variables>`
+    whose value includes this option, and adds this option to all color variables it sets.
+    This allows identifying variables set by a theme,
+    and it allows fish to update color variables whenever :envvar:`fish_terminal_color_theme` changes.
+
 **-h** or **--help**
     Displays help about using this command.
 

doc_src/faq.rst

@@ -129,16 +129,14 @@ If you want to change or disable this display, modify the ``fish_mode_prompt`` f
 
 How do I customize my syntax highlighting colors?
 -------------------------------------------------
-Use the web configuration tool, :doc:`fish_config <cmds/fish_config>`, or alter the :ref:`fish_color family of environment variables <variables-color>`.
-
-You can also use ``fish_config`` on the commandline, like::
+Use the web configuration tool started by :doc:`fish_config <cmds/fish_config>`,
+or alter the :ref:`fish_color family of environment variables <variables-color>`,
+or use the :doc:`fish_config theme <cmds/fish_config>` subcommand, like::
 
   > fish_config theme show
   # to demonstrate all the colorschemes
   > fish_config theme choose coolbeans
   # to load the "coolbeans" theme
-  > fish_config theme save
-  # to make the change permanent
 
 How do I change the greeting message?
 -------------------------------------

doc_src/interactive.rst

@@ -73,7 +73,7 @@ Detected errors include:
 To customize the syntax highlighting, you can set the environment variables listed in the :ref:`Variables for changing highlighting colors <variables-color>` section.
 
 Fish also provides pre-made color themes you can pick with :doc:`fish_config <cmds/fish_config>`.
-Running just ``fish_config`` opens a browser interface, or you can use ``fish_config theme`` in the terminal.
+Running just ``fish_config`` opens a browser interface, or you can use ``fish_config theme`` from fish.
 
 For example, to disable nearly all coloring::
 
@@ -83,6 +83,20 @@ Or, to see all themes, right in your terminal::
 
   fish_config theme show
 
+.. _syntax-highlighting-instant-update:
+
+To update the theme of all shell sessions without restarting them,
+first have those sessions define an :ref:`event handler <event>` by adding the following to your :ref:`config.fish <configuration>` and restarting them::
+
+    function apply-my-theme --on-variable=my_theme
+        fish_config theme choose $my_theme
+    end
+
+Then, set the corresponding :ref:`universal variable <variables-universal>` from any session::
+
+    > set -U my_theme lava
+    > set -U my_theme snow-day
+
 .. _variables-color:
 
 Syntax highlighting variables
@@ -137,7 +151,8 @@ Variable                                          Meaning
 
 ==========================================        =====================================================================
 
-If a variable isn't set or is empty, fish usually tries ``$fish_color_normal``, except for:
+If a variable isn't set or is empty after subtracting any ``--theme=THEME`` options,
+fish usually tries ``$fish_color_normal``, except for:
 
 - ``$fish_color_keyword``, where it tries ``$fish_color_command`` first.
 - ``$fish_color_option``, where it tries ``$fish_color_param`` first.

doc_src/language.rst

@@ -1235,11 +1235,6 @@ If you want to set something in config.fish, or set something in a function and
     # Set my language
     set -gx LANG de_DE.UTF-8
 
-If you want to set some personal customization, universal variables are nice::
-
-     # Typically you'd run this interactively, fish takes care of keeping it.
-     set -U fish_color_autosuggestion 555
-
 Here is an example of local vs function-scoped variables::
 
   function test-scopes
@@ -1317,9 +1312,8 @@ This syntax is supported since fish 3.1.
 Universal Variables
 ^^^^^^^^^^^^^^^^^^^
 
-Universal variables are variables that are shared between all the user's fish sessions on the computer. Fish stores many of its configuration options as universal variables. This means that in order to change fish settings, all you have to do is change the variable value once, and it will be automatically updated for all sessions, and preserved across computer reboots and login/logout.
-
-To see universal variables in action, start two fish sessions side by side, and issue the following command in one of them ``set fish_color_cwd blue``. Since ``fish_color_cwd`` is a universal variable, the color of the current working directory listing in the prompt will instantly change to blue on both terminals.
+Universal variables are variables that are shared between all the user's fish sessions on the computer.
+All changes to universal variables are persistent and instantly propagated across fish sessions.
 
 :ref:`Universal variables <variables-universal>` are stored in the file ``.config/fish/fish_variables``. Do not edit this file directly, as your edits may be overwritten. Edit the variables through fish scripts or by using fish interactively instead.
 
@@ -1691,6 +1685,15 @@ Fish also provides additional information through the values of certain environm
 
    the process ID (PID) of the shell.
 
+.. envvar:: fish_terminal_color_theme
+
+   a read-only variable;
+   set to ``light`` or ``dark`` when the terminal uses a light or dark color theme respectively;
+   set to ``unknown`` if the terminal does not :ref:`report its colors <term-compat-query-background-color>`.
+   Like :ref:`status terminal <status-terminal>`, this is only populated once the first interactive prompt is shown.
+   This is used in an :ref:`--on-variable event handler <event>` to update :ref:`syntax highlighting <syntax-highlighting>` variables whenever the terminal's color theme changes.
+   See :ref:`here <fish-config-theme-files>` for how to specify ``light`` and ``dark`` variants in your theme.
+
 .. envvar:: history
 
    a list containing the last commands that were entered.

doc_src/terminal-compatibility.rst

@@ -215,6 +215,14 @@ Optional Commands
    * - ``\e[?2004l``
      -
      - Disable bracketed paste.
+   * - ``\e[?2031h``
+     -
+     - Enable unsolicited `color theme reporting <https://contour-terminal.org/vt-extensions/color-palette-update-notifications/>`_.
+       When enabled, the terminal should send ``\e[?997;1n`` or ``\e[?997;2n`` whenever its color theme has changed.
+       This prompts fish to query for :ref:`background color <term-compat-query-background-color>`.
+   * - ``\e[?2031l``
+     -
+     - Disable unsolicited color theme reporting.
    * - .. _term-compat-osc-0:
 
        ``\e]0; Pt \e\\``
@@ -234,6 +242,17 @@ Optional Commands
      -
      - Create a `hyperlink (OSC 8) <https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>`_.
        This is used in fish's man pages.
+   * - .. _term-compat-query-background-color:
+
+       ``\e]11;?\e\\``
+     - n/a
+     - Query background color.
+
+       A valid response would be of the form ``\e]11;rgb: Pt / Pt / Pt \e\\`` or ``\e]11;rgba: Pt / Pt / Pt / Pt\e\\``
+       where the first three parameters consist of one to four hex digits each, representing red, blue and green components.
+
+       This is used to populate :envvar:`fish_terminal_color_theme`,
+       which is used to select a :ref:`theme variant <fish-config-theme-files>` optimized for the terminal's color theme.
    * - .. _term-compat-osc-52:
 
        ``\e]52;c; Pt \e\\``