# TANINUX → eww: Panel & Dock — Settings-Vertrag (Handover)

**Für die TANINUX-Instanz, die die „Panel & Dock"-Seite baut.** Analog zur
Akzent-Kette: **TANINUX schreibt EINE Config-Datei, eww konsumiert sie.** Die
eww-Seite (Variablen, `:style`/`:visible`, Watcher) ist **bereits gebaut** — du
brauchst nur die Datei zu schreiben.

Gegenstücke: `eww-accent-integration.md` (Akzent), `eww-integration.md` (Gesamtvertrag).

---

## 1. Wo die Werte liegen

**Datei:** `~/.local/share/taninux/panel.json`
(`$XDG_DATA_HOME/taninux/panel.json`, Fallback `~/.local/share/...`) — JSON,
**eine** Datei, neben `gui.json`. Existiert mit Defaults; eww seedet sie zur Not.

```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
    }
  }
}
```

---

## 2. Die Knöpfe (Keys, Typ, erlaubte Werte)

| Key                  | Typ            | Werte / Range            | Wirkung in eww                                  | Live? |
|----------------------|----------------|--------------------------|-------------------------------------------------|-------|
| `dock.autohide`      | bool           | `true` / `false`         | `false` = Dock immer sichtbar; `true` = Hover-Trigger | live  |
| `dock.icon_size`     | int            | **24 – 64** (px)         | Icon-Größe im Dock (`:style min-width/height`)  | live  |
| `dock.hide_delay`    | number         | **0.2 – 5.0** (Sekunden) | Nachhall, bis das Dock nach Verlassen schließt  | next-hide |
| `bar.clock_format`   | string         | strftime (z.B. `%H:%M`)  | Format der Uhr in der Bar-Mitte                 | ≤10 s |
| `bar.modules`        | object<bool>   | Keys: `music sys updates net bt vol` | Welche Rechts-Module die Bar zeigt   | live  |
| `updates.include_aur`| bool           | `true`/`false` (Default false) | AUR im Update-Scope (Zähler+Liste). Opt-in, braucht paru | poll |

- **`updates.include_aur`** (Top-Level-Sektion `updates`): TANINUX-Hub macht AUR
  zum Opt-in (Default Repo+Flatpak). `scripts/updates.sh` soll diesen Key lesen
  und nur dann `paru -Qua` mitzählen/-listen. JSON-Schema der Liste bleibt
  `[{name, old, new}]` (gern + `src`). Beispiel-Lesen:
  `inc=$(jq -r '.updates.include_aur // false' "$PANEL_JSON")`.
- **`bar.modules`** ist ein Objekt `{ "<modul>": true/false }` (nicht Liste) —
  fehlt ein Key, gilt er als sichtbar. Module: `music` (Now-Playing-Mini),
  `sys` (CPU/RAM), `updates` (Update-Zähler), `net`, `bt`, `vol`.
- Clamping macht eww defensiv (icon_size 24–64, ungültiges → Default). Trotzdem
  bitte in der GUI validieren (Spin 24–64, Slider 0.2–5.0).

**Noch nicht im v1 (bewusst):** `dock.position` (left/bottom/right) und feste
Größen der Bar/Dock-Fenster. Die brauchen `eww reload` + Geometrie-Neubau
(Orientierungswechsel bei bottom). Sag Bescheid, wenn du das willst — dann
erweitere ich die eww-Seite und dieses Doc; bis dahin nicht in der GUI anbieten.

---

## 3. Wie man anwendet

Du schreibst `panel.json` — **mehr nicht**. eww zieht nach, auf zwei Wegen:

1. **Automatisch:** ein Watcher (`scripts/panelcfg.sh watch`, läuft aus
   `launch.sh`) pollt die Datei alle 2 s und wendet Änderungen an.
