theme: a name and a directory, not sixty colours in your config

Wearing a theme meant pasting its `theme { }` block into config.kdl, or
including a path to a file you had copied there yourself. Both make the
palette a literal in your config, and a literal is the one thing you cannot
change cheaply: not from a script, not from a running session, not by a list
of what is available, and never again from upstream -- the colours you pasted
are the colours that theme had the day you pasted them.

So a theme is a file in a directory now, and a config names it:

    theme_name "phosphor"
    theme { frame_focus "#00ff88" }   // ...but that one colour is mine

theme_name is applied after the includes and before everything the file says
itself, which is the rule includes already follow and for the same reason: the
loader reads a document by asking it for names rather than walking it in order,
so "here" is not a position it could honour, and "what you asked for is the
base, what you wrote is yours" is the rule worth having.

Two directories, yours first: `themes/` beside the root config -- beside the
file that was loaded, so a config somewhere else (SLOSH_CONFIG, or one handed
to --check) takes its themes with it -- and then <prefix>/share/slosh/themes,
compiled in from PREFIX. install(1) has been putting themes there all along
and nothing could read them; now a shipped theme is nameable without being
copied, and a file of yours with the same name shadows it, which is how a
root-owned theme gets edited.

A name, not a path. The directory is what makes a theme switchable, listable
and shadowable, and a path silently does none of those, so `theme_name
"../x.kdl"` is refused with a line pointing at `include`, which still works
and is still the answer for a file somewhere a directory of names cannot
reach. A theme that is not there is one complaint and no more (D9): the rest
of the config applies, because losing your keybindings over a mistyped colour
scheme would be the wrong trade. A theme file is read by the same loader, so
it is watched like any other: saving one reloads the session wearing it, and
the derivations (tab_status_fg, tab_idle_bg) run over the theme's own colours
exactly as before.

Switching without editing anything, over the socket a session already has:

    slosh -s main cmd theme                                # amber default* ...
    slosh -s main cmd '{"cmd":"theme","name":"amber"}'      # now
    slosh -s main cmd '{"cmd":"theme","name":"amber","save":true}'

The session holds the name over later reloads, so saving your config for an
unrelated reason does not put the old colours back; `save` writes the
theme_name line into the file, replacing the one already there and leaving
every other line and comment alone -- dumping the whole config back over
itself would reformat a hand-written file and drop its comments, which is not
a fair price for changing a colour scheme. A name is tried on a throwaway
config first, so a typo costs nothing. An empty name gives the answer back to
the file.

--dump-config stops writing colours: it writes the theme's name and the
colours a config overrode by hand, so a dumped config keeps following its
theme instead of freezing it. --dump-theme is the other half and is new: the
resolved palette as a theme file, which is how you start one from the session
in front of you rather than from an empty file. It is also what keeps
contrib/themes/default.kdl honest -- that file is now the annotated reference
(the commented palette moved there out of config.kdl, where it was 119 lines
of colour in the middle of the prose), and a test compares it against the
compiled-in one.

While in there: tests/test_themes.py's "every theme sets every colour" guard
had been grepping for `&c->`, the spelling before the colour table moved to
offsetof, so it had been finding zero colours and passing for months. Fixed,
with the derived and opt-in colours exempted for the reasons they are derived
and opt-in, and with a check that the guard found a table at all.

3 files changed, 122 insertions, 19 deletions

diff --git a/docs/config.md b/docs/config.md
index fa287f1..6cee3d2 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -65,19 +65,62 @@ include "keys/vim.kdl" "shaders/crt.kdl"
 
 ## Themes
 
-Every colour the compositor draws has its own name under `theme { }`.
-
-Six ready-made themes are in
-`contrib/themes`:
-`amber`, `mono`, `paper`, `phosphor`, `sl0p`, `slate`, plus `default`, the
-compiled-in palette written out, so another theme is one include-swap away from
-coming back. Include one and put your own two lines on top:
+A theme is a file of colours in a directory, and a config names it:
 
 ```kdl
-include "~/.config/slosh/themes/phosphor.kdl"
+theme_name "phosphor"               // themes/phosphor.kdl
 theme { frame_focus "#00ff88" }     // ...but that one colour is mine
 ```
 
