funman300
85ef13492e
Flameshot's portal-based capture path on niri triggers an xdg-desktop-portal access prompt on every invocation, blocking the screenshot itself. grim talks to wlr-screencopy directly and never touches the portal, so no prompt. Pipeline: slurp (region) → grim (capture) → satty (annotate + copy + save). satty replaces the wofi action menu by being the post-capture surface itself. - scripts/screenshot.sh added - install.sh symlinks it; flameshot.ini generator removed - niri Mod+Print → "screenshot" - packages.txt drops flameshot - docs tables updated Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
287 lines
4.9 KiB
Markdown
287 lines
4.9 KiB
Markdown
# ARCHITECTURE.md
|
|
|
|
## Overview
|
|
|
|
This system is a **Wayland-first desktop environment** built around the **Niri compositor**, designed for:
|
|
|
|
* Tiling workflow
|
|
* Keyboard-driven interaction
|
|
* Minimal background processes
|
|
* Clean separation between components
|
|
|
|
---
|
|
|
|
## High-Level Architecture
|
|
|
|
```
|
|
┌──────────────┐
|
|
│ greetd │
|
|
│ + regreet │
|
|
└──────┬───────┘
|
|
│
|
|
▼
|
|
┌──────────────┐
|
|
│ Niri │
|
|
│ Compositor │
|
|
└──────┬───────┘
|
|
┌───────────────┼────────────────┐
|
|
▼ ▼ ▼
|
|
┌────────┐ ┌────────┐ ┌──────────┐
|
|
│ Waybar │ │ Mako │ │ Wofi │
|
|
└────────┘ └────────┘ └──────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
Status UI Notifications App Launcher
|
|
|
|
┌────────────────────────────────────┐
|
|
▼ ▼
|
|
Alacritty GTK Apps / CLI
|
|
│
|
|
▼
|
|
Fish + Starship
|
|
```
|
|
|
|
---
|
|
|
|
## Component Responsibilities
|
|
|
|
### Niri (Core)
|
|
|
|
* Window management
|
|
* Input handling
|
|
* Layout control
|
|
* Workspace logic
|
|
|
|
**Owns:**
|
|
|
|
* Keybindings
|
|
* Window rules
|
|
* Focus behavior
|
|
|
|
---
|
|
|
|
### Waybar (Status Layer)
|
|
|
|
* Displays system info (time, CPU, network, etc.)
|
|
* Acts as visual feedback layer
|
|
|
|
**Design constraints:**
|
|
|
|
* No heavy scripts
|
|
* Prefer event-driven updates
|
|
|
|
---
|
|
|
|
### Mako (Notifications)
|
|
|
|
* Handles all desktop notifications
|
|
|
|
**Rules:**
|
|
|
|
* Short timeouts
|
|
* Minimal visual noise
|
|
* No stacking chaos
|
|
|
|
---
|
|
|
|
### Wofi (Launcher)
|
|
|
|
* Application launcher + runner
|
|
|
|
**Usage modes:**
|
|
|
|
* drun (desktop apps)
|
|
* run (commands)
|
|
|
|
---
|
|
|
|
### Terminal Stack
|
|
|
|
#### Alacritty
|
|
|
|
* GPU-accelerated terminal
|
|
* No tabs (delegated to WM)
|
|
|
|
#### Fish
|
|
|
|
* Interactive shell
|
|
|
|
#### Starship
|
|
|
|
* Prompt renderer
|
|
|
|
---
|
|
|
|
### Session & Login
|
|
|
|
#### greetd + regreet
|
|
|
|
* Lightweight login manager
|
|
* Starts Niri session
|
|
|
|
---
|
|
|
|
### Lock Screen
|
|
|
|
#### gtklock
|
|
|
|
* Simple Wayland-native lockscreen
|
|
|
|
---
|
|
|
|
### Background Services
|
|
|
|
| Function | Tool |
|
|
| ----------- | -------------------- |
|
|
| Wallpaper | swww |
|
|
| Screenshots | grim + slurp + satty |
|
|
| Clipboard | cliphist |
|
|
|
|
---
|
|
|
|
## Data Flow
|
|
|
|
### Startup Sequence
|
|
|
|
1. greetd starts
|
|
2. regreet authenticates user
|
|
3. Niri session launches
|
|
4. Autostart:
|
|
|
|
* waybar
|
|
* mako
|
|
* swww
|
|
* cliphist (if enabled)
|
|
|
|
---
|
|
|
|
### User Interaction Flow
|
|
|
|
**Launching Apps**
|
|
|
|
```
|
|
Keybind → Wofi → Exec → Niri manages window
|
|
```
|
|
|
|
**Notifications**
|
|
|
|
```
|
|
App → DBus → Mako → Render
|
|
```
|
|
|
|
**Status Updates**
|
|
|
|
```
|
|
System → Waybar module → Display
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration Strategy
|
|
|
|
### Centralized via Symlinks
|
|
|
|
```
|
|
~/.config/
|
|
├── niri/
|
|
├── waybar/
|
|
├── alacritty/
|
|
├── fish/
|
|
├── starship.toml
|
|
├── mako/
|
|
├── wofi/
|
|
└── gtklock/
|
|
```
|
|
|
|
All configs are sourced from the repo via:
|
|
|
|
```
|
|
install.sh → ln -s
|
|
```
|
|
|
|
---
|
|
|
|
## Theming Architecture
|
|
|
|
### Global Theme: Tomorrow Night
|
|
|
|
Applied consistently across:
|
|
|
|
* GTK (Materia-dark)
|
|
* Icons (Papirus)
|
|
* Terminal
|
|
* Waybar
|
|
* Wofi
|
|
|
|
### Recommended Structure
|
|
|
|
```
|
|
theme/
|
|
├── colors.json (optional future)
|
|
├── gtk.css
|
|
├── waybar.css
|
|
└── wofi.css
|
|
```
|
|
|
|
---
|
|
|
|
## Extensibility Model
|
|
|
|
### Safe Extensions
|
|
|
|
* Add Waybar modules (lightweight)
|
|
* Add Wofi modes
|
|
* Extend Niri keybindings
|
|
* Add CLI tools
|
|
|
|
### Risky Extensions
|
|
|
|
* Background daemons
|
|
* Polling scripts
|
|
* X11 compatibility layers
|
|
* Overly dynamic configs
|
|
|
|
---
|
|
|
|
## Performance Considerations
|
|
|
|
* Avoid blocking shell scripts
|
|
* Keep Waybar modules lightweight
|
|
* Minimize startup processes
|
|
* Prefer static config over runtime logic
|
|
|
|
---
|
|
|
|
## Failure Modes
|
|
|
|
| Issue | Likely Cause |
|
|
| --------------------- | ------------------- |
|
|
| Black screen on login | Niri config error |
|
|
| Missing bar | Waybar not launched |
|
|
| No notifications | Mako not running |
|
|
| Slow shell | Fish config bloat |
|
|
|
|
---
|
|
|
|
## Future Improvements
|
|
|
|
* Shared theme variables across all tools
|
|
* Config templating (optional, must stay transparent)
|
|
* Per-host overrides
|
|
* Optional feature flags (minimal)
|
|
|
|
---
|
|
|
|
## Guiding Philosophy
|
|
|
|
This system is:
|
|
|
|
* **Predictable**
|
|
* **Minimal**
|
|
* **Fast**
|
|
* **Keyboard-first**
|
|
|
|
Every addition must justify its existence.
|
|
|
|
If it adds complexity without clear benefit, it should not be included.
|