seth-linux-theme/SESSION.md

# SESSION.md — Seth Linux Theme

## Project Summary
Centralized Linux desktop theme for Seth's GNOME setup. Black titlebars, square corners, ultra-thin headerbars, dark mode with orange accent (#D35400). Configs for GTK3/4 CSS, kitty terminal, and GNOME gsettings.

## Gitea
- Repo: https://git.sethpc.xyz/Seth/seth-linux-theme

## Context Files
- `gtk-3.0/gtk.css` — GTK3/4 headerbar CSS (same file used for both)
- `kitty/kitty-theme.conf` — kitty terminal overrides (borderless, black titlebar, tab bar config, keybindings)
- `kitty/tab_bar.py` — custom tab bar: flat tabs + right-aligned status (git, cpu, mem, uptime, host, clock)
- `kitty/tab-bar-hide.conf` / `tab-bar-show.conf` — toggle snippets (may be unused now with inline --override approach)
- `gnome/apply-gnome-settings.sh` — GNOME dark mode, orange accent, Super+right resize
- `install.sh` — deploys all configs to target user's ~/.config

## Session Notes

### Architecture
- GTK CSS goes in `~/.config/gtk-3.0/gtk.css` and `~/.config/gtk-4.0/gtk.css` (same content)
- kitty uses its own config, not GTK — `wayland_titlebar_color` only works with CSD, not Mutter SSD
- `hide_window_decorations yes` removes Mutter's server-side decorations from kitty entirely (borderless)
- GNOME Shell rounded corners are Mutter-controlled, not GTK CSS — need GNOME Shell theme or extension to override DE-wide
- `resize-with-right-button true` enables Super+right-drag to resize (was disabled by default)

### Deployment
- Desktop runs on steel141 (192.168.0.141) under `seth@` user
- `claude@` is headless, no DE — GUI configs must target `/home/seth/.config/`
- From claude@: `sudo -u seth cp <file> /home/seth/.config/...`
- GTK3 apps pick up CSS changes live (open new window). GTK4/libadwaita apps need full relaunch. Kitty needs relaunch.

### Current state (2026-04-07)
- GTK CSS: black headerbar, square corners, white text, transparent buttons, #999 backdrop text/icons, 36px min-height
- Kitty: borderless (`hide_window_decorations yes`), JetBrainsMono Nerd Font, custom tab bar with status area
- Kitty tab bar: flat style (no powerline), user@ prefix for non-seth users, right-aligned status (git branch, CPU%, memory, uptime, hostname, clock) with Nerd Font icons in orange
- Kitty tab bar toggle: F12 hides (min_tabs=999), Shift+F12 shows (min_tabs=1) via `remote_control load-config --override`
- GNOME: dark mode, orange accent, Super+right resize enabled

### Open issues
- [ ] GNOME Shell rounded window corners — Mutter hardcodes CSD corner rounding at compositor level. No CSS override possible (tried `border-radius: 0 !important` on all nodes). No gsetting exists. GNOME Shell CSS `.window-frame` doesn't control it either. Only fix: patched Mutter or a GNOME Shell extension that modifies Mutter's clipping behavior. "Rounded Window Corners Reborn" extension only ADDS rounding (shader overlay), doesn't remove native rounding.

### Resolved issues (2026-04-07)
- [x] Nautilus sidebar/main headerbar height mismatch — Fixed by targeting `headerbar stackpage > box` and `headerbar stack` with `min-height: 0` and zero padding. Root cause: NautilusPathBar inside a GtkStack in the main headerbar was taller than the sidebar's simple AdwWindowTitle.
- [x] Thin gray border line at top of headerbar — Fixed by targeting `decoration`, `window.csd`, `.titlebar:not(headerbar)`, and `toolbarview > .top-bar` with `border: none; box-shadow: none; outline: none`. Was a CSD decoration border, not on the headerbar node itself.
- [x] User Themes extension — Installed (`gnome-shell-extension-user-theme` apt package), enabled, Sethian theme set via `gsettings set org.gnome.shell.extensions.user-theme name "Sethian"`. Required `gnome-shell --replace` to detect newly installed extension.