+**Named rather than pasted, because a name is a thing you can change.** It is
+one line to edit, one `{"cmd":"theme","name":"amber"}` to switch while the
+session is running, and one row in a list something can show you. Sixty colours
+pasted into a config are none of those — and they freeze the palette at the
+moment they were pasted, so every later improvement to the theme they came from
+is one you never see.
+
+**Two directories, yours first.** `themes/` beside your config (so
+`~/.config/slosh/themes` for the usual one), then the themes slosh installed in
+`<prefix>/share/slosh/themes`. A shipped theme is therefore nameable without
+being copied anywhere, and a file of yours with the same name shadows it —
+which is how you edit a shipped theme without touching a root-owned file. Point
+`theme_dir` somewhere else and that replaces the first of the two, never the
+shipped set.
+
+`theme_name` takes a **name, not a path**: the directory is what makes a theme
+switchable, listable and shadowable, and a path quietly does none of that. For
+a file somewhere a directory of names cannot reach, `include` is unchanged and
+still works.
+
+Seven themes ship in `contrib/themes`: `amber`, `mono`, `paper`, `phosphor`,
+`sl0p`, `slate`, and `default` — the annotated reference, every colour with
+what it is for, matching exactly what no config at all gets you. A theme file
+*is* a config file with one `theme { }` block in it, so `slosh --check` lints
+one and saving one reloads the session wearing it.
+
+Start your own from the session in front of you rather than from an empty file:
+
+```bash
+slosh --dump-theme > ~/.config/slosh/themes/mine.kdl   # the palette in force
+```
+
+`--dump-config` writes `theme_name` and the colours you overrode, not the
+resolved palette, so a dumped config keeps following its theme.
+
+**Switching without editing anything:**
+
+```bash
+slosh -s main cmd theme                                  # amber default* mono ...
+slosh -s main cmd '{"cmd":"theme","name":"amber"}'        # now
+slosh -s main cmd '{"cmd":"theme","name":"amber","save":true}'   # ...and from now on
+```
+
+The session holds the name over later reloads, so editing your config does not
+put the old colours back; `save` writes the `theme_name` line into the config,
+replacing the one already there, and leaves every other line and comment alone.
+`{"cmd":"theme","name":""}` drops the session's own answer and goes back to
+whatever the file says.
+
 ## The knobs, briefly
 
 | group     | what is in it                                                                                                                                                                                                                                                                      |
diff --git a/docs/slosh.1 b/docs/slosh.1
index 6436f6a..aba19ac 100644
--- a/docs/slosh.1
+++ b/docs/slosh.1
@@ -27,6 +27,8 @@ slosh \- a terminal multiplexer
 .br
 .B slosh \-\-dump\-config
 .br
+.B slosh \-\-dump\-theme
+.br
 .B slosh \-\-headless
 |
 .B \-\-script
@@ -120,6 +122,25 @@ The values are the defaults, not the ones currently in effect:
 this is the file to begin from, and
 .B \-\-check
 is the one that reads yours back.
+Colour is the exception: it prints the
+.B theme_name
+in force and the colours a configuration overrides by hand, not the
+resolved palette, so a dumped configuration keeps following its theme.
+.RE
+.TP
+.B \-\-dump\-theme
+Print the palette in force as a theme file: every colour the
+compositor draws, derivations resolved.
+.RS
+.PP
+.EX
+slosh \-\-dump\-theme > ~/.config/slosh/themes/mine.kdl
+.EE
+.PP
+starts a theme from the session in front of you rather than from an
+empty file; name it with
+.B theme_name
+to wear it.
 .RE
 .TP
 .B \-\-headless
diff --git a/docs/slosh.5 b/docs/slosh.5
index 70cfa08..21315e7 100644
--- a/docs/slosh.5
+++ b/docs/slosh.5
@@ -302,20 +302,52 @@ Unset, the workspaces feature is dormant.
 A layout applied to projects that do not carry their own
 .IR slosh.layout .
 .SH THEME
-.B theme { }
-names every colour the compositor draws (frames, titles, tabs,
-buttons, modals, toasts), each its own entry, 48 of them, so one can
-change without dragging thirty others along.
+A theme is a file of colours in a directory, named rather than pasted:
 .PP
 .EX
-include "~/.config/slosh/themes/phosphor.kdl"
+theme_name "phosphor"
 theme { frame_focus "#00ff88" }   // ...but that one colour is mine
 .EE
+.TP
+.BI theme_name\  name
+The theme to wear:
+.IR name .kdl
+from the theme directory, applied before the rest of the file, so a
+.B theme { }
+block beside it wins.
+A name, not a path \(em use
+.B include
+for a file somewhere else.
+Unset, the compiled\-in palette stands.
+.TP
+.BI theme_dir\  path
+Where those files live.
+Unset, it is
+.I themes/
+beside the configuration file, and then
+.IR PREFIX/share/slosh/themes/ ,
+so a shipped theme is nameable without being copied and one of yours
+with the same name shadows it.
 .PP
-.B slosh \-\-dump\-config
-prints the full list with the compiled-in values; ready-made themes
-ship under
-.IR PREFIX/share/slosh/themes/ .
+.B theme { }
+names every colour the compositor draws (frames, titles, tabs,
+buttons, modals, toasts), each its own entry, so one can change without
+dragging thirty others along.
+A theme file is a configuration containing one of those blocks, which
+is why
+.B slosh \-\-check
+lints one and why saving it reloads the session.
+.PP
+The theme can also be changed while the session runs, over the control
+socket:
+.B \(aq{"cmd":"theme"}\(aq
+lists what is installed and what is worn,
+.B \(aq{"cmd":"theme","name":"amber"}\(aq
+switches now, and
+.B "save":true
+with it writes the
+.B theme_name
+line into the configuration so the switch outlives the session.
 .SH SHADERS
 A shader is a colour pass over a pane's cells: foreground, background,
 attributes, never the text, because rewriting text would desync
@@ -488,9 +520,16 @@ for the full search order).
 .TP
 .I PREFIX/share/slosh/
 The annotated default configuration and an example layout, plus the
-shipped themes, chrome presets and shader presets, each a file to
-copy or
+chrome and shader presets, each a file to copy or
 .BR include .
+.TP
+.I PREFIX/share/slosh/themes/
+The shipped themes, read by name: see
+.BR theme_name .
+.TP
+.I ~/.config/slosh/themes/
+Yours, searched first, so a file here replaces a shipped theme of the
+same name.
 .SH SEE ALSO
 .BR slosh (1)
 .PP