taninux/docs/eww-integration.md

# eww ↔ TANINUX — Integrations-Vertrag (Handover)

**Zweck:** Ab jetzt werden die **eww-Bar** (`~/eww`, symlinked nach `~/.config/eww`)
und die **TANINUX-Settings-App** *zusammen gedacht*. Dieses Dokument ist der
Vertrag: was über welche Datei fließt, wer was besitzt, und was man beim Ändern
der einen Seite auf der anderen beachten muss.

Gegenstück: `docs/eww-accent-integration.md` (der ursprüngliche Accent-Handoff
TANINUX → eww). Dieses Dokument hier ist die **vollständige, gelebte** Sicht.

---

## TL;DR — die Schnittstellen

| # | Thema          | Quelle der Wahrheit (TANINUX schreibt)              | eww liest / reagiert via                         |
|---|----------------|-----------------------------------------------------|--------------------------------------------------|
| 1 | **Akzentfarbe**| `~/.local/share/taninux/gui.json` → `accent_hex`    | `~/eww/scripts/accent.sh watch` → setzt `$accent-dim` in `eww.scss`, `eww reload` |
| 2 | **Hell/Dunkel**| `gsettings org.gnome.desktop.interface color-scheme`| `~/eww/scripts/colorscheme.sh get` (defpoll 2 s) → `.light`-Klasse an den Panels |
| 3 | **Compositor** | *(unabhängig erkannt — keine Datei)*                | `~/eww/scripts/wm.sh` erkennt `hyprland`/`sway` selbst |
| 4 | **Settings öffnen** | *(App ist das Ziel)*                           | eww Control-Center-Zahnrad → `~/eww/scripts/settings.sh` → `taninux-gtk` |

Kurz: **Akzent läuft über die JSON, Hell/Dunkel über gsettings, Compositor
erkennt jede Seite selbst.** Diese drei Achsen müssen konsistent bleiben.

---

## 1. Akzentfarbe — `gui.json` → eww

- **TANINUX schreibt** bei jeder Akzent-Änderung `~/.local/share/taninux/gui.json`,
  Feld `accent_hex` (fertiger Hex, z. B. `#8f8aac`). Schema siehe
  `eww-accent-integration.md`.
- **eww** hat einen Watcher `scripts/accent.sh watch` (gestartet aus
  `~/eww/launch.sh`), der `gui.json` alle 2 s auf mtime-Änderung pollt und bei
  Änderung:
  - `accent_hex` liest (Fallback `#8f8aac`, wenn Datei/Feld fehlt/ungültig),
  - damit **nur die eine Zeile** `$accent-dim:` in `~/eww/eww.scss` neu schreibt,
  - `eww reload` auslöst.
- In der SCSS leiten sich **alle** Akzent-Werte aus `$accent-dim` ab:
  ```scss
  $accent-dim: #8f8aac;                 // = accent_hex (von accent.sh verwaltet)
  $accent:     lighten($accent-dim, 8%);
  $accent-08:  rgba($accent, 0.08);
  $accent-14:  rgba($accent, 0.14);
  $accent-22:  rgba($accent, 0.22);
  ```
- **Verifiziert:** Akzent in der App auf z. B. `take`/grün stellen → Bar/Panels/
  Dock tinten innerhalb ~2 s nach.

**Wenn TANINUX hier etwas ändert:** Solange `accent_hex` ein `#rrggbb` bleibt,
muss eww **nichts** angepasst werden. Neue Akzent-Keys (über die 5 Fuji-Töne
hinaus) brauchen nur einen gültigen Hex — eww ist farbagnostisch.

---

## 2. Hell/Dunkel — gsettings (NICHT die JSON)

**Klare Abgrenzung:** Hell/Dunkel läuft **global über
`gsettings org.gnome.desktop.interface color-scheme`** (`prefer-dark` /
`prefer-light` / `default`). Das `color_scheme`-Feld in `gui.json` ist für eww
**nur informativ und wird ignoriert.**

