Arquitectura y repositorios
Cómo encajan los repositorios de equisdots, los contratos compartidos en los que se apoyan y las decisiones que hay detrás.
equisdots es un conjunto de repositorios pequeños con un propietario claro
cada uno, unidos por dos contratos compartidos: settings.json para la
configuración y los archivos de paleta para el color. Esta página traza un mapa
de los repositorios, el flujo de datos y los invariantes en los que se apoyan
las piezas.
Repositorios y rutas de instalación
| Repositorio | Rol | Ubicación de la carga útil |
|---|---|---|
| dots | Meta instalador, actualizador, diagnóstico | ~/.local/bin/dots |
| hyprland | Configuración y scripts del compositor | ~/.config/hypr |
| niri | Configuración (KDL) y scripts del compositor niri | ~/.config/niri |
| niri-meta | Meta instalador, actualizador, diagnóstico (dotsniri) |
~/.local/bin/dotsniri |
| niri-shell | Overlay del shell (backend Niri) | se fusiona en el shell |
| nyx-niri | Overlay de Nyx (neutral al compositor) | se fusiona en el shell |
| niri-login | Entrada de sesión Wayland | /usr/share/wayland-sessions |
| shell | Interfaz Quickshell | ~/.config/hypr/scripts/quickshell |
| nyx | Plugin de isla/notch de mascotas | .../quickshell/ui/plugins/nyx |
| palettes | Datos de paletas y esquema | .../quickshell/dock/palettes |
| background | Fondos curados y catálogo de escenas | asset de release background.zip |
| theme-sync | Motor de temas entre aplicaciones | ~/.local/bin/theme-sync |
| davinci | Núcleo de fondos de pantalla | ~/.local/bin/davinci |
| timex | Plugin de clima/hora (motor, calendario, isla de barra) | .../quickshell/ui/plugins/timex |
| xturing | Interfaz de ajustes de terminal | ~/.local/bin/xturing |
| plugins | Estándar, hub de 63 plugins y registro | .../quickshell/ui/plugins/<id> |
| plugin-api | Esquema, versión de API y evaluadores de compatibilidad | .../quickshell/plugin-api.json |
| plugin-sdk | PluginHost, Settings, superficies, Lua mod | .../quickshell/core/sdk |
| transformpath | Arquitectura y registro de decisiones de plugins | solo documentación |
| web | Sitio de documentación y previews | GitHub Pages |
| login | Pantalla de inicio de sesión SDDM | /usr/share/sddm/themes/x |
Los clones gestionados viven en ~/.local/share/equisdots/<repo> (el stack de
niri usa ~/.local/share/equisdots-niri/<repo>). Los wrappers de
~/.local/bin ejecutan los motores clonados, por lo que dots update cambia el
comportamiento sin tocar el wrapper.
hyprland y niri son los dos frontends de compositor; shell, nyx,
palettes, theme-sync, background, timex, davinci, los repositorios de
plugins y login son compartidos por ambos.
Un shell, dos compositores
El repositorio shell es Hyprland-primero; niri-shell y nyx-niri son
overlays que añaden lo que niri necesita y dejan intacto todo lo demás. El meta
de niri los fusiona en el shell desplegado, de modo que un solo árbol sirve a
ambas sesiones:
shell (base) + niri-shell + nyx-niri = ~/.config/hypr/scripts/quickshell
core/Compositor.qml no tiene ningún compositor fijo. Lee el entorno y elige
core/compositors/Niri.qml cuando XDG_CURRENT_DESKTOP contiene niri o hay
un NIRI_SOCKET definido; en caso contrario,
core/compositors/Hyprland.qml. Ambos backends implementan la misma superficie
— workspacesCommand, keyboardCommand, focusCommand, setWindowBorders,
switchWorkspace, cycleKeyboardLayout — más las llamadas neutras de
persistencia de core/Config.qml (persistKeybinds, persistStartup,
applyMonitors, resetMonitors, reload). Los widgets nunca ramifican por
compositor.
La raíz de datos compartida se queda en ~/.config/hypr en ambos compositores
(ajustes, paletas, fondos, shell); solo la salida del compositor se mueve a
~/.config/niri. Los scripts de niri leen la raíz compartida a través de
EQUISDOTS_CONFIG_DIR.
| Aspecto | Hyprland | niri |
|---|---|---|
| Espacios | hyprctl + .socket2.sock |
niri msg --json event-stream |
| Bordes | hyprctl eval |
generated/borders.kdl + recarga |
| Atajos / startup / apariencia | config/*.lua + recarga |
generated/user-*.kdl + recarga |
| Efectos / monitores | hyprctl getoption/eval, hl.monitor |
generated/*.kdl + recarga |
Los dos meta instaladores son independientes: dots posee el stack de Hyprland
(~/.local/share/equisdots) y dotsniri el de niri
(~/.local/share/equisdots-niri), y ambos conviven. Los overlays son
condicionales y reversibles: un archivo compartido solo se reemplaza por su
variante niri mientras se selecciona la sesión niri. Ver
Compositor niri.
Sistema de plugins
La capa de plugins se divide en cuatro contratos, de modo que hosts y plugins nunca importan las interioridades del otro:
| Repositorio | Contrato |
|---|---|
| plugin-api | Esquema de plugin.json, versión de API y evaluadores de compatibilidad |
| plugin-sdk | PluginHost, Settings reactivos, superficies, Lua mod |
| plugins | Estándar, hub de 63 plugins, registro y pruebas de humo |
| transformpath | Arquitectura, decisiones y estado de la migración |
Los hosts descubren plugins por carpeta (~/.config/hypr/plugins y
plugins-user), resuelven el manifiesto y montan solo los activos y
compatibles. Un plugin gestionado se despliega dos veces: el repositorio
completo en .../quickshell/ui/plugins/<id>/ (la cara UI) y el subconjunto
runtime (plugin.json, hypr.lua, scripts/) en
~/.config/hypr/plugins/<id>/. El shell monta hosts, paneles, módulos de barra
y barras completas genéricas; el cargador de Hyprland evalúa los fragmentos
hypr.lua bajo pcall. niri consume los mismos plugins mediante binds KDL
estáticos y el shell neutral al compositor.
Consulte Plugins y extensiones para el manifiesto, el ciclo de vida y la CLI.
Flujo de configuración
settings.json (single source of truth: bar, widgets, timex, plugins, ...)
| read/write atomically (tmp + mv), watched by the shell
|
+--> shell Config.qml -----------> live UI updates
+--> plugins scan -----------------> enabled/config/defaults
+--> xturing --------------------- terminal edits
+--> hyprland colors.lua ---------> border defaults at load
+--> theme-sync ------------------> active palette for every target
+--> timex -----------------------> provider, city, unit
+--> davinci --------------------> slideshow and wallpaper options
Las escrituras son atómicas para que los vigilantes de archivos sigan
funcionando: dots combina settings.json como valores predeterminados
distribuidos más los valores del usuario, xturing conserva las claves
desconocidas y el editor del shell aplica antirrebote a sus propias escrituras.
Flujo de paletas
palettes repo --> dock/palettes/{*.json, community/, index.json, schema.json}
|
settings.json bar.palette selects the slug (fallback: x)
|
+--------------------+--------------------+
| | |
shell Colors.qml theme-sync targets Hyprland colors.lua
| | |
bar, widgets, kitty, starship, window borders
lock screen nvim, vscode, gtk, (live via hyprctl eval)
qt, browsers, ...
|
xwww scenes (--palette equisdots)
Los consumidores nunca codifican colores; una escena que lee el mismo archivo de paleta concuerda con el resto del escritorio por construcción. Consulte Temas y paletas.
Flujo de fondos de pantalla
davinci (kernel CLI)
+--> xwww img ......... still images
+--> xwww scene run ... interactive scenes (JS, palette-driven)
+--> mpvpaper ......... video wallpapers
+--> current_wallpaper.png ... lock screen, SDDM
+--> current_scene, thumbs, slideshow state ... cache/state/run dirs
El selector de Quickshell es un frontend fino sobre la misma CLI. El shell, la
pantalla de bloqueo e init.sh solo consumen los archivos del contrato.
Arranque de la sesión
autostart.lua inicia xwww-daemon e init.sh; init.sh vuelve a aplicar la
escena registrada en current_scene cuando existe; en caso contrario, se
restaura el fondo de pantalla anterior. restore-monitors.sh vuelve a aplicar
el diseño guardado de monitores y lo reconcilia cada dos segundos. El shell y
sus vigilantes de datos se ejecutan después durante toda la sesión.
Invariantes de actualización
- Los clones gestionados son de solo lectura:
dotsdescargaorigin/mainy restablece por la fuerza. - Un clon con cambios sin confirmar nunca se despliega, por lo que una copia obsoleta no puede degradar archivos activos.
xwwwestá fijado a una versión;dots update/dots systemreinstalan cuando el binario en ejecución difiere, ydots doctorinforma de las discrepancias.settings.jsonnunca se regenera desde cero; siempre son valores predeterminados más anulaciones del usuario.
Consulte Actualización y diagnóstico para los detalles de los comandos.
Decisiones de diseño
- Configuración Lua de Hyprland (0.55+): archivos modulares con
require()y anulaciones en tiempo de ejecución; los cambios en vivo pasan porhyprctl eval, nunca reescribiendo archivos cargados a mitad de sesión. - Sin Matugen: las paletas son datos JSON fijos, así que los colores son predecibles y compartidos entre compositor, shell y aplicaciones.
- Tema SDDM estático: sin sudo en tiempo de ejecución y sin sincronización de paleta en la pantalla de inicio de sesión, lo que evita fallos de PAM.
- Las escenas se renderizan en el cliente xwww: el demonio sigue siendo un simple consumidor de fotogramas y el sandbox mantiene el código de las escenas solo en CPU, sin E/S ni entrada.
- Dos frontends de compositor, un shell:
hyprlandynirison intercambiables trascore/Compositor.qml; el shell, las paletas y Nyx son compartidos, la raíz de datos compartida se queda en~/.config/hypr, y el código específico de niri se distribuye como overlays reversibles (niri-shell,nyx-niri). - Los plugins son una capa de primera clase: el manifiesto es el único
contrato, los hosts no conocen ids de plugins, los puntos de extensión son
genéricos (
provides) y un plugin roto se aísla en vez de abortar la sesión. - Sin CI: cada repositorio incluye un script de comprobación local, que se ejecuta antes de hacer push.
Comprobaciones de desarrollo
| Repositorio | Comando | Comprueba |
|---|---|---|
| shell | scripts/check.sh |
qmllint sobre QML, node --check sobre JS |
| hyprland | scripts/check.sh |
luac -p sobre Lua, bash -n sobre scripts |
| niri | scripts/check.sh |
bash -n sobre scripts, balance de llaves KDL |
| niri-meta | dotsniri doctor --self-test |
bash -n del toolkit (funciona sin niri) |
| palettes | scripts/check.sh |
Consistencia del esquema y de index.json |
| theme-sync | scripts/check.sh |
compileall más una prueba de humo de la CLI |
| xturing | scripts/check.sh |
cargo fmt, clippy y pruebas |
| plugins | tests/smoke.sh |
Manifiestos, qmldir, escaneo, ids y registro |
| plugin-api | fixtures de evaluadores | Paridad semver entre bash y Lua |
| plugin-sdk | qmllint + pruebas Lua |
Kit de host y API mod |
Dependencias externas
La pila también instala desde fuera de la organización: xscriptor-colors/terminal (kitty y starship), xscriptor-colors/nvim, xscriptor-colors/vscode y x-ports/xwww (el demonio de fondos de pantalla y el motor de escenas).
Páginas relacionadas
- Contribución y seguridad para comprobaciones y notificación.
- Actualización y diagnóstico para el flujo de actualización.