# CLAUDE.md

Guidance for AI agents working in this repo.

## What this is

`wallp` — a single bash script that sets and restores wallpapers on a fixed
two-screen wayland (sway/hyprland) setup. It merges two older scripts
(`multiwal.sh` interactive setter, `qar-lastwall.sh` restorer). Uses `swaybg` to
paint wallpapers, `qarma` for GUI selection, `wal` (pywal) for the color theme.

Logical screens are `H` (horizontal) and `V` (vertical), mapped to physical
outputs via config (`OUTPUT_H`/`OUTPUT_V`).

## Layout

- `wallp` — the whole program (one bash file, ~320 lines).
- `tests/wallp.bats` — bats test suite (the only tests).
- `wallp.conf.example` — sample config.
- `docs/superpowers/specs/` — design spec.
- `docs/superpowers/plans/` — implementation plan.

## Build / test

No build step. Run the suite:

```bash
bats tests/wallp.bats
```

Requires `bats` (1.5.0 known good). Tests run hermetically: `setup()` creates a
temp `$HOME`, stubs `swaybg`/`wal`/`qarma`/`notify-send`/`pkill`/`kill` on `PATH`
(each logs its call to `$HOME/calls.log` and exits 0), then `source`s `wallp`.
The sourcing guard at EOF (`[ "${BASH_SOURCE[0]}" = "$0" ]`) keeps `main` from
running on source — **do not remove it.**

Syntax check: `bash -n wallp`.

## Development rules

- **TDD.** Every change: write the failing bats test first, confirm it fails,
  implement, confirm green, commit. Functions go ABOVE `main()`.
- **Test conventions:** use `run fn` when asserting on `$status`/`$output`; call
  the function directly when asserting on globals (`CONF_*`, `SET_*`) or
  filesystem side effects, since `run` executes in a subshell.
- **Pure logic is unit-testable** (conf parse, arg parse, tilde expansion, output
  mapping, theme resolution). Side-effecting bits (`swaybg`, `wal`, `qarma`) are
  isolated in thin functions and exercised via the PATH stubs.
- `set -u` is on. Empty-array expansion `"${set_args[@]}"` is safe on bash ≥ 4.4
  (this host is fine). Guard env vars with `${VAR:-}`.
- Quote all paths (wallpaper filenames may contain spaces).

## Critical gotchas

- **Install is a COPY, not a symlink.** The live binary is `~/bin/wallp`, copied
  from this repo. After editing repo `wallp`, re-copy:
  `cp /home/danix/Programming/GIT/wallp/wallp ~/bin/wallp`
  Otherwise hypr autostart/keybind run the stale version.
- **qarma `--list` needs `--radiolist --print-column=2`.** A plain `--list`
  prints nothing on selection (bug that shipped once). `qarma_select` depends on
  these flags; a regression test guards it.
- **qarma `--info` collapses whitespace.** Newlines and runs of spaces are eaten
  by the GTK label. `show_help`'s markup uses `<br>` for line breaks and `&#160;`
  (non-breaking space) for column padding — NOT `\n` or literal spaces. Pango has
  no `<br>`, but qarma preprocesses it into a newline. `--width=600` stops the
  description column from wrapping (GTK still enforces a min dialog width, so the
  window looks wide). The stdout branch keeps plain text; a test asserts no
  markup tags leak there.
- **Selective kill.** `apply_output` kills only the changed output's swaybg PID
  (tracked in `~/.cache/wallp/{H,V}.pid`). Updating one screen must never blank
  the other — there's a test for this; keep it green.
- **`load_conf` return codes:** 0 ok, 1 invalid (missing required key), 10
  bootstrapped (template just written → caller exits 0, no wallpaper change).
- **Persistence is wallp-owned**, under `~/.config/wallp/` (`wall_h`, `wall_v`,
  `theme`). `~/.cache/wal/wpaper` symlink is still maintained (rofi reads it).
  `~/bin/wal.sh` was trimmed to dunst+kitty glue only; it no longer touches
  wallpaper pointers.

## External integration (outside this repo)

- `~/bin/wal.sh` — wal's `-o` hook; dunst + kitty theming only now.
- `~/.config/hypr/sections/autostart.lua` → `wallp --restore`.
- `~/.config/hypr/sections/keybindings.lua` → `wallp --set` (mainMod+Return).
- Old `~/bin/multiwal.sh` + `qar-lastwall.sh` kept as fallback, unreferenced.

## Commits

Pre-commit gitleaks hook prints ASCII art — normal; the commit succeeds when it
reports "no leaks found".