- **TANINUX** setzt beim Umschalten die gsettings-Keys (`gui/desktop.py`,
  `gsettings set …`). Das ist der globale Standard und greift für alle GTK-Apps.
- **eww** pollt `scripts/colorscheme.sh get` (defpoll, 2 s) → `light`/`dark` und
  hängt eine `.light`-Klasse an alle Panels/Dock (Bar bleibt immer dunkel).
  Hell = „Shibui"-Weiß-Palette in `eww.scss` (`$bg-l`, `$fg-l`, …).
- **Wichtig (Lesson learned):** Ein `gsettings monitor`-Deflisten **stirbt** in
  eww's Spawn-Umgebung — deshalb **defpoll**, nicht monitor. Und: ein
  `deflisten→defpoll`-Wechsel braucht einen **vollen eww-Neustart**
  (`launch.sh`), ein `eww reload` reicht nicht.

**Vertrag:** Damit eww dem App-Umschalter folgt, **muss TANINUX die gsettings
tatsächlich setzen** (nicht nur `gui.json.color_scheme`). Tut es das nicht,
bleibt eww auf dem alten Modus — das ist dann ein TANINUX-Bug, kein eww-Bug.
(Beobachtet: einmal stand `gui.json=light`, aber `gsettings=prefer-dark` →
eww blieb korrekterweise dunkel.)

---

## 3. Compositor-Erkennung — beide Seiten, unabhängig

Beide Apps müssen auf **Hyprland UND Sway/SwayFX** laufen. Es gibt **keine
geteilte Datei** dafür — jede Seite erkennt selbst:

- **TANINUX:** eigene Compositor-Erkennung (von dir gebaut).
- **eww:** `~/eww/scripts/wm.sh` — eine sourcebare Abstraktion. Erkennt über
  `$HYPRLAND_INSTANCE_SIGNATURE` / `$SWAYSOCK` / `pgrep` und setzt `$WM`.
  Bietet einheitliche Funktionen, die alle eww-Scripts nutzen:

  | Funktion              | Hyprland                              | Sway / SwayFX                         |
  |-----------------------|---------------------------------------|---------------------------------------|
  | `wm_clients`          | `hyprctl clients -j`                  | `swaymsg -t get_tree`                 |
  | `wm_focus <id>`       | `hl.dsp.focus({window="address:…"})`  | `[con_id=…] focus`                    |
  | `wm_goto_ws` / `cycle`| `hl.dsp.focus({workspace=…})`         | `workspace number …`                  |
  | `wm_cursor_y`         | `hyprctl cursorpos`                   | *(kein Cursor-IPC → Menü zentriert)*  |
  | `wm_outputs`          | `hyprctl monitors`                    | `swaymsg -t get_outputs`              |
  | `wm_lock` / `wm_exit` | `hyprlock` / `hl.dsp.exit()`          | `swaylock -f` / `swaymsg exit`        |
  | `wm_blur_layer`       | `hyprctl keyword layerrule blur,…`    | SwayFX `layer_effects … blur enable`  |

  Genutzt von: `dock.sh`, `power.sh`, `ws.sh`, `workspaces.sh`, `launch.sh`.

  **Hyprland-Eigenheit:** Dispatch läuft auf diesem Setup über die **Lua-API**
  (`hyprctl dispatch "hl.dsp.…()"`), nicht über die klassische Textsyntax.
  `hl.dsp.focus` springt automatisch auf den Workspace des Fensters.

**Konsistenz-Regel:** Wenn TANINUX seine Compositor-Erkennung ändert (neue
Compositor, andere Detektion), sollte `wm.sh` dieselbe Logik spiegeln, damit
beide Apps nie auseinanderlaufen. Idealerweise teilt man sich später *eine*
Detektionsquelle — aktuell bewusst getrennt (keine harte Kopplung).

