svelte-kit-vice/src/uix/README.md

# UIX

Documento corto de posicionamiento arquitectonico para `src/uix`.

Nota de continuidad más reciente:
[src/uix/CONTINUITY_2026-04-24.md](/G:/dev/svelte/vicen/src/uix/CONTINUITY_2026-04-24.md)

UIX no intenta ser "otra libreria de componentes". La apuesta es mas ambiciosa y
mas estructural: **separar capas que casi todos los frameworks actuales mantienen
mezcladas**.

En la mayoria de sistemas de UI, estas cosas viven pegadas:

- contrato publico del DOM
- comportamiento headless
- accesibilidad
- semantica del evento
- capa visual
- motores modales (sound, vibra, motion)
- integracion con servicios de app

UIX intenta partir ese bloque en piezas con fronteras fuertes.

---

## 1. La idea central

UIX modela la interfaz como varias capas cooperando, no como un unico componente
gigante que hace todo a la vez.

```text
App
├─ servicios transversales
│  └─ ADom
└─ componentes
   └─ capa estructural / semantica / comportamental / visual
```

La intuicion es esta:

- la estructura publica del componente no es lo mismo que su comportamiento
- la semantica de un evento no es lo mismo que su materializacion
- el DOM activo no es lo mismo que utilidades DOM puras
- la app no deberia acoplar motores modales entre si

UIX pone nombres y contratos explicitos a esas separaciones.

---

## 2. Las capas de UIX

### `Morfo`

Contrato estructural cross-layer del componente.

Define:

- partes
- `data-*`
- ARIA
- foco
- teclado
- eventos

No es prose ni runtime. Es la forma canonica publica del componente.

Ver: [src/uix/morfo/README.md](/G:/dev/svelte/vicen/src/uix/morfo/README.md)

### `Sema`

Vocabulario y contrato semantico.

No ejecuta sound, vibra ni CSS. Su trabajo es decir:

- que acciones existen
- que ocurrencias/eventos canónicos nombra el sistema
- como se relacionan esos nombres con el componente

En su version madura, `Sema` debe ser **vocabulario y validacion**, no runtime.

### `Soma`

Capa headless de comportamiento.

Gestiona:

- estado
- contexto
- a11y
- keyboard / pointer / focus
- emision de eventos hacia `ADom`

`Soma` no deberia conocer la implementacion concreta de los engines modales. Su
trabajo es emitir hechos del componente, no materializarlos.

Ver: [src/uix/soma/SOMA_ARCHITECTURE.md](/G:/dev/svelte/vicen/src/uix/soma/SOMA_ARCHITECTURE.md)

### `Eidos`

Capa visual.

Reacciona a contratos DOM y a senales reflejadas, pero no implementa la logica
headless del componente. Su responsabilidad es apariencia, no comportamiento.

### `ADom`

Runtime observable del DOM activo.

No es un helper DOM puro ni un semantic engine. Es el broker infrastructural de
senales DOM activas:

- recibe emisiones de `Soma`
- publica a listeners tipados
- refleja `data-event*` en el DOM
- evita que cada engine monte su propio observer para el mismo hecho

Ver: [src/uix/adom/README.md](/G:/dev/svelte/vicen/src/uix/adom/README.md)

### `uix/lib/dom`

Utilidades DOM puras o casi puras.

Aqui viven:

- `contains`
- `getDocument`
- `getWindow`
- foco
- traversal
- wrappers base de observers

No contiene el runtime activo. Ese papel pertenece a `ADom`.

---

## 3. Que hace distinto a UIX

### 3.1 El contrato estructural es una capa propia

En la mayoria de librerias, la estructura publica del componente esta dispersa:

- atributos en el provider
- roles en el render
- partes en CSS
- selector names en docs
- contratos en tests

UIX intenta concentrar eso en `Morfo`.

Eso no es una comodidad menor; cambia el tipo de sistema que puedes construir:

- docs derivadas del contrato
- validacion cross-layer
- menos drift entre headless y visual
- tooling mas fiable

### 3.2 La semantica no se mezcla con la ejecucion

UIX separa el **nombre de la ocurrencia** de su **materializacion modal**.

Eso permite que:

- sonido
- vibracion
- CSS
- motores futuros

usen el mismo vocabulario sin quedar pegados entre si.

### 3.3 El comportamiento headless no carga con toda la modalidad

`Soma` no deberia ser un mega-engine que sabe de todo:

- no sabe reproducir WAVs
- no sabe vibrar
- no sabe decidir la fisica perceptiva de cada canal

`Soma` emite. Los engines ejecutan.

### 3.4 El DOM activo es infraestructura de app, no detalle incidental

Muchos sistemas tratan el DOM como detalle local del componente.

UIX da un paso mas: reconoce que hay hechos transversales del DOM que varios
consumidores quieren escuchar, y por eso introduce `ADom`.

Eso permite:

- un solo punto de publicacion
- listeners tipados
- reflection uniforme en atributos
- menos `MutationObserver` duplicados
- mejor tooling y debug

### 3.5 La app compone servicios, no "super componentes"

