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):

{
  "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.