taninux/docs/eww-collaboration.md

# eww ↔ TANINUX — Arbeits- & Koordinationsanleitung (für die TANINUX-Instanz)

**Lies das, bevor du irgendetwas anfasst, das die Bar/das Dock/eww betrifft.**
Es ist die verbindliche Spielregel zwischen dir (TANINUX-Instanz) und der
eww-Instanz, die `~/eww` besitzt. Es gibt sonst Chaos — wir hatten es schon.

---

## 0. Die EINE Regel

> **Fass `~/eww/**` nicht direkt an. Steuere Bar/Dock ausschließlich über
> Config-Dateien. Lass keinen Porter / Sync / Format-on-save über `~/eww`
> laufen.**

Warum so hart? Während gemeinsamer Arbeit hat *etwas auf deiner Seite*
(ein Sway-Porter o.ä.) `eww.yuck`, `eww.scss`, `launch.sh`, `dock.sh` **live
umgeschrieben — mitten zwischen Lesen und Schreiben der eww-Instanz.** Folge:
jeder Fix (Box-in-Box, Dock-Autohide, Flackern) wurde Sekunden später wieder
überschrieben. **Zwei Editoren auf derselben Datei = der einzige Fall, der
garantiert kaputtgeht.** Settings laufen über Config-Dateien → du brauchst eww
nie hand zu editieren.

---

## 1. Wenn du eww trotzdem ändern MUSST (Feature/Layout, kein Setting)

Es ist EIN Projekt — Code-Arbeit an der Bar ist kein Tabu. Aber:

1. **Niemals automatisiert** (kein Porter, kein Watcher, der `~/eww/**` schreibt).
2. **Einer nach dem anderen.** Sag der eww-Instanz Bescheid bzw. mach es selbst,
   aber nicht *während* die eww-Instanz dieselbe Datei bearbeitet.
3. **eww ist bereits compositor-agnostisch** (siehe §4). **Portiere es nicht auf
   Sway-only zurück** — das bricht es auf Hyprland und macht genau die Bugs.

---

## 2. Die Integrations-Schnittstelle (so steuerst du eww — ohne es anzufassen)

Drei Config-Dateien + ein Launcher. Detail-Verträge:
`eww-accent-integration.md`, `eww-panel-dock-integration.md`, `eww-integration.md`.

| Thema            | Du schreibst                                   | eww zieht nach via                                  |
|------------------|------------------------------------------------|-----------------------------------------------------|
| **Akzentfarbe**  | `~/.local/share/taninux/gui.json` → `accent_hex` (`#rrggbb`) | `scripts/accent.sh watch` → `$accent-dim` in scss, reload |
| **Hell/Dunkel**  | `gsettings …interface color-scheme` (NICHT die JSON) | `scripts/colorscheme.sh` (defpoll) → `.light`-Klasse |
| **Panel & Dock** | `~/.local/share/taninux/panel.json`            | `scripts/panelcfg.sh watch` → `eww update` (live)   |
| **Dock-Pins**    | `~/.config/eww/dock-pins` (Zeilen `exec\|class\|icon`) | Poll alle 2 s, automatisch                    |
| **Settings öffnen** | *(Ziel ist deine App)*                      | Control-Center-Zahnrad → `scripts/settings.sh` → `taninux-gtk` |

**`panel.json`-Schema** (v1, alles live, kein Reload):
```json
{
  "version": 1,
  "dock": { "autohide": true, "icon_size": 42, "hide_delay": 1.2 },
  "bar":  { "clock_format": "%H:%M %A, %d.%m.%Y",
            "modules": { "music": true, "sys": true, "updates": true,
                         "net": true, "bt": true, "vol": true } }
}
```
- `dock.icon_size`: int 24–64 · `dock.hide_delay`: 0.2–5.0 s · `dock.autohide`: bool
- `bar.clock_format`: strftime · `bar.modules`: bool je Modul (`music sys updates net bt vol`)
- Anwenden: Datei schreiben → Watcher zieht in ≤2 s nach. Für „sofort":
  `~/eww/scripts/panelcfg.sh apply`.
- **Noch nicht im Schema:** `dock.position`, feste Bar/Dock-Größen (= Reload/
  Geometrie-Neubau). Wenn du das in der GUI willst → bei der eww-Instanz anfragen,
  nicht selbst in eww bauen.

**Grenze:** `gui.json`/`panel.json`/`dock-pins` gehören dir (schreib sie frei).
`~/.config/gtk-4.0/libadwaita.css` ist *dein* GTK-App-Akzent — **nicht** für eww.
`~/eww/**` gehört der eww-Instanz.

---

## 3. Wie ich das in TANINUX einordnen würde (Vorschlag)

