companion: spec for blushing at a listed wallpaper

She turns to the wallpaper with the existing watch back view and blushes
with blush3, when the workspace in front of her is empty and the
wallpaper on her monitor is on a plain text list. The list is toggled
from the wallpaper picker and its path set on the companion page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 73 insertions, 0 deletions

diff --git a/docs/superpowers/specs/2026-10-23-companion-blush-design.md b/docs/superpowers/specs/2026-10-23-companion-blush-design.md
new file mode 100644
index 0000000..06d2370
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-23-companion-blush-design.md
@@ -0,0 +1,73 @@
+# Companion: blushing at a wallpaper
+
+She turns to look at the wallpaper behind her and blushes, for the
+wallpapers on a list, when the workspace in front of her is empty enough
+for her to see it.
+
+## Trigger
+
+Checked at two moments, in `Companion.qml`:
+
+- the focused workspace changes or loses a window (`workspacev2`,
+  `closewindow`), so switching to an empty workspace or closing its last
+  window counts;
+- she appears: shown (SUPER+\ or the settings switch), back from a remap
+  after another layer opened, or moved to another monitor with the focus.
+
+It fires when all three hold:
+
+- the focused workspace has no windows (`lastIpcObject.windows === 0`,
+  after `Hyprland.refreshToplevels()`);
+- the wallpaper on her monitor is on the list;
+- at least 3 minutes since the last blush (`T.blushCooldown`).
+
+Her monitor's wallpaper: wallp's `wallp.conf` maps `OUTPUT_H` and
+`OUTPUT_V` to connectors, and `Wallpapers.currentH`/`currentV` say what is
+on each. The connector names are read from `wallp.conf`, not hardcoded. A
+monitor matching neither has no wallpaper and never fires.
+
+## Reaction
+
+A new state in `Mood.js`, `admire`, stamped by `admireAt`:
+
+| since `admireAt` | frame |
+| --- | --- |
+| 0 to 1.5 s (`T.admireLook`) | `watch`, the back view: she turns to the wallpaper |
+| 1.5 to 4.5 s (`T.admireBlush`) | `blush3` |
+
+`watch` and `blush3` exist in both outfits, so no new art is generated.
+
+Priority: below destruct, scorched, dodge, shoved, listen, think, wave and
+clicks; above mock, watch (typing), stretch, muse and idle. A click during
+it wins, as it does over everything below it now.
+
+A line from a `wallpaper` set in `Lines.js` as the blush starts, under the
+usual 30 s line cooldown.
+
+## The list
+
+A plain text file: one absolute path per line, blank lines and lines
+starting with `#` skipped. Paths compare exactly with what wallp writes to
+`wall_h`/`wall_v`.
+
+- Default path `~/.config/keystone/companion-blush.txt`; a missing file is
+  an empty list.
+- The path is `Prefs.companionBlushFile`, with a text field on Settings >
+  Desktop > Companion (`desktop/modules/companion/`).
+- Watched with a `FileView`, so a hand edit applies live.
+- The wallpaper picker (`WallpaperTab.qml`) draws a heart toggle on each
+  thumbnail, filled when the path is listed. Toggling rewrites the file
+  through a `Process` running `cat > <file>`, because
+  `FileView.setText("")` on an emptied list writes no file (AGENTS.md).
+  Comments in the file are kept on rewrite; only the toggled path's line is
+  added or removed.
+
+The parsed list lives in one place both the companion and the picker read,
+a small singleton in `desktop/companion/`.
+
+## Check
+
+`test_mood.js` gains: the `watch` then `blush3` sequence and its end, the
+3 minute cooldown, a click winning over it, and it winning over typing.
+The trigger is checked by hand: an empty workspace with a listed
+wallpaper, a non-empty one, an unlisted wallpaper, each monitor.