equisdots
Menú

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: dots descarga origin/main y restablece por la fuerza.
  • Un clon con cambios sin confirmar nunca se despliega, por lo que una copia obsoleta no puede degradar archivos activos.
  • xwww está fijado a una versión; dots update/dots system reinstalan cuando el binario en ejecución difiere, y dots doctor informa de las discrepancias.
  • settings.json nunca 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 por hyprctl 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: hyprland y niri son intercambiables tras core/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

Editar esta página en GitHub