Initial commit — TANINUX (camel): management app + distro packaging

- app: GTK System Settings (tsettings) + Software Hub (thub) + TUI - distro/: camel.toml manifest + MANIFEST.md (Arch + [tanin] repo model) - packaging/: taninux, tanin-desktop (niri metapackage), tanin-greet, tanin-libadwaita, tanin-setup - docs/, data/, LICENSE (GPL-3.0-or-later) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-18 20:18:30 +02:00
commit 10b88a67bc
167 changed files with 19624 additions and 0 deletions
@@ -0,0 +1,176 @@
+# 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`).