valw/docs/superpowers/specs/2026-10-03-valw-theme-design.md

# valw theme round: the paint shader, overview backdrop, window picker (design)

Date: 2026-10-03
Status: approved in brainstorming (after the throwaway `valw-lab` spike), pending written-spec review
Builds on: every phase on `main`; zoom's EGL/GLES renderer (`src/zoom/gl.rs`)

## 1. Goal

Give valw a theme of its own: a Balatro-like liquid-paint background,
written from scratch as a shader, coloured from the user's theme, a
wallpaper or a window. Three uses:

- **T1** A shared theme module (shader, palettes); the region overlay's
  dark dim takes the theme's colour (no shader there: the user must see
  what they select).
- **T2** `valw backdrop`: the shader, calm and slow, behind niri's overview,
  coloured from the wallpaper (replacing Noctalia's blurred backdrop).
- **T3** An Alt+Tab-style window picker (`valw window` from now on): cards
  for every window over the shader, the shader coloured from the selected
  window's icon; Enter or a click captures that window.

### Out of scope

- Live window thumbnails in the picker: niri 26.04 gives clients no way to
  read a window's pixels except `screenshot-window`, which also sets the
  clipboard and shows a notification every time. Recorded as a research
  item; cards show icons until then.
- The shader on the toolbar, zoom or editor (possible later on the same
  module).

## 2. The paint shader

The spike's shader, cleaned up (our own code, not Balatro's):

- Two octaves of domain warping (six sine-warp iterations each, a fixed
  rotation between them), banded into a 3-colour palette with soft edges,
  dark rims, glossy streaks and a soft vignette.
- Uniforms: time, resolution, `motion` (0 = flow, 1 = swirl around the
  centre), `speed`, `scale` (blob size), palette `base`, `body`,
  `highlight`.
- Lives in `src/theme/paint.frag` and is drawn by a renderer shared with
  zoom's GL code (EGL + glow; no Vulkan).

## 3. Palettes

`theme::Palette { base, body, highlight }` (linear 0–1 RGB), from:

1. **Noctalia's theme**: `noctalia msg color-scheme-get` and
   `theme-mode-get`; for a `community` scheme the palette file
   `$XDG_STATE_HOME/noctalia/community-palettes/<id>.json` at the current
   mode: base = `mSurface`, body = `mSecondary`, highlight = `mPrimary`
   (accent `mTertiary` kept for later). Other sources (builtin,
   wallpaper, custom) fall back to (3) until their files are mapped.
2. **An image** (a wallpaper, an icon): dominant colours by coarse
   bucketing of a downscaled copy; the three most frequent distinct
   colours (ignoring transparent and near-grey pixels for icons), sorted
   dark → light.
3. **A built-in default** (dark grey-blue), when Noctalia isn't there or
   anything above fails (logged at debug level, never an error).

## 4. T1: themed region dim

The overlay outside the selection becomes the frozen screen blended 55 %
towards the theme's `base` colour (today: darkened to 60 %), so it stays
see-through. Computed once per output before the overlay appears (no cost
per frame).

## 5. T2: `valw backdrop`

- A long-running process: one background-layer surface per output
  (namespace `valw-backdrop`, no keyboard, empty input region), drawing
  the shader with `motion = flow` at a slow speed, coloured from that
  output's wallpaper (`noctalia msg wallpaper-get <connector>`, palette
  source 2).
- Draws only on frame callbacks, so it costs nothing while niri doesn't
  show it. When frames resume after more than 2 s, it re-reads the
  wallpaper (a changed wallpaper changes the colours, easing over 1 s).
- Outputs coming and going are followed; a second `valw backdrop` exits
  at once (a lock, like the preview host's).
- Wiring (in copland, documented in the README): `spawn-at-startup "valw"
  "backdrop"`, niri `layer-rule { match namespace="^valw-backdrop$";
  place-within-backdrop true; }`, Noctalia `[backdrop] enabled = false`.

## 6. T3: the window picker

- `valw window` now opens the picker; the click-a-window mode stays as
  `valw window --pick` (and Space in region mode keeps using it).
- A full-screen overlay layer surface on the focused output (exclusive
  keyboard): the shader full screen, and over it a centred row (wrapping
  to more rows when needed) of cards for every window, most recently
  focused first (niri's `focus_timestamp`), the focused window's card
  selected.
- A card: a rounded translucent panel, the app icon (96 logical px), the
  window title (one line, ellipsised) and the app name below. The
  selected card is larger (110 %), brighter, with a 2 px light border.
- Keys: Tab / → / ↓ next, Shift+Tab / ← / ↑ previous, Enter capture,
  Esc cancel (exit 3). Mouse: hover selects, a click captures, a click
  outside the cards cancels.
- The shader's motion alternates per run (swirl, flow, swirl, …; the last
  one is remembered in `$XDG_STATE_HOME/valw/picker`), and stays fixed
  while the picker is open. Its colours come from the selected window's
  icon (palette source 2) and ease to the next card's over 300 ms.
- Icons: the window's `app_id` → its `.desktop` file (`$XDG_DATA_DIRS`
  applications, `StartupWMClass` or file name) → `Icon=` → the icon
  theme from `~/.config/gtk-3.0/settings.ini` (`gtk-icon-theme-name`),
  its `Inherits`, then `hicolor`; SVGs rendered with `resvg`. No icon: a
  rounded square with the app name's initial.
- Capturing: the picker closes (surface destroyed, flushed and
  round-tripped), then the Phase 3 path (`niri screenshot-window --id`),
  shadow, sound, preview, clipboard as usual.

## 7. Structure

| File | Role |
|---|---|
| `src/theme/mod.rs` | `Palette`, sources (Noctalia, image, default) |
| `src/theme/paint.frag`, `src/theme/gl.rs` | the shader and its renderer (shared EGL setup with `zoom::gl`) |
| `src/render.rs`, `src/region.rs` | themed dim |
| `src/backdrop.rs` | `valw backdrop` |
| `src/picker/{mod,layout,icons}.rs` | the picker, card layout, icon lookup |
| `src/main.rs` | `Command::Backdrop`, `Command::Window { pick }` |
| `src/niri.rs` | `windows()` (all windows with focus timestamps) |
| `README.md` | backdrop wiring |

New dependency: `resvg` (SVG icons; built on tiny-skia).

## 8. Testing

Unit tests (`cargo nextest`):
- palettes: Noctalia palette file parsing (light and dark, missing keys →
  default), image palette (dark → light order, transparent and grey
  pixels ignored for icons), default.
- themed dim: a pixel is blended towards `base` by the right amount.
- picker layout: card positions for 1, 5 and 20 windows on 1366×768 and
  1920×1080 (rows wrap, centred, selected card scaled), hit-testing,
  keyboard navigation wrapping, MRU order from focus timestamps.
- picker motion alternation from the state file (missing/broken file →
  swirl).
- icon lookup against a fake data dir (desktop file by name and by
  `StartupWMClass`, theme inheritance, hicolor fallback, SVG and PNG).
- backdrop: the "resume after a pause" rule and colour easing.

Manual checks go to the theme section of `docs/test-checklist.md`
(including how it feels on the HD 4000).

## 9. Definition of done

`cargo clippy -- -D warnings`, `cargo fmt --check`, `cargo nextest run`
and `nix flake check` pass; README and checklist updated; copland wiring
done with the user's approval.