taninux/HANDOVER.md

# TANINUX — Handover (Session 2026-06-22)

Context for a fresh instance. Repo: `~/projects/taninux` (distro codename **camel**,
niri-only GTK4/libadwaita + eww desktop). User: Karim (German; iterates visually;
hates UI jank; blanket perms in `~/projects`). UI strings are **English**.

This session did two things: (A) added packages to the `[tanin]` binary repo,
(B) built a custom **accent-reactive icon theme** to replace Papirus.

---

## A. New packages in the `[tanin]` repo

The `[tanin]` repo is a thin overlay on Arch (own packages + AUR rebuilds),
hosted on the Gitea Arch registry. Build/publish scripts in `packaging/`:
`build-tanin-repo.sh` (no-sudo), `finish-tanin-repo.sh` (sudo: taninux + AUR
rebuilds), `publish-tanin-repo.sh` (upload to Gitea).

Added to the AUR-rebuild list (`build-tanin-repo.sh` + `finish-tanin-repo.sh`):
- `librewolf-bin` — default browser. Also a **hard dep** of `tanin-desktop`.
  ⚠ Security: rebuild + republish on every LibreWolf release, else `pacman -Syu`
  ships a stale (vulnerable) browser.
- `arch-update`, `timeshift` (+ `timeshift-autosnap`), `xdg-terminal-exec` —
  all hard deps of `tanin-desktop` now.
- `paru` — built into the repo but stays **optdepend** (not forced).

Deliberately **rejected**: `papirus-folders` (removed). The other 20 AUR pkgs on
Karim's machine are personal apps/games/emulators/hardware → not base-OS.
`swayfx`+`scenefx0.4` are pulled by `greetd-regreet` (a leftover alt-greeter;
TANINUX uses `tanin-greet`) — candidate for removal, not done.

---

## B. Icon theme: Papirus → `tanin-icons` (the main work)

Karim's decision: Papirus is "too flat"; **Adwaita fits the design**, folders
should follow the Fuji accent. The 5 Fuji accents are deliberately *muted*
(`ume #8f8aac`, `shinkai #8a98ac`, `take #8aac8b`, `chikyu #aca98a`, `beni #ac8a8c`)
— so `papirus-folders` (saturated presets) and native GNOME accent-folders (preset
accents only) both can't match. Hence a custom package.

**New package `packaging/tanin-icons/`:**
- `recolor.py` — generator. Builds 5 thin themes `Tanin-<accent>` that
  `Inherits=Adwaita`, recolouring **only** the folder/place icons. Algorithm:
  HSL shift of the Adwaita blue ramp → keep each stop's **lightness**, swap
  hue+saturation to the accent (preserves folder depth). White emblems untouched
  (saturation gate). **16px PNGs are rasterised via `rsvg-convert`** because
  Adwaita's only fixed-size raster is 16x16 — without an override the inherited
  blue PNG wins at 16px.
- `PKGBUILD` (depends `adwaita-icon-theme`; makedepends `librsvg python`) +
  `tanin-icons.install` (gtk-update-icon-cache hook). Builds clean, ~52 KB.
- ⚠ `recolor.py` was fixed to only `rmtree` its own `Tanin-<key>` subdirs, NOT
  the whole `OUT` dir (it earlier wiped a shared dir when `OUT_DIR` pointed at
  `~/.local/share/icons` — no data lost that time, but the bug is gone now).
- ⚠ Rebuild this package after any `adwaita-icon-theme` bump (reads
  `/usr/share/icons/Adwaita` at build time).

**Integration (source only, NOT yet in the installed taninux):**
`src/taninux/gui/style.py` → `_set_gsettings()` now also sets
`icon-theme=Tanin-<accent_key>`, so folders recolour **live** when the accent
changes. Also fixed `src/taninux/gui/pages/panel.py` hint "Papirus" → "Adwaita".

**Wiring:**
- `build-tanin-repo.sh`: `tanin-icons` added to `OWN_SIMPLE`.
- `tanin-desktop/PKGBUILD`: depends `+tanin-icons`, **removed** `papirus-icon-theme`
  (Adwaita is the base now), `pkgrel` 3→5.
- Distro manifests synced: `distro/camel.toml` (icon_theme, `icons=[adwaita...]`,
  new `[[packages.own]] tanin-icons`), `distro/MANIFEST.md` (icon row + pkg table).

---

## CURRENT STATE — read carefully

| Thing | State |
|---|---|
| `tanin-icons` package built (`*.pkg.tar.zst`) | ✅ in `packaging/tanin-icons/` |
| Verified GTK resolves folder @48px (svg) + @16px (png) to `Tanin-<accent>` | ✅ |
| **Active in Karim's running session** | ✅ but via a **user-dir copy** at `~/.local/share/icons/Tanin-*` + `gsettings icon-theme=Tanin-beni` (current accent). NOT the pacman package. |
| `tanin-icons` installed via pacman | ❌ (sudo needs a password; no TTY here) |
| `[tanin]` repo rebuilt + published with the new pkgs | ❌ |
| `taninux`/`tanin-desktop` rebuilt with the style.py change | ❌ → **accent→icon auto-switch is NOT live yet**; changing the accent in Settings won't move the icon-theme until taninux is reinstalled. Workaround now: `gsettings set org.gnome.desktop.interface icon-theme Tanin-<accent>`. |
| ISO rebuilt | ❌ |

So: **wired in source + manifests, but no artifacts rebuilt** → a fresh ISO/install
does NOT have it yet.

### To fully ship (needs Karim for sudo)
1. `./packaging/finish-tanin-repo.sh` — builds `tanin-icons` + the new `taninux`/
   `tanin-desktop` + AUR rebuilds.
2. `./packaging/publish-tanin-repo.sh` — upload to Gitea (`TANIN_PKG_TOKEN`).
3. Rebuild the ISO (pulls the updated `[tanin]`).
4. Optional cleanup: once installed system-wide, delete the user-dir copies
   `~/.local/share/icons/Tanin-*` (identical, harmlessly shadowed).

---

## OPEN / OFFERED, not done
- **camel.toml `rebuilt_aur` list is stale** — still only eww/tiramisu/waypaper/
  calamares/paru; missing `librewolf-bin`, `arch-update`, `timeshift-autosnap`,
  `xdg-terminal-exec`. Offered to sync; awaiting Karim.
- **Manual icon-theme picker** (`src/taninux/gui/desktop.py`) still lists the 5
  `Tanin-*` themes and a manual pick gets overridden on the next accent change.
  Could filter them out — not done.
- **Accent-icon scope**: only folders/places are recoloured. Karim was asked
  whether to extend to `emblem-*`/coloured mimetypes — undecided.
- `papirus-folders` still *installed* on Karim's machine (`paru -Rns papirus-folders`).

## Gotchas to respect
- NEVER run lock/session/suspend commands to "test" (locked Karim out once).
- GTK3 can't be exact-Fuji recoloured (parse-time `@define-color`); only GTK4/
  libadwaita is exact. See memory `taninux-gtk-theming`.
- Lots of unrelated uncommitted changes exist in the tree (tanin-calendar,
  online_accounts, gtklock, iso/*) — NOT from this session; don't bundle them.

## Files touched this session
`packaging/tanin-icons/{PKGBUILD,recolor.py,tanin-icons.install}` (new),
`packaging/{build,finish}-tanin-repo.sh`, `packaging/tanin-desktop/PKGBUILD`,
`src/taninux/gui/style.py`, `src/taninux/gui/pages/panel.py`,
`distro/{camel.toml,MANIFEST.md}`.