sl0ppty: modals get their own surface, and dim what is behind them

Two things wrong with the first one, and both are about it being a modal
rather than a pane that happens to float.

The close button was invisible. It was drawn in the pane button colour on the
finder background, and in the default theme those are the same value --
#45454a on #45454a -- so it only appeared when the pointer landed on it and
the hover colour took over. That is the hazard of borrowing names from
another surface: each one is right, and together they are nothing. A modal is
its own surface now, with its own names (modal_bg, modal_fg, modal_border,
modal_title, modal_button, modal_button_hover), a dark panel a shade lighter
than the dimmed screen, a border in the accent, and a button chosen to be
visible *without* the pointer on it. All six themes set them.

And nothing behind it moved, so it read as another pane rather than as
something in front. There is a scrim now, `modal_scrim` (0..255, 120 by
default), and the pleasing part is that it is not a new mechanism: it is the
shader pass aimed at the screen instead of at a pane. Same dim, same
materialisation of default colours, no special case. It goes down after
everything else is painted and before the modal, so the modal is the only
thing at full brightness -- which is the whole idea, and is asserted rather
than assumed.

The shape is now reusable: modal_frame() draws the box, title, close button
and hit, and returns the rect inside it; draw_scrim() is one line above it.
The next modal is a function call and looks the same as this one.

The finder is deliberately left alone. It is a picker rather than a modal --
it navigates, where a modal here dismisses on any key -- so unifying them
would be making two things one because they are both rectangles.

1 files changed, 23 insertions, 0 deletions

diff --git a/HANDOVER.md b/HANDOVER.md
index bd04ef0..1950872 100644
--- a/HANDOVER.md
+++ b/HANDOVER.md
@@ -216,6 +216,25 @@ no cursor". The graphics stream now opens with DECSC and closes with DECRC,
 and emits nothing at all when there is nothing to say. Any future
 after-the-frame output owes the same debt.
 
+## Modals
+
+`modal_frame()` draws the surface and `draw_scrim()` pushes back what is
+behind it; the cheatsheet is the first thing to use them and is meant to be
+the shape the next one copies. Two things it got wrong first, both worth not
+repeating:
+
+- **it borrowed colours from another surface.** The close button was the pane
+  button colour on the finder background, which are the same value in the
+  default theme, so it was invisible until hovered. A modal is its own
+  surface and now has its own `modal_*` names. When you add a surface, give
+  it names; when you reuse names, check what they resolve to *together*.
+- **the scrim is the shader pass, aimed at the screen.** Nothing about it is
+  special-cased, which is why it dims chrome as happily as contents — but it
+  also means the whole screen's unset colours get materialised through
+  `default_fg`/`default_bg` while a modal is up, so a terminal whose real
+  background differs from the configured one shifts slightly. Documented next
+  to `modal_scrim` rather than hidden.
+
 ## Things left on the table
 
 - **A `reload` keybinding.** The config watcher made it less pressing.
@@ -238,6 +257,10 @@ after-the-frame output owes the same debt.
   pane. Hot-swapping would need every shader reference to be indirected
   through the registry, which is a real change and not obviously worth it.
 - **Per-row shader dispatch** — see the numbers above.
+- **The finder is not a modal** and predates `modal_frame()`. It keeps its own
+  `finder_*` colours and its own box. Moving it over would unify two overlay
+  looks into one; it was left alone because it is a picker rather than a
+  modal — it navigates, and modals here dismiss on any key.
 - **The cell size is not queried, only received.** If a client's terminal
   reports no pixel size in `TIOCGWINSZ`, we keep the 8x16 default rather than
   asking it with `CSI 14 t`/`CSI 16 t`. Doing that properly means the client