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
31## Flujo
32
33```text
34  mirada-layout ─► mirada-protocol ─► mirada-brain ─► [app mirada · Cerebro]
35                          │                                  │
36                          │                            mirada-link
37                          │                                  │
38                          └────► mirada-body ─► [mirada-compositor · Cuerpo]
39```
40
41- El Cuerpo reporta hardware/clientes con `BodyEvent` (salida conectada,
42  ventana abierta, atajo pulsado…).
43- El Cerebro (`Desktop::on_event`) recalcula y emite `BrainCommand`
44  (`Place` con la geometría completa, `Close`, `GrabKeys`…).
45- El Cuerpo (`BodyState::apply`) traduce cada comando a `BodyOp`
46  concretas y sólo emite lo que de verdad cambia.
47
48## Detalle por crate
49
50- **`mirada-layout`** — `Rect` + `split` (reparto exacto de píxeles),
51  `LayoutMode` (`MasterStack`/`Monocle`/`Grid`/`Columns`), `Workspace`
52  con foco cíclico y reordenado. Determinista.
53- **`mirada-protocol`** — `WindowPlacement`, los enums `BrainCommand` y
54  `BodyEvent`, el marco `postcard` con prefijo `u32` LE
55  (`write_frame`/`read_frame`, guard `MAX_FRAME`) y el puente
56  `placements(&Workspace, Rect)`.
57- **`mirada-brain`** — `Desktop`: salidas, 9 escritorios virtuales,
58  registro de ventanas. `on_event(BodyEvent) -> Vec<BrainCommand>`;
59  `DesktopAction` + mapa de teclas estilo *tiling WM* (`Super`).
60- **`mirada-link`** — `Link<Out,In>` sobre socket Unix; hilo lector de
61  fondo + canal `mpsc` para sondeo no bloqueante. `BrainLink`/`BodyLink`,
62  `connected_pair` (socketpair), `connect`/`listen` por ruta.
63- **`mirada-body`** — `BodyState`: salidas + superficies; `apply` traduce
64  `BrainCommand`→`BodyOp` (idempotente), los mutadores del backend
65  devuelven los `BodyEvent` a mandar. Ejemplo `headless`: un Cuerpo sin
66  gráficos guiado por stdin para ejercitar el bucle entero.
67- **`mirada` (app)** — envuelve `Desktop` y lo pinta (barra de
68  escritorios + modo + foco, lienzo teselado). Con `MIRADA_SOCKET`
69  conecta a un Cuerpo; sin él corre en **simulación** (ventanas
70  sintéticas, teclado de la propia ventana).
71
72## Dependencias
73
74- Todos los `lib` con `#![forbid(unsafe_code)]`. Cero Wayland, cero
75  `smithay` en los seis crates de arriba.
76- El acoplamiento a Wayland/hardware vive sólo en `mirada-compositor`.
77
78## Estado
79
80Implementado y verde: `mirada-layout` (22 tests), `mirada-protocol`
81(9), `mirada-brain` (17), `mirada-link` (7), `mirada-body` (13), y la
82app `mirada` (compila; verificación visual manual).
83
84El **Cuerpo** ya existe: `mirada-compositor` es un compositor Wayland
85teselante real sobre `smithay`, con backend `winit` — corre **anidado**
86como una ventana dentro de la sesión gráfica actual. Habla
87`wl_compositor`/`xdg_shell`/`wl_shm`/`wl_seat`/`wl_data_device`, compone
88las superficies de los clientes con `GlesRenderer` y aplica la geometría
89del Cerebro. Reusa `mirada-body` (contabilidad) y `mirada-link` (cable).
90Dos modos: **autónomo** (Cerebro `Desktop` embebido, un solo proceso) o
91**enlazado** (`MIRADA_SOCKET` → la app `mirada` decide la geometría).
92Compila y pasa clippy; verificación visual manual — ver
93`crates/apps/mirada-compositor/README.md`.
94
95**Pendiente** — refinamientos del Cuerpo, no verificables en modo
96desatendido:
97
98| capa pendiente       | rol                                                      |
99| -------------------- | -------------------------------------------------------- |
100| backend DRM/libinput | de `winit` anidado a sesión nativa: superficies KMS, GPU |
101| `mirada-input`       | puntero/ratón completo, repetición de teclas, gestos     |
102| `mirada-sandbox`     | aislamiento de clientes sobre `arje-incarnate`           |
103
104CRIU (congelar/restaurar ventanas) queda anotado como futuro.