# ActiveUix
`active-uix` es la raiz de composicion de UIX. Su responsabilidad no es ser
otra capa de comportamiento, sino entregar a `morfo` , `soma` , `sema` y `eidos`
los servicios minimos que necesitan sin que los componentes conozcan
`ActiveApp` directamente.
## Handoff 2026-05-14
La regla de ownership queda cerrada:
> Solo los composition roots crean servicios compartidos. Si hay `ActiveApp`,
> `attachActiveUix(app)` consume sus servicios y falla si falta alguno
> requerido. Si no hay app, `createActiveUix(...)` es el composition root local
> y crea los servicios/prefs de UIX. `morfo`, `soma`, `sema`, `eidos` y los
> componentes no crean `dom`, `langs`, `prefs`, `format` ni equivalentes.
La revision de naming queda cerrada asi: `events` es el nombre publico del
motor perceptivo en `ActiveUix` y tambien el nombre del servicio que
`defineUixServices(...)` registra en `ActiveApp` . `semantic` queda reservado
para el payload declarativo de `morfo.events[].semantic` , no para servicios
runtime. `morfo.translations` queda como catalogo declarativo owned por el
componente. `prefs` es el unico nombre para preferencias: `ActiveUix` expone
el `ActivePrefs` bruto y las capas inferiores consumen vistas acotadas cuando
no deben mutar.
## Boot paths actuales
`createActiveUix(options)` compone un runtime standalone:
- crea `logger` , `timers` , `bus` y `prefs` ;
- el `bus` usa `createSvelteEngineBus({ logger, clock: timers.clock })` ,
igual que `ActiveApp` , para que los listeners corran bajo `untrack` ;
- crea `langs` , `dom` o `disabledDom` , `format` y `events` segun opciones;
- conserva `portal` como target generico de portales para que cada capa lo
adapte a su API sin acoplar `active-uix` a esa capa;
- registra traducciones comunes y `morfo.translations` .
`attachActiveUix(app, options)` se adjunta a un `ActiveApp` externo:
- reutiliza `app.prefs` , `app.langs` , `app.dom` y `app.format` si existe;
- exige `app.langs` y `app.dom` ; si faltan, lanza error de configuracion;
- no vuelve a suscribir `langs` a `prefs.language` : esa conexion pertenece
a `defineActiveLangs` dentro de `ActiveApp` ;
- registra traducciones comunes y `morfo.translations` ;
- no posee el lifecycle del `app` .
## Contratos actuales
| Modulo | Minimo requerido | Opcional | Fallback si falta | Error si falta |
| ------------------------ | ----------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------- |
| `ActiveUix` standalone | `langs` config | `format` , `events` , `portal` , `dom:false` | crea `prefs` , core services y, si `dom:false` , `disabledDom` local | falta config `langs` |
| `ActiveUix` attach | `ActiveApp` core + services `langs` , `dom` | `app.format` , app event engine, `portal` | ninguno para servicios requeridos | falta `langs` o `dom` en app |
| `SomaRuntime` | `dom` desde `ActiveUix` | event engine, `langs` , `format` | ninguno propio | morfo/event/part inexistente |
| `Sema` desde `ActiveUix` | `dom/projector` inyectado por `ActiveUix` | `sound` , `haptic` | ninguno propio de servicios UIX | por definir para uso directo fuera de `ActiveUix` |
| `Eidos` | `dom` si `applyDom` | `langs` , `format` , `prefs` , mode/density sources | `applyDom:false` permite render/serializar sin DOM | falta `dom` con `applyDom` activo; componentes visuales fallan si leen un servicio no inyectado |
| `ADom` | superficie `ActiveDom` | breakpoints/window | `disabledDom` en UIX | por definir fuera de UIX |
## Decisiones cerradas y riesgos abiertos
1. `dom:false` solo degrada en standalone: `ActiveUix` expone un
`disabledDom` local y no deja a Sema/events caer a escrituras directas.
2. En attach mode no hay creacion compensatoria: si la app no tiene `dom` ,
`attachActiveUix(app)` falla.
3. Standalone usa el mismo bus Svelte-aware que `ActiveApp` .
4. Attach mode no duplica la suscripcion `prefs.language -> langs` .
5. `langs` no es `locale` : `prefs.language` alimenta traducciones;
`prefs.locale` alimenta formatos.
6. `prefs.direction` es la preferencia efectiva de direccion; `html[dir]` es
solo su proyeccion DOM.
7. Los wrappers/componentes no deben ser el lugar donde se resuelvan estas
politicas. Primero se cierra el contrato de la raiz activa.
8. `frontend` no es capa obligatoria de UIX. Queda como servicio legacy
opt-in de `ActiveApp` . `ActiveUix` no proyecta preferencias al DOM:
`arts/prefs` proyecta lo transversal y `ActiveEidos` proyecta lo visual.
9. `ActiveUix` no crea ni conoce `Soma` ni `Eidos` : `Soma.create(...)` crea
su scope y `Soma.runtime(...)` ; `ActiveEidos.create(...)` crea el scope
visual si la app necesita CSS runtime.
## Boot de una shell UIX
Una shell que usa componentes visuales debe cablear tres piezas de forma
explicita:
```ts
const uix = createActiveUix({ langs, prefs: { schema } });
setActiveUix(uix);
Soma.create();
const prefsProjection = createActivePrefsDomProjection({
prefs: uix.prefs,
dom: uix.dom
});
const eidos = ActiveEidos.create({
theme: 'base',
modeSource,
applyDom: true
});
```
`prefsProjection` es el dueño de `dir` , `data-motion` , `data-sound` y
`data-haptic` . `ActiveEidos` es el dueño de `data-theme` , `data-mode` y
`data-density` . No escribir `uix.prefs.setIntent('theme', ...)` : `theme` no
existe en el preset core de UIX y provocara `prefs::unknown_dimension` .
## Regla de trabajo vigente
Tras cerrar P1, siguen vigentes estas restricciones:
- no tocar `src/uix/eidos/components/*` ;
- no crear nuevas fachadas internas;
- no introducir `Engine*` /`Active*` por simetria decorativa;
- cualquier cambio debe justificar que contrato minimo aclara.
