diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/superpowers/specs/2026-06-11-wallp-merge-design.md | 85 |
1 files changed, 58 insertions, 27 deletions
diff --git a/docs/superpowers/specs/2026-06-11-wallp-merge-design.md b/docs/superpowers/specs/2026-06-11-wallp-merge-design.md index 5f23772..b1a85b3 100644 --- a/docs/superpowers/specs/2026-06-11-wallp-merge-design.md +++ b/docs/superpowers/specs/2026-06-11-wallp-merge-design.md @@ -80,26 +80,49 @@ An example conf is shipped in the repo (`wallp.conf.example`). ## State Files -Runtime pointers (volatile, in `~/.cache`, reset on reboot): +Persistent state (wallp-owned, `~/.config/wallp/`, survives reboot): -- `~/.cache/wal/wal` — H wallpaper path. Read by pywal and apps. -- `~/.cache/wal/wal2` — V wallpaper path. -- `~/.cache/wal/wpaper` — symlink to current H image (maintained by wallp). +- `~/.config/wallp/wall_h` — H wallpaper path. +- `~/.config/wallp/wall_v` — V wallpaper path. +- `~/.config/wallp/theme` — last-used theme name. +- `~/.config/wallp/wallp.conf` — config (see Config section). -Persistent pointers (survive reboot, in `~/.config`): - -- `~/.config/wal/wal` — H wallpaper path. -- `~/.config/wal/wal2` — V wallpaper path. - -PID tracking (runtime only, meaningless after reboot): +Runtime state (volatile, reset on reboot): +- `~/.cache/wal/wpaper` — symlink to current H image. **Kept** because it has + external consumers (rofi themes under `~/.config/rofi/darknix/*.rasi`). wallp + maintains it. - `~/.cache/wallp/H.pid` — swaybg PID for horizontal output. - `~/.cache/wallp/V.pid` — swaybg PID for vertical output. -wallp writes **all** pointer files directly (cache + config) on set and restore. -This moves persistence out of `wal.sh` and into wallp. `wal.sh` is reduced to its -theme-app glue only (dunst symlink+restart, kitty symlink); it loses the -wal/wal2/wpaper copy logic. `wal.sh` remains the wal `-o` hook for future use. +Dropped (no external consumer; confirmed via grep over `~/bin` and `~/.config`): + +- `~/.cache/wal/wal`, `~/.cache/wal/wal2` — only the replaced scripts wrote + these; nothing else reads them. +- `~/.config/wal/wal`, `~/.config/wal/wal2` — superseded by `~/.config/wallp/`. + +wallp owns all its persistence directly in `~/.config/wallp/`. This moves +persistence out of `wal.sh` and into wallp. `wal.sh` is reduced to its theme-app +glue only (dunst symlink+restart, kitty symlink); it loses the wal/wal2/wpaper +copy logic. `wal.sh` remains the wal `-o` hook for future use. + +Note: `~/.cache/wal/colors.json` is pywal-native (written by `wal` itself, read +by `pywal_sublime.py`); not touched by wallp. + +## Theme Persistence + +The last-used theme is persisted to `~/.config/wallp/theme` and survives reboot. +Conf `THEME` is only the first-run default. Precedence on every action: + +1. `--theme <name>` flag → use it. +2. else persisted `~/.config/wallp/theme` (if present). +3. else conf `THEME`. +4. else built-in `sexy-splurge`. + +Whatever theme is resolved gets persisted to `~/.config/wallp/theme`. This means +once a theme is set it sticks (for both `--set` and `--restore`) until changed +via `--theme`. `--restore` thus brings back the last-used theme, not the conf +default. ## Set Flow @@ -110,13 +133,14 @@ For each chosen output (H and/or V): 2. Selective kill: read `<X>.pid`; if the PID is alive, `kill` it. The other output's swaybg is left untouched. 3. `swaybg -o <OUTPUT> -i <file> -m fill &`; save the new PID to `<X>.pid`. -4. Write the pointer to cache (`wal`/`wal2`) and config (`wal`/`wal2`). +4. Persist the path to `~/.config/wallp/wall_h` (H) or `wall_v` (V). After all chosen outputs are done: -5. Update `~/.cache/wal/wpaper` symlink → current H image. -6. Run `wal --backend colorz -nq --theme <THEME> -o ~/bin/wal.sh`. -7. `notify-send` color-theme update. +5. Update `~/.cache/wal/wpaper` symlink → current H image (for rofi). +6. Resolve theme (see Theme Persistence), persist to `~/.config/wallp/theme`. +7. Run `wal --backend colorz -nq --theme <THEME> -o ~/bin/wal.sh`. +8. `notify-send` color-theme update. qarma selection flow (`--set`, display present, no args): @@ -129,16 +153,17 @@ qarma selection flow (`--set`, display present, no args): For each output H/V: -1. If the persistent pointer (`~/.config/wal/wal` for H, `wal2` for V) exists → - read the path, selective-kill that output's old PID, `swaybg`, save PID, and - sync the pointer to `~/.cache/wal/`. +1. If the persistent pointer (`~/.config/wallp/wall_h` for H, `wall_v` for V) + exists → read the path, selective-kill that output's old PID, `swaybg`, + save PID. 2. If no persistent pointer for that output → use `DEFAULT_H`/`DEFAULT_V` from - conf, write both pointers (cache + config), swaybg, save PID. + conf, persist it (`wall_h`/`wall_v`), swaybg, save PID. After both outputs: 3. Update `wpaper` symlink → H image. -4. Run wal theme + notify (same as set steps 6-7). +4. Resolve theme (persisted theme wins, see Theme Persistence), persist it, + run wal theme + notify (same as set steps 7-8). No display required. Replaces `qar-lastwall.sh`. Intended for session-start autostart. @@ -167,8 +192,10 @@ The script is side-effecting (swaybg, wal, filesystem). Strategy: - Assertions: - Conf-missing path generates the template and changes no wallpaper. - Missing required key hard-errors. - - `--set V=<file>` writes V pointers (cache + config) and leaves `H.pid` + - `--set V=<file>` writes `~/.config/wallp/wall_v` and leaves `H.pid` untouched (partial update does not blank H). + - Theme persistence: `--theme X` writes `~/.config/wallp/theme`; a later + no-flag run resolves X (persisted wins over conf THEME). - Selective kill targets only the changed output's PID. - Restore falls back to `DEFAULT_*` when no persistent pointer exists. - `~` in conf paths expands to `$HOME`. @@ -176,9 +203,13 @@ The script is side-effecting (swaybg, wal, filesystem). Strategy: ## Migration Notes -- `wal.sh` lines 16-27 (wal/wal2/wpaper copy + symlink) move into wallp; remove - them from `wal.sh`, keep dunst + kitty glue. +- `wal.sh` lines 16-27 (wal/wal2/wpaper copy + symlink) — remove the wal/wal2 + copy lines (16,19,22-23) entirely; the `wpaper` symlink moves into wallp. + Keep dunst + kitty glue (lines 7,13). `wal.sh` stays the wal `-o` hook. - Old `qar-lastwall.sh` read `~/.config/wal/*`; old `multiwal.sh` wrote - `~/.cache/wal/*` — this mismatch bug is resolved: wallp writes both. + `~/.cache/wal/*` — mismatch bug resolved: wallp uses a single owned location + `~/.config/wallp/`. - Old default-wallpaper paths had a literal quoted `~` (swaybg would not expand) — fixed via `~`→`$HOME` expansion on conf load. +- `~/.cache/wal/wpaper` retained — consumed by `~/.config/rofi/darknix/*.rasi`. +- `~/.cache/wal/wal` + `wal2` dropped — no external consumer (grep-verified). |