### Design decisions
- 2026-04-07: Use stock Adwaita dark + CSS overrides, not a full third-party theme — minimal maintenance, survives GNOME updates
- 2026-04-07: Kitty borderless rather than trying to style Mutter's SSD — cleaner, no titlebar to fight with
- 2026-04-07: adw-gtk3 not needed if only overriding headerbar — stock Adwaita + user CSS is sufficient
- 2026-04-07: Flat tab style over powerline — powerline creates clipping artifacts with long titles, flat is simpler
- 2026-04-07: JetBrainsMono Nerd Font — needed for icon glyphs in tab bar status area
- 2026-04-07: Tab bar toggle via `remote_control load-config --override` — no scripts/sockets needed, inline kitty RC

### DANGER — never do these
- **NEVER run `gnome-shell --replace` from claude@ session** — it replaces seth's shell process, kills the active session, resets all extensions and theming to defaults. Use `dbus-send` reexec or ask seth to relog instead.

### Kitty architecture notes
- Repo files (`seth-linux-theme/kitty/`) and Seth's live config (`/home/seth/.config/kitty/`) are separate copies, not symlinks — must deploy manually
- `tab_bar.py` custom draw function: kitty calls `draw_tab()` for each tab. `is_last=True` is the hook for drawing right-aligned status
- CPU % uses delta sampling from `/proc/stat` — first draw shows "..." (no prior sample), subsequent draws show real usage
- `kitty @ load-config` merges overrides into running instance without restart
- `remote_control` from a keymap runs inside kitty's process — no socket/listen_on needed
- Kitty does NOT hot-reload `tab_bar.py`, font changes, or keybindings — full restart required
- Ctrl+Shift+F5 only reloads colors/visuals
- `toggle_tab_bar` action does NOT exist in kitty 0.41.1
- `set-option` RC command does NOT exist — use `load-config --override` instead
- `load-config-file` is wrong command name — correct is `load-config`
- Nerd Font installed system-wide at `/usr/local/share/fonts/NerdFonts/`

### What was tried and didn't work
- `headerbar *` with `min-height: 0` — didn't equalize sidebar/main headerbar heights
- `headerbar > windowhandle > centerbox` targeting — no effect on height mismatch
- `wayland_titlebar_color` in kitty — ignored when Mutter uses server-side decorations
- `border: none` on headerbar — doesn't remove the gray line at top (it's not a headerbar border)
- `border-radius: 0 !important` on `window`, `window.csd`, `decoration`, `.titlebar` — doesn't remove rounded corners (Mutter compositor-level clipping)
- GNOME Shell theme `.window-frame { border-radius: 0 }` — doesn't control Mutter's window corner rounding
- GTK_DEBUG=interactive on Nautilus — inspector window doesn't open (GNOME 48, Nautilus 48.3). Ctrl+Shift+D/I also failed. Shell restart required for newly installed extensions.
- `draw_tab_with_powerline` — creates clipping artifacts with long tab titles (extra rectangle gets cut off)
- `toggle_tab_bar` kitty action — doesn't exist in 0.41.1
- `remote_control set-option` — not a valid RC command
- `remote_control load-config-file` — wrong name, correct is `load-config`
- `map ctrl+shift+f1` — produces capital P instead of triggering action (escape sequence issue)
- Toggle via background script + `kitty @` + socket — overcomplicated, socket discovery unreliable from background processes
- `listen_on unix:/tmp/kitty-{kitty_pid}` + script with `kitty @ --to` — still failed, too many moving parts

### Debugging notes (2026-04-07)
- Nautilus widget tree (from gresource): `NautilusWindow` (AdwApplicationWindow) → `AdwOverlaySplitView` → sidebar: `AdwToolbarView` → `AdwHeaderBar`; content: `AdwToolbarView` → `NautilusToolbar` (AdwBin) → `AdwHeaderBar` with title = `GtkBox` containing `NautilusPathBar` in a `GtkStack`
- The main headerbar height was driven by NautilusPathBar's default min-height/padding in the GtkStack
- The gray top line was from the CSD `decoration` node and/or `toolbarview > .top-bar` border