UIX se apoya en un modelo donde la app compone servicios transversales y los
componentes los consumen. `langs`, `presentation`, `logger` y `ADom` viven mejor
como servicios de app que como dependencias ocultas dentro de cada componente.

---

## 4. Lo que UIX no es

UIX no es:

- una coleccion plana de componentes visuales
- un simple wrapper opinionated sobre primitives existentes
- un design system clasico donde visual, comportamiento y contratos viven juntos
- un semantic engine centralizado que ejecuta todas las modalidades
- un `EventEmitter` global disfrazado de arquitectura

Tampoco busca novedad gratuita.

La originalidad de UIX no esta en inventar nombres exoticos, sino en **separar
problemas reales** que otros sistemas suelen aceptar como un unico bloque.

---

## 5. Comparacion honesta con otros enfoques

### Frente a headless libraries clasicas

Librerias como Radix, Ariakit o React Aria resuelven muy bien comportamiento y
accesibilidad. Pero normalmente no separan:

- contrato estructural declarativo
- vocabulario semantico independiente
- runtime transversal de DOM activo

UIX quiere cubrir ese espacio.

### Frente a design systems clasicos

Muchos design systems tienen tokens, componentes y guidelines, pero la frontera
entre:

- estructura
- comportamiento
- visualidad
- semantica

queda difusa.

UIX intenta que cada una tenga una capa reconocible.

### Frente a engines modales aislados

Es relativamente comun encontrar sistemas de motion o sound por separado.

Lo raro es tener:

- headless primitives
- contrato estructural machine-readable
- vocabulario comun
- servicio de DOM activo
- engines modales desacoplados

trabajando juntos sin colapsar en un runtime monolitico.

---

## 6. Por que esto puede ser valioso

Si sale bien, UIX ofrece algo poco comun:

- mejor explicabilidad arquitectonica
- menos drift entre capas
- mas capacidad de validacion automatica
- mejor testabilidad
- mas libertad para introducir nuevos engines
- mas honestidad sobre que pertenece al framework y que pertenece al integrador

Especialmente importante:

**la coherencia cross-modal puede tratarse como responsabilidad del integrador, no
como una falsa promesa de un runtime centralizado que pretende saberlo todo.**

El framework puede proveer:

- vocabulario
- contratos
- transporte
- puntos de extension

Pero no debe fingir que puede decidir por todas las modalidades de todas las apps.

---

## 7. Los riesgos reales

UIX tambien tiene riesgos claros, y conviene decirlos sin adornos.

### 7.1 Exceso de capas

Si las fronteras no estan clarisimas, el sistema puede sentirse mas complejo de lo
que realmente resuelve.

### 7.2 Nombres sin disciplina

Si `Morfo`, `Sema`, `Soma`, `Eidos`, `ADom` no mantienen contratos nitidos, los
nombres se convierten en decoracion y no en arquitectura.

### 7.3 Invasion de responsabilidades

El peligro constante es que una capa intente hacer el trabajo de otra:

- `Sema` convirtiendose en runtime
- `Soma` convirtiendose en engine modal
- `ADom` convirtiendose en semantic engine
- `Eidos` acoplandose a detalles incidentales

UIX solo funciona si cada capa acepta sus limites.

### 7.4 Falta de precedentes

No hay demasiados sistemas con esta composicion exacta. Eso significa mas libertad,
pero tambien menos patrones externos que copiar. Hay que inventar con disciplina.

---

## 8. Reglas de dependencia

UIX debe preservar una direccion clara de acoplamiento.

Version simplificada:

```text
Morfo -> describe
Sema  -> nombra y valida sobre Morfo
Soma  -> implementa comportamiento y emite a ADom
ADom  -> transporta y publica
Eidos -> materializa visualmente
App   -> compone servicios y engines
```

Y, como regla general:

- `Morfo` no conoce `Soma`
- `Sema` no ejecuta engines
- `ADom` no conoce sonido ni vibracion
- `Soma` no conoce implementaciones modales concretas
- `Eidos` no duplica behavior headless

---

## 9. La diferencia en una frase

Si hubiera que resumir UIX en una sola idea, seria esta:

> UIX trata la interfaz no como un componente monolitico, sino como un sistema de
> capas con contratos explicitos entre estructura, semantica, comportamiento,
> visualidad y transporte de eventos activos.

Esa es la apuesta.

---

## 10. Orden de lectura sugerido

Para entender el sistema en su estado actual:

1. [src/uix/morfo/README.md](/G:/dev/svelte/vicen/src/uix/morfo/README.md)
2. [src/uix/soma/SOMA_ARCHITECTURE.md](/G:/dev/svelte/vicen/src/uix/soma/SOMA_ARCHITECTURE.md)
3. [src/uix/adom/README.md](/G:/dev/svelte/vicen/src/uix/adom/README.md)
4. [src/uix/terra/README.md](/G:/dev/svelte/vicen/src/uix/terra/README.md)
5. [src/uix/air/README.md](/G:/dev/svelte/vicen/src/uix/air/README.md)

La arquitectura final seguira cambiando, pero esta es la idea fundacional que
explica por que UIX no se parece demasiado a otros frameworks de UI.