tawasuyu/llimphi

1//! llimphi-compositor — el núcleo declarativo de Llimphi, sin winit.
2//!
3//! Aquí vive el árbol de vista `View<Msg>` (DSL declarativo), su instalación
4//! sobre taffy (`mount`), el pintado a `vello::Scene` (`paint`/`paint_gpu`) y
5//! el hit-test. Nada de esto necesita una ventana ni `llimphi-hal`: la
6//! composición `view → layout → scene` es pura y reutilizable.
7//!
8//! El runtime que la maneja vive aparte:
9//! - `llimphi-ui` la corre sobre winit (`run<A: App>()`).
10//! - a futuro, un runtime sobre el framebuffer del kernel `wawa` puede
11//!   reusar exactamente este compositor sin arrastrar winit.
12//!
13//! `wgpu` entra sólo por la firma de [`GpuPaintFn`] (tipos de Device/Queue/
14//! Encoder/TextureView); `wgpu` no depende de winit, así que el compositor
15//! sigue libre de windowing.
16
17use std::collections::HashMap;
18use std::sync::Arc;
19
20use llimphi_layout::taffy::NodeId;
21use llimphi_layout::{ComputedLayout, LayoutTree, Style};
22use vello::kurbo::{Affine, Point, Rect as KurboRect, RoundedRect};
23use vello::peniko::{Color, Fill, Image, Mix};
24
25mod render;
26mod view;
27pub use render::*;
28
29/// Texto a pintar dentro de un nodo. Alineación por defecto `Center`
30/// (horizontal y vertical), apta para labels de botón. Para layouts tipo
31/// editor o párrafo, usar `.text_aligned(...)` con `Alignment::Start`.
32pub struct TextSpec {
33    pub content: String,
34    pub size_px: f32,
35    pub color: Color,
36    pub alignment: llimphi_text::Alignment,
37    /// `true` = forzar variante italic en la fuente activa. Default false.
38    pub italic: bool,
39    /// CSS-style font-family string (acepta lista con fallbacks). `None`
40    /// = la fuente default de parley.
41    pub font_family: Option<String>,
42    /// Múltiplo de interlínea (`line-height` / `font-size`). 1.2 es el
43    /// default que usaban todos los callers; puriy lo sobreescribe con el
44    /// valor computado de CSS. Se usa tanto al **medir** (para que taffy
45    /// reserve el alto correcto) como al **pintar**, así medida y dibujo
46    /// coinciden.
47    pub line_height: f32,
48    /// Colores por rango de **bytes** sobre `content`, para texto multicolor
49    /// (syntax highlighting) en una sola pasada de shaping. `None` = color
50    /// uniforme (`color`). Cuando es `Some`, el runtime usa
51    /// `Typesetter::layout_runs` + `draw_layout_runs`, y `color` actúa como
52    /// color por defecto de lo no cubierto por ningún run.
53    pub runs: Option<Vec<(usize, usize, Color)>>,
54}
55
56/// Fase de un drag activo. `Move` se emite por cada `CursorMoved` con el
57/// delta desde el evento anterior; `End` se emite al soltar el botón.
58#[derive(Debug, Clone, Copy, PartialEq, Eq)]
59pub enum DragPhase {
60    Move,
61    End,
62}
63
64/// Handler de drag. Recibe la fase + delta (`dx`, `dy`) **desde el evento
65/// anterior** (no acumulado desde el press). Devolver `None` deja el drag
66/// activo sin disparar Msg. `Arc<dyn Fn>` para que el runtime pueda
67/// clonarlo barato al iniciar el drag y mantenerlo vivo aunque el cache
68/// de la vista se regenere mientras tanto.
69pub type DragFn<Msg> = Arc<dyn Fn(DragPhase, f32, f32) -> Option<Msg> + Send + Sync>;
70
71/// Handler de drop. El runtime lo invoca cuando un drag activo se suelta
72/// sobre este nodo. Recibe el `payload` `u64` que el origen del drag
73/// declaró vía [`View::drag_payload`]. Devolver `None` ignora el drop.
74///
75/// Los IDs `u64` son opacos para el runtime: el widget elige una
76/// convención (índice de tile, hash del item, etc.) y el handler decide
77/// qué Msg emitir en función de ese ID.
78pub type DropFn<Msg> = Arc<dyn Fn(u64) -> Option<Msg> + Send + Sync>;
79
80/// Handler de click con posición. Recibe `(x_local, y_local, rect_w,
81/// rect_h)`: las dos primeras son la posición del cursor **relativa a
82/// la esquina superior-izquierda del nodo** y las dos últimas son el
83/// ancho/alto actual del nodo en pixels — útil cuando el caller
84/// necesita centrar o normalizar. Devolver `None` no dispara update.
85pub type ClickAtFn<Msg> = Arc<dyn Fn(f32, f32, f32, f32) -> Option<Msg> + Send + Sync>;
86
87/// Handler de rueda **local a un nodo**. Recibe el delta `(dx, dy)` en
88/// líneas lógicas (misma normalización que `App::on_wheel`: `dy` positivo
89/// = scroll hacia abajo). El runtime lo invoca cuando la rueda gira con el
90/// cursor sobre este nodo, ANTES de caer al `App::on_wheel` global: si el
91/// handler devuelve `Some(Msg)`, el evento se consume acá. Permite áreas
92/// de scroll autocontenidas (el widget `scroll` lo usa) sin que cada app
93/// rutee la rueda a mano por su `Model`. Devolver `None` deja pasar el
94/// evento al `on_wheel` global.
95pub type ScrollFn<Msg> = Arc<dyn Fn(f32, f32) -> Option<Msg> + Send + Sync>;
96
97/// Variante de [`DragFn`] que **conoce la posición inicial del press**
98/// relativa al rect del nodo. Útil cuando el caller necesita identificar
99/// qué entidad (Concepto, lemming, etc.) bajo el cursor agarró el drag.
100/// Recibe `(phase, dx, dy, initial_lx, initial_ly)`.
101pub type DragAtFn<Msg> = Arc<dyn Fn(DragPhase, f32, f32, f32, f32) -> Option<Msg> + Send + Sync>;
102
103/// Rect absoluto del nodo (en coordenadas físicas del frame). Lo
104/// recibe el callback de [`View::paint_with`] para que pueda
105/// posicionar sus primitivas custom dentro del nodo.
106#[derive(Debug, Clone, Copy, Default)]
107pub struct PaintRect {
108    pub x: f32,
109    pub y: f32,
110    pub w: f32,
111    pub h: f32,
112}
113
114/// Callback de pintura custom. El runtime lo invoca durante el paint
115/// del nodo (entre el `fill`/`image` y el `text`) con el `Scene` vivo
116/// + el `Typesetter` cacheado del runtime + el rect absoluto del nodo.
117/// Pensado para "canvas elements" tipo `dominium-canvas`,
118/// `pluma-editor` (osciloscopio de coherencia), `cosmos` (charts).
119///
120/// El `Typesetter` se pasa porque crearlo por frame es caro
121/// (`FontContext::new` enumera las fontes del sistema vía fontique).
122/// Los callers que no necesiten texto pueden ignorar el argumento.
123///
124/// El callback no debe llamar a `scene.push_layer` sin un `pop_layer`
125/// correspondiente, ni reset el scene — sólo agregar primitivas que
126/// pertenezcan al rect del nodo.
127pub type PaintFn = Arc<
128    dyn Fn(&mut vello::Scene, &mut llimphi_text::Typesetter, PaintRect) + Send + Sync,
129>;
130
131/// Callback de pintura GPU directo, sin vello intermedio. Recibe el
132/// `device`/`queue` ya construidos por el runtime más un
133/// `CommandEncoder` y la `TextureView` del frame (la intermediate
134/// `Rgba8Unorm` de `WinitSurface`), todo durante el paint del nodo.
135///
136/// El caller abre su propio `begin_render_pass` con `LoadOp::Load` para
137/// no sobrescribir lo que ya pintó vello, dibuja sus primitivas y
138/// cierra el pass. El runtime se encarga de dispatchear (`queue.submit`)
139/// el encoder ya con todas las pasadas de todos los nodos acumuladas —
140/// es un solo submit por frame.
141///
142/// **Orden de pintura en Fase 1**: todos los `gpu_painter` corren
143/// DESPUÉS de la pasada completa de vello (fill, image, painter,
144/// text) sobre el `mounted` tree. Entre sí mantienen el orden DFS
145/// pre-orden. Si una app necesita pintar texto **encima** del render
146/// GPU directo, la forma idiomática es ponerlo en `App::view_overlay`,
147/// que se renderiza como una segunda Scene de vello encima de todo.
148///
149/// Pensado para apps con volumen masivo de primitivos (cosmos
150/// starfield Gaia, tinkuy particle viewer, nakui viewport, pineal
151/// denso) — el hook que paga el costo de mantener pipelines WGSL
152/// propias en `llimphi-raster` (ver `02_ruway/llimphi/SDD.md`
153/// §"Roadmap — GPU directo wgpu").
154pub type GpuPaintFn = Arc<
155    dyn Fn(
156            &wgpu::Device,
157            &wgpu::Queue,
158            &mut wgpu::CommandEncoder,
159            &wgpu::TextureView,
160            PaintRect,
161            (u32, u32),
162        ) + Send
163        + Sync,
164>;
165
166/// Nodo de la vista declarativa. Estilo de layout (taffy) + relleno opcional
167/// (vello) + texto opcional (skrifa+vello) + Msg al click opcional + hijos.
168pub struct View<Msg> {
169    pub style: Style,
170    pub fill: Option<Color>,
171    /// Relleno cuando el cursor está sobre este nodo. Sin valor (`None`)
172    /// = no se reacciona al hover.
173    pub hover_fill: Option<Color>,
174    pub radius: f64,
175    pub text: Option<TextSpec>,
176    /// Imagen a pintar dentro del rect del nodo. Se centra y escala
177    /// preservando aspect ratio (`min(rect.w/img.w, rect.h/img.h)`).
178    /// El alfa por píxel de la imagen y el `Image::alpha` global se
179    /// respetan; el `fill` (si lo hay) se pinta debajo como background.
180    pub image: Option<Image>,
181    /// Callback de pintura custom. Si está presente, el runtime lo
182    /// invoca durante el paint del nodo con el `Scene` vivo + el rect
183    /// absoluto. Pensado para "canvas elements" (dominium, pluma,
184    /// cosmos) que pintan primitivas custom no expresables como una
185    /// composición de Views.
186    pub painter: Option<PaintFn>,
187    /// Pintor GPU directo. Se invoca DESPUÉS de la pasada vello del
188    /// frame; comparte tree y orden DFS con los demás. Ver
189    /// [`GpuPaintFn`].
190    pub gpu_painter: Option<GpuPaintFn>,
191    pub on_click: Option<Msg>,
192    /// Handler de click que recibe la posición **relativa al rect del
193    /// nodo** (esquina superior-izquierda del nodo = `(0, 0)`). Útil
194    /// para canvas elements que quieren mapear el click a coordenadas
195    /// de mundo. Si está presente, gana sobre `on_click`. Devolver
196    /// `None` no dispara update.
197    pub on_click_at: Option<ClickAtFn<Msg>>,
198    /// Equivalente a `on_click` pero para el botón derecho del ratón.
199    /// Pensado para menús contextuales: el nodo declara qué `Msg`
200    /// emitir cuando se le hace right-click, y la app abre el overlay
201    /// con el menú.
202    pub on_right_click: Option<Msg>,
203    /// Variante posicional de [`Self::on_right_click`]. Útil para
204    /// grillas que necesitan saber *qué celda* del rect recibió el
205    /// click derecho (la celda no es un nodo aparte, sino una región
206    /// dentro del nodo). Si está presente, gana sobre `on_right_click`.
207    pub on_right_click_at: Option<ClickAtFn<Msg>>,
208    /// Equivalente a `on_click` pero para el botón del medio del ratón
209    /// (rueda presionada). Pensado para abrir en pestaña nueva — los
210    /// browsers usan middle-click como atajo equivalente a Ctrl+Click.
211    pub on_middle_click: Option<Msg>,
212    /// Handler de drag. Si está presente, este nodo arrastra (y NO emite
213    /// `on_click` al presionar — un nodo es uno u otro).
214    pub drag: Option<DragFn<Msg>>,
215    /// Variante de drag que recibe la posición inicial del press relativa
216    /// al rect del nodo. Gana sobre `drag` si ambos están presentes.
217    pub drag_at: Option<DragAtFn<Msg>>,
218    /// Payload `u64` que viaja con el drag iniciado sobre este nodo. Lo
219    /// recibe el handler [`Self::on_drop`] del drop target. Sin payload,
220    /// el drag funciona igual pero ningún drop target reacciona.
221    pub drag_payload: Option<u64>,
222    /// Handler invocado al soltar un drag sobre este nodo (drop target).
223    pub on_drop: Option<DropFn<Msg>>,
224    /// Color a pintar mientras un drag activo está hovereando este drop
225    /// target. Sobrepone a `fill`/`hover_fill` cuando aplica.
226    pub drop_hover_fill: Option<Color>,
227    /// Si `true`, los descendientes se recortan al rect del nodo (vía
228    /// `scene.push_layer` con `Mix::Clip`). El hit-test también respeta
229    /// el recorte: clicks fuera del rect ignoran a los hijos.
230    pub clip: bool,
231    /// Msg a emitir cuando el cursor entra al rect del nodo (transición
232    /// no-hover → hover). Útil para previews tipo "URL del link al
233    /// pasar el mouse".
234    pub on_pointer_enter: Option<Msg>,
235    /// Msg a emitir cuando el cursor sale del rect del nodo.
236    pub on_pointer_leave: Option<Msg>,
237    /// Handler de rueda local. Si está presente y el cursor cae sobre este
238    /// nodo, el runtime lo invoca antes del `App::on_wheel` global; un
239    /// `Some(Msg)` consume el evento. Base de las áreas de scroll
240    /// autocontenidas. Ver [`ScrollFn`].
241    pub on_scroll: Option<ScrollFn<Msg>>,
242    /// Marca este nodo como **enfocable** con el id opaco `u64`. El runtime
243    /// mantiene el foco (uno por ventana) y lo mueve con Tab/Shift+Tab en
244    /// orden de árbol (pre-orden) y al clickear un nodo enfocable; notifica
245    /// a la app vía `App::on_focus` para que pinte el ring y rutee el
246    /// teclado. El id lo elige el caller (índice de campo, hash, etc.).
247    pub focusable: Option<u64>,
248    /// Opacidad multiplicada sobre TODO el subtree (este nodo + hijos),
249    /// en `[0.0, 1.0]`. Se realiza con `scene.push_layer(Mix::Normal, a, …)`
250    /// alrededor del rect del nodo: el subárbol se rasteriza en una capa
251    /// intermedia y se compone al alfa indicado contra lo que ya hay
252    /// detrás. `None` = sin capa (caso de la abrumadora mayoría de
253    /// nodos). Útil para fade-in/out de overlays, ghosts mientras se
254    /// arrastra, modales que aparecen, panels "vidrio". Note que la
255    /// composición tiene costo (allocate + blit), por lo que sólo
256    /// poblar este slot cuando hace falta — no es un atributo gratis.
257    pub alpha: Option<f32>,
258    /// Transformación afín 2D aplicada a este nodo y todo su subtree
259    /// **alrededor del centro de su propio rect** (convención CSS
260    /// `transform-origin: 50% 50%`). El runtime resuelve el centro en
261    /// `paint` (sólo entonces conoce el layout computado) y compone
262    /// `T(centro) · transform · T(-centro)` sobre la transformación
263    /// acumulada del padre, así nodos anidados transforman en el espacio
264    /// ya transformado de su ancestro — igual que CSS. `None` = identidad
265    /// (la abrumadora mayoría de nodos). Pensado para `transform`/
266    /// `@keyframes` CSS de puriy (rotate/scale/translate). El hit-test
267    /// **respeta** el afín (un nodo transformado recibe clicks donde se ve
268    /// pintado). Limitación restante: los `painter`/`runs` custom no heredan
269    /// el afín, y la posición local que reciben los handlers `*_at` se
270    /// reporta en espacio de pantalla, no en el espacio local del nodo.
271    pub transform: Option<Affine>,
272    /// Texto de **tooltip**: si está, el runtime/cliente puede mostrar un
273    /// rótulo flotante cuando el cursor se posa sobre este nodo. Llimphi sólo
274    /// transporta el dato hasta el [`MountedNode`]; *quién* lo pinta (un overlay
275    /// del runtime, una surface popup del cliente) lo decide el consumidor. El
276    /// hit-test de hover ya localiza el nodo bajo el cursor. `None` = sin tip.
277    pub tooltip: Option<String>,
278    pub children: Vec<View<Msg>>,
279}
280
281/// Versión "instalada" del árbol: cada nodo tiene su NodeId de taffy, color
282/// y handler. Se mantiene en orden de inserción (recorrido pre-orden), así
283/// el hit-test puede iterar al revés para honrar el orden de pintado.
284///
285/// `pub` (con campos `pub`) porque el runtime (llimphi-ui) lee el árbol
286/// montado para hit-test y para la pasada GPU directa, pero vive en otro
287/// crate. No se construye fuera de [`mount`].
288pub struct Mounted<Msg> {
289    pub root: NodeId,
290    pub nodes: Vec<MountedNode<Msg>>,
291    /// Contenido de texto por nodo-hoja, para que el runtime lo mida con
292    /// parley durante `compute_with_measure` y taffy reserve el alto real
293    /// del texto envuelto (varias líneas) en vez de una sola. Sin esto un
294    /// párrafo que envuelve a N líneas se aplastaría en la altura de una
295    /// (el bug clásico de "textos aplastados"). Sólo se pueblan hojas con
296    /// texto uniforme (sin `runs` multicolor, que el caller dimensiona).
297    pub text_measures: HashMap<NodeId, TextMeasure>,
298}
299
300/// Datos de un nodo-hoja de texto necesarios para medirlo (shaping +
301/// line-break) sin volver a tocar el `View`. Lo consume el runtime en la
302/// función de medición que le pasa a [`LayoutTree::compute_with_measure`].
303#[derive(Clone)]
304pub struct TextMeasure {
305    pub content: String,
306    pub size_px: f32,
307    pub alignment: llimphi_text::Alignment,
308    pub italic: bool,
309    pub font_family: Option<String>,
310    pub line_height: f32,
311}
312
313pub struct MountedNode<Msg> {
314    pub id: NodeId,
315    pub fill: Option<Color>,
316    pub hover_fill: Option<Color>,
317    pub radius: f64,
318    pub text: Option<TextSpec>,
319    pub image: Option<Image>,
320    pub painter: Option<PaintFn>,
321    pub gpu_painter: Option<GpuPaintFn>,
322    pub on_click: Option<Msg>,
323    pub on_click_at: Option<ClickAtFn<Msg>>,
324    pub on_right_click: Option<Msg>,
325    pub on_right_click_at: Option<ClickAtFn<Msg>>,
326    pub on_middle_click: Option<Msg>,
327    pub drag: Option<DragFn<Msg>>,
328    pub drag_at: Option<DragAtFn<Msg>>,
329    pub drag_payload: Option<u64>,
330    pub on_drop: Option<DropFn<Msg>>,
331    pub drop_hover_fill: Option<Color>,
332    pub clip: bool,
333    pub on_pointer_enter: Option<Msg>,
334    pub on_pointer_leave: Option<Msg>,
335    pub on_scroll: Option<ScrollFn<Msg>>,
336    pub focusable: Option<u64>,
337    pub alpha: Option<f32>,
338    /// Transformación afín 2D del nodo (alrededor del centro de su rect).
339    /// Ver [`View::transform`]. `paint` la compone con la del padre.
340    pub transform: Option<Affine>,
341    /// Texto de tooltip de este nodo (ver [`View::tooltip`]). El consumidor lo
342    /// lee tras un hit-test de hover para pintar el rótulo flotante.
343    pub tooltip: Option<String>,
344    /// Índice (exclusivo) del fin del subárbol en `Mounted::nodes`. Los
345    /// descendientes ocupan `[idx + 1, subtree_end)`. Hace de "barrera" en
346    /// paint/hit_test para `pop_layer` y para saltar subárboles enteros.
347    pub subtree_end: usize,
348}