1# mirada-compositor — el Cuerpo de carmen
2
3Un compositor Wayland teselante real, sobre [`smithay`]. Es el **Cuerpo**
4de la arquitectura Cerebro↔Cuerpo de `mirada` (ver
5`crates/modules/mirada/SDD.md`): habla el protocolo Wayland con los
6clientes, compone sus superficies y aplica la geometría que decide el
7Cerebro.
8
9Tiene **dos backends gráficos**:
10
11- **`winit`** — corre **anidado**, como una ventana dentro de tu sesión
12  gráfica actual (X11 o Wayland). Para desarrollar y probar sin dejar el
13  escritorio.
14- **`drm`** — corre **nativo** sobre una TTY, sin sesión anfitriona:
15  toma la GPU (DRM/KMS/GBM/EGL), el teclado (`libinput`) y la pantalla
16  entera. Es carmen como tu escritorio de verdad.
17
18Sin argumentos elige solo: con `DISPLAY`/`WAYLAND_DISPLAY` → `winit`;
19sin ellos → `drm`. O fuérzalo: `mirada-compositor --winit` / `--drm`.
20
21La bandera `--greeter` (ortogonal al backend) arranca el compositor como
22gestor de login — ver **Modo greeter (DM)** más abajo.
23
24## Backends
25
26### winit — anidado
27
28```sh
29cargo run -p mirada-compositor -- --winit
30```
31
32Necesita una sesión gráfica anfitriona (X11 o Wayland) donde dibujar su
33ventana; sin ella aborta con un mensaje que lo explica.
34
35### drm — nativo sobre TTY
36
37```sh
38cargo run -p mirada-compositor -- --drm
39```
40
41Corre directo sobre el hardware. Requiere una **TTY** (`Ctrl+Alt+F3`),
42una GPU con `/dev/dri`, y `seatd` o `logind` para la sesión. Toma la
43pantalla completa; sal con `Super+Shift+e` o `Ctrl+C`.
44
45Lleva teclado y ratón por `libinput`: el foco sigue al puntero y los
46clics y la rueda llegan a la ventana que tienes debajo. El cursor toma
47la forma que pide el cliente (la «I» sobre texto, una mano…) y cae a un
48cuadrado por defecto sobre el escritorio. **`Super`+arrastre** con el
49botón izquierdo mueve una ventana, con el derecho la redimensiona — al
50arrastrarla, la ventana pasa a flotar. Cada ventana lleva un marco
51fino: azul la que tiene el foco, gris las demás.
52
53- `MIRADA_STARTUP=<cmd>` — lanza una app al arrancar (`MIRADA_STARTUP=foot`).
54- `MIRADA_DRM_TIMEOUT=<s>` — cierra el compositor solo tras N segundos
55  (0 o sin definir = sin tope).
56
57## Como sesión de escritorio
58
59Para usar carmen como tu escritorio de verdad — entrar a una sesión, no
60sólo probarlo:
61
621. Compila e instala los binarios en el `PATH`:
63
64   ```sh
65   cargo build --release -p mirada-compositor -p mirada-ctl -p mirada-launcher
66   sudo install -m755 target/release/mirada-compositor \
67        target/release/mirada-ctl target/release/mirada-launcher /usr/local/bin/
68   sudo install -m755 session/mirada-session /usr/local/bin/
69   ```
70
712. Arranca desde una TTY:
72
73   ```sh
74   mirada-session
75   ```
76
77   O regístralo en un gestor de login copiando `session/carmen.desktop`
78   a `/usr/share/wayland-sessions/` — aparecerá carmen como sesión.
79
803. **Autoarranque** — los programas que quieras al iniciar van en
81   `~/.config/mirada/autostart`, uno por línea (`#` comenta). Tienes un
82   ejemplo en `session/autostart.example`:
83
84   ```sh
85   mkdir -p ~/.config/mirada
86   cp crates/apps/mirada-compositor/session/autostart.example \
87      ~/.config/mirada/autostart
88   ```
89
90Dentro de la sesión, `Ctrl+Alt+F1…F12` salta a otra TTY y vuelve sin
91romper carmen.
92
93## Modo greeter (DM)
94
95`mirada-compositor --greeter` arranca el compositor como **gestor de
96login**: en vez de la sesión, compone el greeter (`mirada-greeter`),
97que lanza como proceso hijo. El usuario teclea sus credenciales; cuando
98el login es válido el greeter emite un `SessionTicket` por su stdout y
99el compositor **muta a modo sesión sin reiniciar el servidor Wayland**
100— el mismo proceso, la misma GPU, las mismas ventanas («mutación
101atómica»). Desde ahí baja privilegios al usuario autenticado
102(`setuid`/`setgid` + grupos) para todo lo que lanza.
103
104La bandera es ortogonal al backend: `--greeter` solo (auto), o
105`--greeter --drm` / `--greeter --winit`.
106
107```sh
108# DM real, sobre una TTY — el compositor corre como root: PAM lo exige
109sudo mirada-compositor --greeter --drm
110
111# iterar el greeter anidado, con credenciales de prueba
112MIRADA_GREETER_MOCK=demo:demo \
113  cargo run -p mirada-compositor -- --greeter --winit
114```
115
116En modo greeter no se registran atajos (todas las teclas van al
117greeter — que el usuario no pueda lanzar nada ni cerrar el compositor),
118se rechaza `spawn:` y no corre el autoarranque; los atajos y la sesión
119arrancan sólo tras el traspaso. `MIRADA_GREETER_BIN` apunta a otro
120binario de greeter (cómodo para señalar a `target/…` en desarrollo).
121
122## Lanzador de aplicaciones
123
124`mirada-launcher` escanea los `.desktop` del sistema y lanza el que
125elijas. Es un programa de terminal sin dependencias: lo abres en una
126terminal pequeña y filtras escribiendo. El keymap por defecto ata
127`Super+p` a `spawn:foot -e mirada-launcher` — pulsa el atajo, escribe
128unas letras del nombre, Enter.
129
130Necesita `mirada-launcher` y `foot` en el `PATH` (ver la instalación de
131arriba). Suelto también vale: `mirada-launcher` en cualquier terminal.
132
133## Dos modos
134
135- **Autónomo** (por defecto) — lleva un `Desktop` (de `mirada-brain`)
136  embebido. Es un compositor teselante completo en un solo proceso.
137
138  ```sh
139  cargo run -p mirada-compositor
140  ```
141
142- **Enlazado** — el Cuerpo escucha en un socket y la app `mirada` (el
143  Cerebro GPUI) se conecta y decide la geometría.
144
145  ```sh
146  # terminal 1 — el Cuerpo
147  MIRADA_SOCKET=/tmp/mirada.sock cargo run -p mirada-compositor
148  # terminal 2 — el Cerebro
149  MIRADA_SOCKET=/tmp/mirada.sock cargo run -p mirada
150  ```
151
152## Probarlo
153
154Al arrancar imprime el `WAYLAND_DISPLAY` que abrió. Lanza cualquier
155cliente Wayland contra él:
156
157```sh
158WAYLAND_DISPLAY=wayland-1 foot      # o weston-terminal, alacritty, …
159```
160
161Las ventanas se teselan solas. El teclado, con la ventana del compositor
162enfocada, maneja el escritorio con atajos `Super+…`: el lanzador de
163aplicaciones `Super+p`, una terminal `Super+Shift+Return`, foco
164`Super+j/k`, los 7 layouts en `Super+t/m/g/c/r/d/s` (o ciclar con
165`Super+space`), área maestra `Super+h/l`, `nmaster` `Super+,/.`,
166promover a maestra `Super+Return`, escritorios `Super+1..9`, cerrar
167`Super+q`. Cierra la ventana del compositor para salir.
168
169## Atajos de teclado
170
171Los atajos son configurables en RON: `~/.config/mirada/keymap.ron`. En
172modo autónomo, el Cuerpo lo carga al arrancar (si no existe, escribe uno
173por defecto documentado) y lo **recarga en caliente** — edita el archivo,
174guarda, y los atajos cambian sin reiniciar. En modo enlazado el keymap es
175asunto del Cerebro (la app `mirada`).
176
177```sh
178cargo run -p mirada-brain --example keymap-default   # ver el formato
179```
180
181El compositor en sí no interpreta atajos: sólo intercepta las
182combinaciones que el Cerebro le pide (`GrabKeys`) y le devuelve la
183pulsada. *Qué significa* cada una lo decide `mirada-brain`. Ver el SDD.
184
185## Control externo
186
187En modo autónomo, el compositor abre un socket de control y `mirada-ctl`
188lo maneja desde la terminal — al estilo de `swaymsg`/`hyprctl`:
189
190```sh
191mirada-ctl focus-next            # cambia el foco
192mirada-ctl focus-window 5        # enfoca una ventana concreta
193mirada-ctl workspace 3           # va al escritorio 3
194mirada-ctl windows               # lista las ventanas
195```
196
197En modo enlazado el socket de control lo abre el Cerebro (la app
198`mirada`), no el compositor.
199
200## Qué implementa
201
202`wl_compositor`, `xdg_shell` (toplevels y popups), `wl_shm`, `wl_seat`
203(teclado, y ratón en el backend DRM), `wl_output`, `wl_data_device`
204(selección), `xdg-decoration` — fuerza decoración del servidor y no
205dibuja ninguna, así las ventanas van sin barra de título — y
206`zwp_linux_dmabuf`, que deja conectarse a los clientes que pintan por
207GPU (apps GPUI, navegadores acelerados). Composición con `GlesRenderer`
208— en `winit` sobre la ventana, en `drm` con un `DrmCompositor` por
209salida.
210
211Reusa `mirada-body` para la contabilidad de salidas y superficies, y
212`mirada-link` para el cable hacia un Cerebro externo. Toda la lógica
213espacial es agnóstica de Wayland y vive en los crates de
214`crates/modules/mirada/`.
215
216## Pendiente
217
218Del backend DRM: conmutación de VT, hotplug de monitores, multi-GPU.
219Puntero en el backend `winit`. Aislamiento de clientes. Ver el SDD.
220
221[`smithay`]: https://github.com/Smithay/smithay