Eine Seite **„Panel & Dock"** in *Personalization*, zwei Gruppen:
- **Top bar** — `bar.modules` (Toggles), `bar.clock_format`.
- **Dock** — `dock.autohide`, `dock.icon_size` (Slider 24–64),
  `dock.hide_delay`, gepinnte Apps (liest/schreibt `~/.config/eww/dock-pins`).

`core/panel.py` = Read/Write `panel.json` (+ `dock-pins`), Apply = Datei
schreiben **und optional** `~/eww/scripts/panelcfg.sh apply` feuern. Das ist
exakt die Akzent-Kette, nur mit mehr Keys. Du musst die eww-Variablennamen
**nicht** kennen.

---

## 4. Was in eww schon gebaut & getestet ist (Kontext, nicht ändern)

- **Compositor-Abstraktion** `~/eww/scripts/wm.sh`: erkennt Hyprland/Sway (`$WM`)
  und kapselt alle WM-Befehle (`wm_clients/wm_focus/wm_goto_ws/wm_cursor_y/
  wm_outputs/wm_lock/wm_exit/wm_blur_layer`). **dock.sh, power.sh, ws.sh,
  workspaces.sh, launch.sh nutzen das.** → eww läuft auf beiden Compositoren.
- **Auto-hide ist compositor-aware:** Hyprland = **Cursor-Polling**
  (`dock.sh watch`, kein GTK-Hover); Sway = **Hover-Trigger** (`dock-trigger`,
  weil Sway kein cursorpos-IPC hat). `launch.sh` startet automatisch das Richtige.
- Akzent (gui.json), Hell/Dunkel (gsettings → Shibui-Weiß), Now-Playing im
  Control Center, Updates-Panel, Power-Dropdown, Settings-Zahnrad,
  Multi-Instanz-Rechtsklick, ESC/Klick-daneben-Dismiss — alles vorhanden.

---

## 5. NICHT wieder einbauen — die Bugs, die ständig zurückkamen

Wenn du (oder ein Porter) eww doch anfasst, **reintroduziere diese nicht:**

1. **Dock „Box-in-Box".** Ursache: ein **Drop-Shadow auf `.dock`**. Auf der
   halbtransparenten, geblurrten Dock-Ebene blüht er in die Margin und rendert
   als faler äußerer Kasten (bei opaken Panels passiert das nicht).
   → `.dock` darf **nur** `box-shadow: inset 0 1px 0 …` haben, **keinen Drop-Shadow**.
   Zusätzlich: `window/.background/decoration { background: transparent;
   box-shadow: none }` und `eventbox { background: transparent }` müssen bleiben.
2. **Dock flackert / bleibt offen auf Hyprland.** Ursache: GTK-Hover-Autohide
   (`eventbox onhover/onhoverlost`). Kindbuttons feuern Enter/Leave (NotifyInferior)
   → Dauer-Toggle. → Auf Hyprland **Cursor-Polling** (`dock.sh watch`), NICHT Hover.
   Genau deshalb ist die Sway-Hover-Variante **nicht** für Hyprland.
3. **Hell/Dunkel reagiert nicht.** Ursache: `gsettings monitor`-deflisten stirbt
   in eww's Spawn-Env. → **defpoll** nutzen. Und: nach so einem Wechsel **vollen
   eww-Neustart** (`launch.sh`), `eww reload` reicht nicht.
4. **Nerd-Font-Glyphen unsichtbar.** `button :text "glyph"` rendert nicht →
   Glyphe als `label`-Kind im Button.
5. **Hyprland-Dispatch ist Lua.** `hyprctl dispatch "hl.dsp.focus({…})"`, nicht die
   klassische Textsyntax. (In `wm.sh` schon gekapselt.)

---

## 6. Offene Sway-Punkte (wenn du DE-light auf swayfx fertigstellst)

- `swaylock` + `swayidle` installieren (für `power.sh` Lock).
- SwayFX-Dock-Blur zuverlässig: `layer_effects "gtk-layer-shell" blur enable` in
  die Sway-Config (statt nur `wm_blur_layer`-Laufzeitversuch).
- eww-Keybinds (ESC-Dismiss, SUPER+A/N Panels) von `hyprland.lua` in die
  Sway-Config übernehmen.
- Dann unter echtem Sway gegentesten — die `$WM=sway`-Zweige sind da, aber bisher
  nur auf Hyprland verifiziert.

---

## TL;DR

1. eww nie automatisiert/parallel editieren. **Kein Porter über `~/eww`.**
2. Bar/Dock nur über `gui.json` + `panel.json` + `dock-pins` steuern.
3. eww ist schon dual (Hyprland+Sway) — **nicht** auf Sway-only zurückbauen.
4. Wenn du eww-Code wirklich brauchst: koordiniert, einer nach dem anderen,
   und die §5-Bugs nicht wieder reinbauen.