Plugins y extensiones
El estándar de plugins de equisdots, el hub de 63 plugins, el descubrimiento por carpetas, la activación, los puntos de extensión y la CLI.
equisdots se construye con repositorios pequeños, y el sistema de plugins es la
forma de añadir funciones al escritorio sin editar los hosts. Un plugin es una
función autocontenida declarada por un manifiesto plugin.json: puede traer una
página de ajustes, un módulo de barra, un panel, una barra completa, atajos,
scripts, un adaptador de host o caras de widgets de escritorio.
El estándar lo implementan cuatro repositorios:
| Repositorio | Rol |
|---|---|
| plugins | El estándar, la carpeta con los 63 plugins, el registro de instalación y las pruebas de humo. |
| plugin-api | Esquema normativo del manifiesto, versión de la API y evaluadores de compatibilidad en bash/Lua. |
| plugin-sdk | Kit de ejecución: PluginHost, Settings reactivos, superficies, kit de widgets y API Lua mod. |
| transformpath | Notas de arquitectura, registro de decisiones y estado de la migración. |
Nyx y timex son plugins con repositorio propio. El resto del conjunto convertido
vive en equisdots/plugins/plugins/.
Estado: el estándar está en
branch/experimentaly es un POC funcional. Nyx, timex, screenshots y el editor de atajos ya son superficies reales; la API y el SDK se versionan en paralelo (plugin-api.json: API1.0.0, shell0.1.0).
Qué puede aportar un plugin
| Superficie | Clave del manifiesto | Ejemplo |
|---|---|---|
| UI siempre visible (overlay, isla) | host |
isla de mascotas Nyx |
| Página de ajustes | settings.page |
Plugins → Nyx, Timex |
| Panel / popup | provides.panels.<name> |
calendario, portapapeles, lector RSS |
| Módulo de barra | provides.bar.modules.<id> |
grabación, clima, sysmon |
| Barra completa | provides.bar.provider |
Samurai Bar, POC hello-bar |
| Caras de widgets de escritorio | provides.widgets.faces |
widget del clima de timex |
| Especies y tarjetas de mascotas | provides.mascots |
catálogo de especies de Nyx |
| Fragmento del compositor | hypr.lua |
atajos, startup, entorno |
| Entrada Quickshell independiente | standalone |
overlay de capturas |
provides es libre y los hosts lo pasan sin tocarlo. Cada consumidor documenta
sus claves; el estándar nunca conoce nombres de funciones como “mascots” o
“weather”.
Manifiesto
{
"id": "nyx",
"name": "Nyx",
"version": "0.1.0",
"author": "equisdots",
"description": "Mascot island and control-center notch for the shell",
"type": "shell",
"compat": { "shell": ">=0.1.0" },
"toggle": "mascots.enabled",
"settings": { "page": "settings/NyxPage.qml", "label": "Nyx" }
}
ides la identidad: estable, única globalmente e igual al nombre de carpeta.typeesshell,hypr,mixedocli.compatlo aplica el escaneo:{ "hyprland": ">=0.55", "shell": ">=0.1.0" }. Un plugin incompatible se lista pero nunca se monta;dots plugins addlo rechaza salvo con--force.togglenombra el interruptor maestro propio del plugin (por defectoplugins.<id>.enabled). Nyx apunta amascots.enabledpara tener un solo interruptor.defaultsnombra un fragmento de ajustes propiedad del plugin;dotssiembra el archivo de ajustes del plugin, nunca elsettings.jsoncentral.
El JSON Schema completo vive en plugin-api/schema/plugin.schema.json.
Descubrimiento y activación
Los hosts escanean dos carpetas; ningún código de host conoce ids de plugins:
| Carpeta | Propietario | Prioridad |
|---|---|---|
~/.config/hypr/plugins/<id>/ |
gestionada por dots |
|
~/.config/hypr/plugins-user/<id>/ |
usuario | gana en colisiones de id |
Cualquier directorio con un plugin.json es un plugin. Que un plugin de usuario
solape uno gestionado es intencionado, pero las colisiones nunca son silenciosas:
el escaneo informa de copias shadowed y dirMismatch, el cargador registra
status: "collision", el gestor avisa en la tarjeta y dots doctor informa de
duplicados del registro.
Dos interruptores mantienen la propiedad clara:
| Interruptor | Clave | Posee |
|---|---|---|
| Maestro | toggle o plugins.<id>.enabled |
toda la función; los hosts montan solo mientras está activo |
| Menú de configuración | plugins.<id>.config (por defecto true) |
si la página aparece en el grupo Plugins |
El valor efectivo por defecto es defaultEnabled (opt-in, false salvo que se
declare). El cambio en vivo recarga el fragmento del compositor y los vigilantes
del shell aplican el ajuste; no se reinstala nada.
Convención de despliegue
Un plugin gestionado se despliega en dos piezas:
repositorio completo -> ~/.config/hypr/scripts/quickshell/ui/plugins/<id>/
subconjunto runtime -> ~/.config/hypr/plugins/<id>/
plugin.json + hypr.lua + scripts/
La copia del árbol del shell es la cara UI que carga Quickshell. La carpeta del
registro es lo que leen el descubrimiento y el cargador del compositor. Los
plugins de usuario se quedan en plugins-user/ y deben ser autocontenidos.
Puntos de extensión
Los hosts implementan solo mecanismos genéricos:
PluginsCatalogescanea manifiestos, resuelveenabled,configy la ruta de UI.ui/PluginHosts.qmlmonta elhosty/o la barra completa de cada plugin gestionado activo. Los hosts pueden publicar rectángulosframeObstaclepara que el marco de pantalla se adapte.- Grupo Plugins del panel de ajustes: gestor más una página dinámica por
plugin (
p_<id>), cargada desdesettings.page. - Paneles:
ui/Main.qmlresuelveprovides.panels.<name>;qs_manager toggle <name>y los módulos de barra siguen funcionando. - Módulos de barra: el motor de zonas resuelve
provides.bar.modules.<id>; el núcleo conserva el id del hueco, el diseño y la configuración del usuario. - Cargador de Hyprland:
plugins.luaevalúa cadahypr.luaactivo con unpcall, así que un plugin roto nunca aborta la sesión. Los resultados van a~/.cache/equisdots/plugins-report.json.
El editor de atajos
Cada mod.bind(key, dispatcher, { label, id }) se registra con un id estable, la
tecla efectiva y la tecla por defecto. El plugin keybinds muestra los atajos de
todos los plugins y permite reasignar o silenciar uno solo. Las anulaciones viven
en el archivo de ajustes del plugin (<scope>.binds.<id> = "KEY" o false);
el plugin posee la acción y el usuario la tecla. Los atajos del núcleo se listan
solo lectura y no se pueden capturar.
El hub de 63 plugins
equisdots/plugins/plugins/ concentra el conjunto convertido. Incluye:
- Por defecto: screenshots + grabación, timex, lector RSS, portapapeles, quicknotes, búsqueda de archivos, sysmon y keybinds.
- Herramientas de escritorio: dock, calculadora, selector de color, selector de glifos, conversor de unidades, visor JSON, snippets, tareas, pomodoro, reloj mundial, panel y temas de xfetch.
- Módulos de barra: batería, brillo, caps lock, frecuencia de CPU, cripto, disco, DND, Docker, ventilador, GitHub, git, GPU, kernel, carga, correo, memoria, micrófono, media, luz nocturna, actualizaciones, procesos, swap, torrents, uptime, VPN y más.
- Barras completas: la Samurai Bar monocroma y el POC
hello-bar.
Nyx y timex viven en sus propios repositorios y se referencian desde el registro, nunca se copian al hub.
CLI
dots plugins # instalados: id, nombre, versión, tipo, estado
dots plugins available # registro: instalados vs disponibles
dots plugins add <id> # descarga, despliega por convención y activa
dots plugins add <id> --no-enable --force
dots plugins remove <id>
dots plugins enable <id>
dots plugins disable <id>
dotsniri replica la misma superficie para el stack de niri. La página del gestor
lee la copia del registro que dots despliega en el árbol del shell, así que los
plugins disponibles también se instalan desde la UI.
Comprobaciones y aislamiento de fallos
No hay CI. Las puertas locales son:
equisdots/plugins/tests/smoke.sh # manifiestos, qmldir, escaneo, ids, registro
hyprland/tests/plugins_loader_test.sh # cargador, anulaciones de atajos, colisiones
dotsniri doctor --self-test # sintaxis del toolkit
Un plugin roto queda aislado: un hypr.lua defectuoso lo captura pcall, una
página del shell rota no carga, y borrar un plugin deja claves huérfanas
inofensivas. El escritorio siempre sobrevive; el peor caso es una función
ausente en silencio.
Escribir un plugin
- Copie
equisdots/plugins/plugins/_template/y asigne unidúnico. - Añada
plugin.json,defaults.jsony, opcionalmente,hypr.lua,scripts/,settings/<Page>.qml,host/o QML de panel. - Pruebe en local en
~/.config/hypr/plugins-user/<id>/. - Ejecute
equisdots/plugins/tests/smoke.sh. - Registre el plugin en
registry.jsonsolo si debe instalarse desde el hub; los plugins con repositorio propio se referencian porsource.
Páginas relacionadas
- Shell Quickshell para los mecanismos de host y los paneles.
- Isla de mascotas Nyx para el primer plugin y su regla de extensión.
- Arquitectura y repositorios para el mapa completo.