---

## 4. eww startet die Settings-App

Das **Zahnrad oben rechts im Control Center** öffnet die TANINUX-GUI:
`~/eww/scripts/settings.sh` → `cd ~/projects/taninux && setsid -f env
PYTHONPATH=src /usr/bin/python -m taninux.gui`.

- **System-Python**, nicht das venv — das venv hat **kein `gi`/PyGObject**
  (Systempaket). Entry point laut `pyproject.toml`: `taninux-gtk =
  taninux.gui.app:main`.
- Single-Instance über die GTK-App-ID `ch.gabrielevarano.Taninux` → zweiter
  Klick fokussiert nur.

**Wenn TANINUX die Startweise ändert** (z. B. richtig installiertes
`taninux-gtk` mit `gi` im venv, oder ein `.desktop`/Binary auf dem PATH):
`scripts/settings.sh` entsprechend anpassen — am besten auf `taninux-gtk`,
sobald es ohne `PYTHONPATH=src`-Hack läuft.

---

## Datei- & Besitz-Karte

| Pfad                                         | Besitzer  | Rolle |
|----------------------------------------------|-----------|-------|
| `~/.local/share/taninux/gui.json`            | TANINUX   | Akzent (`accent_hex`) — eww liest |
| `gsettings …interface color-scheme`          | TANINUX   | Hell/Dunkel global — eww liest |
| `~/.config/gtk-4.0/libadwaita.css`           | TANINUX   | **GTK-App-Akzent** — *nicht* für eww, nicht anfassen |
| `~/eww/**` (yuck, scss, scripts)             | **eww**   | Bar/Panels/Dock — TANINUX fasst das **nie** an |
| `~/eww/scripts/wm.sh`                         | eww       | Compositor-Abstraktion |
| `~/eww/scripts/accent.sh`                     | eww       | gui.json → `$accent-dim` |
| `~/eww/scripts/colorscheme.sh`               | eww       | gsettings → light/dark |
| `~/eww/scripts/settings.sh`                   | eww       | startet TANINUX-GUI |

**Goldene Regel:** TANINUX schreibt **nie** in `~/eww/**`; eww schreibt **nie**
in TANINUX-Dateien (außer es liest `gui.json` und startet die GUI). Die
SCSS-Verdrahtung gehört eww, die Settings-Logik gehört TANINUX.

---

## Checkliste beim Ändern

**TANINUX-Seite ändert Akzent-Format?** → nur prüfen, dass `accent_hex` ein
`#rrggbb` bleibt. Sonst nichts.

**TANINUX-Seite ändert Hell/Dunkel-Mechanik?** → muss weiterhin `gsettings
color-scheme` setzen. eww hängt daran.

**Neuer Compositor unterstützt?** → `wm.sh` um einen `$WM`-Zweig erweitern
(dieselben Funktionen implementieren). Sonst läuft die Bar dort nicht.

**Settings-Startweg ändert sich?** → `~/eww/scripts/settings.sh` anpassen.

---

## Status (Stand dieser Übergabe)

- ✅ Akzent live aus `gui.json` (getestet: ume/violet ↔ take/green).
- ✅ Hell/Dunkel live aus gsettings (Shibui-Hell-Palette, Bar bleibt dunkel).
- ✅ Compositor-Abstraktion `wm.sh` — auf **Hyprland verifiziert**; Sway-Zweige
  implementiert (final unter Sway noch gegenzutesten).
- ✅ Settings-Zahnrad startet `taninux-gtk` (System-Python).
- ⚠️ Für Sway fehlen noch **`swaylock` + `swayidle`** (Pakete installieren).
- ⚠️ SwayFX-Blur fürs Dock: `wm_blur_layer` versucht `layer_effects` live;
  zuverlässiger ist die Regel in der SwayFX-Config (`layer_effects
  "gtk-layer-shell" blur enable`).