2. **Sofort (optional, empfohlen für „Apply"):** nach dem Schreiben einmal
   ```
   ~/eww/scripts/panelcfg.sh apply
   ```
   feuern — dann greift es ohne die 2-s-Latenz. (Best-effort, schadet nie.)

**Kein `eww reload` nötig** für die v1-Knöpfe. Intern macht `panelcfg.sh`:
`eww update cfg-icon-size=… cfg-modules=…`, schaltet Autohide imperativ, und
`clock_format`/`hide_delay` werden on-demand gelesen. (Du musst die
eww-Variablennamen **nicht** kennen — nur `panel.json` schreiben.)

---

## 4. Die Grenze — wer schreibt was

- **`panel.json` gehört dir (TANINUX).** Schreib es frei. eww liest es nur.
- **Gepinnte Dock-Apps** liegen NICHT in `panel.json`, sondern in
  `~/.config/eww/dock-pins` — eine simple Zeilen-Datei, Format **`exec|class|icon`**:
  ```
  librewolf|librewolf|librewolf
  kitty|kitty|kitty
  code|Code|code-oss
  ```
  - `exec` = Startbefehl, `class` = Fensterklasse (app_id/WM_CLASS), `icon` =
    Icon-Name (Papirus). eww spiegelt Änderungen automatisch (Poll alle 2 s).
  - **Die Zeilen-REIHENFOLGE = die Dock-Reihenfolge.** → **Drag & Drop bitte hier
    bauen:** Die „Dock"-Gruppe zeigt die gepinnten Apps als ziehbare GTK-Liste;
    beim Loslassen schreibst du `dock-pins` in der neuen Reihenfolge neu. eww
    sortiert das Dock in ≤2 s nach. Echtes DnD im eww-Dock selbst geht nicht
    (eww/GTK3 hat keine Drag-Primitiven) — deshalb gehört das in deine GTK-Seite.
    (eww bietet zusätzlich „Move up/Move down" im Dock-Rechtsklick als
    Schnell-Option — die schreibt dieselbe Datei.)
  - **Du darfst diese Datei direkt lesen UND schreiben** (z.B. die Pin-Liste in
    der GUI verwalten). eww mutiert sie auch selbst (Dock-Rechtsklick →
    Pin/Unpin). Zwei-Wege ist ok, weil das Format trivial und idempotent ist —
    schreib die ganze Datei neu, eww liest sie beim nächsten Poll.
  - Falls du lieber Befehle feuerst statt zu schreiben:
    `~/eww/scripts/dock.sh pin <class>` / `unpin <class>`.
- **`~/eww/**` (yuck/scss/andere scripts)** ist eww-intern. Für *Settings*
  brauchst du das nie anzufassen — alles läuft über `panel.json` + `dock-pins`.

### Darfst du eww trotzdem direkt anfassen?
Ja — für *Code/Feature*-Arbeit an der Bar selbst (neue Widgets, Layout) ist es
EIN Projekt, kein Tabu. **Einzige harte Regel: nie zwei Editoren gleichzeitig
auf derselben Datei** (genau das hat beim Hyprland→Sway-Umbau Chaos gemacht).
Für *Settings* aber gilt: über `panel.json` gehen, nicht eww hand-editieren —
sonst ist jede GUI-Änderung ein yuck-Edit (brittle + Race-Gefahr).

---

## Status (gebaut & getestet)

- ✅ `panel.json` (Default vorhanden) + `scripts/panelcfg.sh` (apply/watch/get).
- ✅ `dock.icon_size` live (24–64, getestet 42↔56), `bar.modules` live,
  `dock.autohide` imperativ, `bar.clock_format` via `scripts/clock.sh`,
  `dock.hide_delay` aus der JSON gelesen.
- ✅ Watcher in `launch.sh` eingetragen.
- ⏳ `dock.position`/Fenstergrößen = Reload-Thema, auf Anfrage.

Damit kannst du `core/panel.py` (Read/Write `panel.json` + optional `dock-pins`,
Apply = Datei schreiben + `panelcfg.sh apply`) und die GTK-Seite „Panel & Dock"
(Gruppen *Top bar* / *Dock*) direkt bauen.
