1# modules/mirada/ — Compositor Wayland (carmen)
2
3**Propósito.** Un compositor Wayland teselante. La decisión de diseño
4central es partirlo en dos procesos, el **Cerebro** y el **Cuerpo**:
5
6- **El Cuerpo** (`mirada-compositor`, sobre `smithay`) habla Wayland con
7  los clientes, posee el hardware (DRM/GPU/libinput) y compone las
8  superficies reales. Los píxeles nunca salen de él — composición
9  *zero-copy*.
10- **El Cerebro** (la app `mirada`, GPUI) decide *dónde* va cada ventana
11  —pura aritmética de rectángulos— y orquesta el escritorio: layouts,
12  atajos, focos, escritorios virtuales.
13
14Los dos hablan por un socket Unix con un contrato mínimo de enums. Así,
15toda la lógica espacial es agnóstica de Wayland y se prueba sin un
16servidor gráfico; el Cuerpo queda reducido a "habla el protocolo y
17ejecuta operaciones de geometría".
18
19## Crates
20
21| crate              | tipo     | rol                                                                    |
22| ------------------ | -------- | ---------------------------------------------------------------------- |
23| `mirada-layout`    | lib      | Motor de teselado: `Rect`, modos de layout, `Workspace` (ventanas, foco) |
24| `mirada-protocol`  | lib      | Contrato Cerebro↔Cuerpo: `BrainCommand`/`BodyEvent` + marco de cable   |
25| `mirada-brain`     | lib      | Orquestador del escritorio: `Desktop`, eventos→comandos, atajos        |
26| `mirada-link`      | lib      | Transporte: el socket Unix con hilo lector + canal                     |
27| `mirada-body`      | lib      | Contabilidad del Cuerpo: `BodyState`, traduce comandos a `BodyOp`      |
28| `mirada` (app)     | bin/GPUI | El Cerebro: ventana que tesela el escritorio y manda geometría         |
29| `mirada-compositor`| bin/smithay | El Cuerpo: compositor Wayland real (backend `winit`, anidado)        |
30| `mirada-ctl` (app) | bin/CLI  | Control externo del Cerebro (estilo `swaymsg`): acciones y consultas   |
31
32## Flujo
33
34```text
35  mirada-layout ─► mirada-protocol ─► mirada-brain ─► [app mirada · Cerebro]
36                          │                                  │
37                          │                            mirada-link
38                          │                                  │
39                          └────► mirada-body ─► [mirada-compositor · Cuerpo]
40```
41
42- El Cuerpo reporta hardware/clientes con `BodyEvent` (salida conectada,
43  ventana abierta, atajo pulsado…).
44- El Cerebro (`Desktop::on_event`) recalcula y emite `BrainCommand`
45  (`Place` con la geometría completa, `Close`, `GrabKeys`…).
46- El Cuerpo (`BodyState::apply`) traduce cada comando a `BodyOp`
47  concretas y sólo emite lo que de verdad cambia.
48
49## Detalle por crate
50
51- **`mirada-layout`** — `Rect` + `split` (reparto exacto de píxeles),
52  `LayoutMode` con 7 modos (`MasterStack`, `CenteredMaster`, `Spiral`
53  —espiral de Fibonacci—, `Grid`, `Columns`, `Rows`, `Monocle`) y
54  `LayoutMode::next()` para el ciclo, `Workspace` con foco cíclico,
55  reordenado y `promote_focused`. `LayoutParams` lleva `master_ratio` y
56  `master_count` (`nmaster`); *smart gaps* (una sola ventana va a
57  sangre). Determinista.
58- **`mirada-protocol`** — `WindowPlacement`, los enums `BrainCommand` y
59  `BodyEvent`, el marco `postcard` con prefijo `u32` LE
60  (`write_frame`/`read_frame`, guard `MAX_FRAME`) y el puente
61  `placements(&Workspace, Rect)`.
62- **`mirada-brain`** — `Desktop`: salidas, 9 escritorios virtuales,
63  registro de ventanas. `on_event(BodyEvent) -> Vec<BrainCommand>`;
64  `DesktopAction` + `Keymap` configurable (`set_keymap` en caliente) +
65  `Rules` de ventana.
66- **`mirada-link`** — `Link<Out,In>` sobre socket Unix; hilo lector de
67  fondo + canal `mpsc` para sondeo no bloqueante. `BrainLink`/`BodyLink`,
68  `connected_pair` (socketpair), `connect`/`listen` por ruta.
69- **`mirada-body`** — `BodyState`: salidas + superficies; `apply` traduce
70  `BrainCommand`→`BodyOp` (idempotente), los mutadores del backend
71  devuelven los `BodyEvent` a mandar. Ejemplo `headless`: un Cuerpo sin
72  gráficos guiado por stdin para ejercitar el bucle entero.
73- **`mirada` (app)** — envuelve `Desktop` y lo pinta (barra de
74  escritorios + modo + foco, lienzo teselado). Con `MIRADA_SOCKET`
75  conecta a un Cuerpo; sin él corre en **simulación** (ventanas
76  sintéticas, teclado de la propia ventana). Pips de escritorio y
77  ventanas clicables.
78- **`mirada-ctl` (app)** — CLI de control: parsea la acción de los
79  argumentos (`DesktopAction: FromStr`) y la manda al Cerebro por el
80  socket de control; `windows` y `actions` para consultar.
81
82## Atajos de teclado configurables
83
84El keymap vive **sólo en el Cerebro** (`mirada-brain::Keymap`). El Cuerpo
85nunca lo ve: recibe únicamente la lista de cadenas a interceptar en un
86`GrabKeys`, hace un `Vec::contains` ciego y devuelve la combinación
87pulsada como `Keybind`; es `Desktop` quien la traduce a `DesktopAction`.
88Esa separación —*qué* interceptar (lista barata, Cuerpo) vs. *qué
89significa* (el mapa, Cerebro)— hace innecesario cualquier candado o
90`Arc`: el mapa es monohilo y la lista se reemplaza de golpe.
91
92- **Disco** — RON de texto en `~/.config/mirada/keymap.ron`, editable a
93  mano y versionable. La app lo crea documentado en el primer arranque;
94  si está corrupto, avisa y usa el de por defecto sin pisar el archivo.
95- **Cable** — sólo viaja la lista de cadenas (`GrabKeys`), vía el marco
96  `postcard` que ya existe. No hay formato binario de configuración.
97- **Vocabulario** — la acción es una cadena estable (`"focus-next"`,
98  `"layout:grid"`, `"workspace:3"`): `DesktopAction: Display + FromStr`.
99- **Recarga en caliente** — `Keymap::watch` (sobre `notify`) vigila el
100  archivo; al cambiar, el dueño del `Desktop` recarga, llama a
101  `set_keymap` y reenvía el `GrabKeys`. Sin reiniciar.
102- **Configurador** — no hay ejecutable aparte: el editor de texto del
103  usuario, y la app `mirada` (que a futuro puede dibujar un editor visual
104  sobre el mismo API `Keymap`). `cargo run -p mirada-brain --example
105  keymap-default` imprime el archivo por defecto.
106
107## API de acciones
108
109Toda acción de escritorio converge en un único embudo:
110`Desktop::apply(DesktopAction) -> Vec<BrainCommand>`. El keymap no es más
111que un front-end (`Keybind` → `lookup` → `apply`); hay otros tres:
112
113- **`DesktopAction::FocusWindow(WindowId)`** — direccionamiento directo de
114  una ventana (no sólo ciclar con `FocusNext`/`Prev`); si está en otro
115  escritorio, salta a él. Lo usan la taskbar y `mirada-ctl`.
116- **Ventanas flotantes** — `ToggleFloat` (`Super+f`) saca la enfocada del
117  teselado a un rectángulo libre (centrado, 60 %); `Workspace` guarda las
118  flotantes aparte, `layout()` las pone al final y `WindowPlacement`
119  /`BodyOp::Configure` llevan `floating: bool` para que el Cuerpo las
120  componga por encima.
121- **Pantalla completa** — `ToggleFullscreen` (`Super+Shift+f`): la ventana
122  cubre toda la salida (sin gap), oculta al resto y se lleva el foco;
123  `Workspace.fullscreen: Option<WindowId>`, y el Cuerpo le fija el estado
124  `xdg_toplevel Fullscreen`.
125- **Layout y área maestra por el API** — los 7 modos se intercambian
126  (`SetLayout`/`CycleLayout`, `mirada-ctl layout spiral`); el área
127  maestra se redimensiona (`grow`/`shrink-master`, `Super+l`/`Super+h`);
128  `inc`/`dec-master` cambian `nmaster` (`Super+,`/`Super+.`); y
129  `promote-to-master` lleva la enfocada al puesto maestro (`Super+Return`
130  — `combo_string` ya canoniza teclas con nombre: `Return`, `Tab`, `F5`…).
131- **HUD interactivo** (app `mirada`) — los pips de escritorio y las
132  ventanas del lienzo son clicables: clic = `apply` de la acción.
133- **`mirada-ctl`** — control externo por línea de comandos
134  (`mirada-ctl focus-next`, `workspace 3`, `windows`). Habla con el
135  Cerebro por un socket Unix aparte; el módulo `mirada-brain::ctl` define
136  `CtlRequest`/`CtlReply` (marco `postcard`), `CtlServer`/`CtlConn` y
137  `send_request`. El Cerebro (la app `mirada` siempre; `mirada-compositor`
138  sólo embebido) abre el socket y atiende en su bucle. `DesktopAction`
139  viaja como enum serializado: contrato tipado de punta a punta.
140
141`cargo run -p mirada-brain --example headless-ctl` levanta un Cerebro sin
142gráficos para ejercitar `mirada-ctl` en modo desatendido.
143
144## Reglas de ventana
145
146`mirada-brain::rules` decide qué hacer con una ventana **al abrirse**:
147config declarativa en RON (`~/.config/mirada/rules.ron`), mismo patrón
148que el keymap. Cada `Rule` casa por subcadena de `app_id` y/o `title`
149(sin distinguir mayúsculas; vacío = cualquiera) y aplica un destino:
150`workspace` (1..9) y/o `floating`. Gana la primera regla que case.
151
152El `Desktop` consulta `Rules::resolve` en cada `WindowOpened` — el evento
153ya trae `app_id`/`title` — y manda la ventana a su escritorio, flotando
154si toca. Se carga al arrancar (la primera vez se escribe una plantilla
155con ejemplos comentados); las reglas afectan a las ventanas futuras, no
156a las ya abiertas.
157
158## Dependencias
159
160- Todos los `lib` con `#![forbid(unsafe_code)]`. Cero Wayland, cero
161  `smithay` en los seis crates de arriba.
162- El acoplamiento a Wayland/hardware vive sólo en `mirada-compositor`.
163
164## Estado
165
166Implementado y verde: `mirada-layout` (32 tests), `mirada-protocol`
167(11), `mirada-brain` (52), `mirada-link` (7), `mirada-body` (14), las
168apps `mirada` y `mirada-compositor` (compilan; verificación visual
169manual) y `mirada-ctl` (CLI, probado vía el ejemplo `headless-ctl`).
170
171El **Cuerpo** ya existe: `mirada-compositor` es un compositor Wayland
172teselante real sobre `smithay`, con backend `winit` — corre **anidado**
173como una ventana dentro de la sesión gráfica actual. Habla
174`wl_compositor`/`xdg_shell`/`wl_shm`/`wl_seat`/`wl_data_device`, compone
175las superficies de los clientes con `GlesRenderer` y aplica la geometría
176del Cerebro. Reusa `mirada-body` (contabilidad) y `mirada-link` (cable).
177Dos modos: **autónomo** (Cerebro `Desktop` embebido, un solo proceso) o
178**enlazado** (`MIRADA_SOCKET` → la app `mirada` decide la geometría).
179Compila y pasa clippy; verificación visual manual — ver
180`crates/apps/mirada-compositor/README.md`.
181
182**Pendiente** — refinamientos del Cuerpo, no verificables en modo
183desatendido:
184
185| capa pendiente       | rol                                                      |
186| -------------------- | -------------------------------------------------------- |
187| backend DRM/libinput | de `winit` anidado a sesión nativa: superficies KMS, GPU |
188| `mirada-input`       | puntero/ratón completo, repetición de teclas, gestos     |
189| `mirada-sandbox`     | aislamiento de clientes sobre `arje-incarnate`           |
190
191CRIU (congelar/restaurar ventanas) queda anotado como futuro.