active-svelte/docs/ecosistema_v2.md

# Ecosistema v2 - mejoras para completar cada modulo

Fuente usada: codigo, configuracion, tests, scripts y estructura real del repo. No se usa documentacion antigua como base.

## Lectura correcta

La version 2.0 no debe buscar "componentes v2 existentes", porque no hay una capa v2 ya montada. Lo que hay que definir es que le falta a cada modulo para que el ecosistema sea completo, usable y componible por encima de la 1.0.

La 1.0 debe cerrar estabilidad, build, typecheck, tests y API publica. La 2.0 debe convertir esos motores en una plataforma completa: componentes UI, devtools, presets, integraciones, adapters reales, contratos tipados y flujos de producto.

## Principios de v2

1. No reescribir nucleos que ya estan maduros. `sium` y `http`, por ejemplo, necesitan capas superiores e integraciones, no una reconstruccion del core.
2. Separar producto de demo/test/docs. Lo reutilizable debe vivir en `src/uix`, `src/arts`, `src/libs` o `src/svrs`, no en rutas de prueba.
3. Cada modulo debe exponer contrato publico, tests propios, fixtures, diagnostico y ejemplos minimos.
4. Las integraciones entre modulos deben ser oficiales: cache + http, sium + uix, perm + uix, prefs + frontend, logger + orca, storage + prefs/cache/session.
5. v2 debe traer experiencia de usuario y de desarrollador: devtools, inspectores, playgrounds, generadores y presets.

## Prioridades globales

### V2-P0 - Base antes de construir encima

- Cerrar los errores actuales de `npm run check` y `npm run build`.
- Eliminar usos de API vieja en rutas demo/test.
- Corregir scripts obsoletos, especialmente aliases antiguos del smoke bundle.
- Alinear Node local/CI y ampliar CI con `lint` y `test:aliases`.
- Congelar barrels publicos por modulo y marcar APIs internas.

### V2-P1 - Capa de producto

- Convertir `src/uix` en la libreria oficial de componentes.
- Crear componentes que usen los motores reales del ecosistema.
- Sustituir demos acopladas por playgrounds que consuman APIs publicas.
- Definir una `ActiveApp` canonica para ejemplos, docs y smoke tests.

### V2-P2 - Integraciones y adapters reales

- Async storage.
- Cache persistente.
- HTTP con cache/dedupe/retry/offline.
- Auth/session/perm con UI y flujos completos.
- Observabilidad transversal con logger/orca/bus/timer.

### V2-P3 - Devtools

- Inspector de `ActiveApp`.
- Timeline de bus/orca/logger/timer.
- Inspector de cache/storage/session.
- Simulador de permisos.
- Generador de formularios desde `sium`.

## Roadmap por modulo

### active-app

Estado: el nucleo ya compone servicios con dependencias, lazy/immediate y disposal ordenado. El problema v2 es hacerlo mas tipado, visible y extensible.

Mejoras v2:

- `AppSchema` exportable para que componentes y rutas no reciban `ActiveApp` generico con servicios `unknown`.
- Presets oficiales: `createClientApp`, `createServerApp`, `createDemoApp`, `createTestApp`.
- Registro de plugins/servicios con manifiesto de capacidades.
- Health graph de servicios: iniciado, lazy, error, disposed, dependencias y tiempo de arranque.
- Devtools de `ActiveApp` para inspeccionar servicios, dependencias y eventos de lifecycle.
- Migrador o capa compat temporal para detectar API vieja con errores claros.

### uix

Estado: `src/uix` existe pero esta vacio. Es el hueco mas grande del ecosistema.

Mejoras v2:

- Primitivas base: `Button`, `Input`, `Select`, `Checkbox`, `Switch`, `Dialog`, `Popover`, `Tabs`, `Tooltip`, `Toast`, `Table`, `Drawer`, `Menu`, `Command`.
- Componentes de formulario conectados a `sium`: `Form`, `Field`, `FieldGroup`, `AutoFields`, `ErrorSummary`, `SubmitBar`.
- Componentes de autorizacion conectados a `perm`: `Can`, `Cannot`, `Gate`, `PermissionBoundary`, `RoleBadge`.
- Componentes de sesion/auth: `LoginForm`, `SessionMenu`, `DeviceList`, `MfaPanel`, `AuthGuard`.
- Componentes operativos: `CacheInspector`, `LogViewer`, `ConnectionStatus`, `PrefsPanel`, `StorageBrowser`, `OrcaTimeline`.
- Contrato visual comun con `frontend`, `prefs`, `adom`, `lang` y `format`.

### sium

Estado: core potente, con introspeccion (`widget`, `widgetOptions`, `kind`, `wrappers`, `effects`, `shape`) y muchas pruebas. No necesita rehacer el nucleo.

Mejoras v2:

- Renderer oficial de formularios en `uix` usando `Form.AutoFields`.
- Registro de widgets por tipo de schema.
- Validacion async y validacion remota con estados de pending/cancelacion.
- Serializacion de schemas para compartir cliente/servidor.
- Generador de formularios, filtros y tablas desde metadata.
- Inspector visual de schema/result/issues para depuracion.
- Paquetes de wrappers comunes: password, money, date range, file, tags, address, permission selector.

### http

Estado: core suficiente y bien aislado por puertos. No necesita una reescritura v2.

Mejoras v2:

- Cliente tipado por endpoint, compatible con schemas de `sium` o contratos declarativos.
- Integracion oficial con cache: dedupe, stale-while-revalidate, invalidacion y tags.
- Retry/backoff/circuit breaker como presets, no como codigo repetido por consumidor.
- Upload/download con progreso, cancelacion y resume.
- Offline queue opcional usando storage/connection.
- Interceptores de auth/session y trace ids de logger.
- Mock server/record-replay para tests y demos.

### auth

Estado: servidor amplio, pero con errores de export/import y poca prueba directa en `libs/auth`.

Mejoras v2:

- MFA estable: TOTP, recovery codes, WebAuthn/passkeys.
- OAuth/OIDC adapters oficiales.
- Passwordless/magic-link.
- Administracion de sesiones y dispositivos.
- Auditoria de eventos de seguridad.
- UI en `uix`: login, register, reset password, MFA, device management.
- Contratos compartidos cliente/servidor con tests directos de `libs/auth`.
- Politicas configurables: lockout, password policy, token rotation, session binding.

### session

Estado: ciclo de vida trabajado, con integracion logger/bus. Falta llevarlo a producto completo.

Mejoras v2:

- Multi-session/profile switcher.
- Sincronizacion cross-tab con leader election.
- Bootstrap SSR/cliente bien tipado.
- Estrategias de refresh enchufables.
- Estado de sesion visible para UI: loading, refreshing, expired, degraded.
- Integracion con auth, perm, storage y logger.
- Panel de sesiones activas y cierre remoto.

### perm

Estado: motor y servidor existen; el cliente tiene solo un componente reusable claro (`Can.svelte`) y tests finos.

Mejoras v2:

- Familia UI: `Can`, `Cannot`, `Gate`, `PermissionBoundary`, `PermissionExplain`.
- Simulador de permisos para usuarios/roles/tenants.
- DSL o builder de politicas.
- Plantillas de roles y permisos por dominio.
- Batch prefetch y cache de permisos.
- Explicabilidad: por que se permite o deniega una accion.
- Integracion PEP/PDP clara para cliente, servidor y rutas.

### cache

Estado: runtime avanzado, pero hay una inversion de capas porque `arts/cache` importa desde `svrs/cache`.

Mejoras v2:

- Corregir frontera: motor compartido en `libs/cache` o separar claramente cliente/servidor.
- Adapters persistentes con `storage`.
- Integracion oficial con `http`.
- Invalidacion por tags, dependencias y eventos de `bus`.
- Prefetch, optimistic updates y rollback.
- Cache inspector en `uix`.
- Metricas: hit rate, stale, evictions, memory, errores de adapter.

### storage

Estado: adapters sincronicos. El propio codigo deja async adapters para v2.

Mejoras v2:

- Contrato async para IndexedDB, OPFS y backends remotos.
- Migraciones versionadas de datos.
- Namespaces y cuotas por modulo.
- Estrategias de eviction.
- Cifrado opcional para datos sensibles, dejando claro que storage no es una caja fuerte.
- Sincronizacion con session/prefs/cache.
- Inspector de storage en devtools.

### prefs

Estado: preparado para persistencia y preferencias, con senales de pending/error para async.

Mejoras v2:

- Hydration async con estados oficiales.
- Sincronizacion entre tabs y perfiles.
- Presets de preferencias por usuario/equipo.
- Merge server/client con resolucion de conflictos.
- Registro de preferencias por modulo.
- UI `PrefsPanel` generada desde metadata.
- Integracion completa con frontend/lang/format/storage.

### frontend

Estado: servicio de estado visual; hay desalineacion con density de prefs.

Mejoras v2:

- Sistema de design tokens: color, spacing, radius, shadow, typography, z-index.
- Theming SSR-safe para evitar saltos de primer render.
- Density unificada con prefs.
- Direccion LTR/RTL y reduced motion como contrato transversal.
- Breakpoints y viewport state publicos.
- Registro de temas y paquetes visuales.
- Integracion con `uix` como consumidor principal.

### adom

Estado: utilidades DOM, viewport, scroll/focus; buen candidato para sostener la capa UI.

Mejoras v2:

- Layer manager para dialog/popover/toast.
- Focus trap, focus restore e inert.
- Portal manager.
- Observers oficiales: resize, intersection, mutation.
- Scroll restoration por ruta/panel.
- Helpers ARIA y keyboard navigation.
- Test harness de accesibilidad para componentes `uix`.

### lang

Estado: basico y con poca cobertura directa.

Mejoras v2:

- Namespaces lazy por modulo.
- Reporte de claves faltantes y claves no usadas.
- Pseudo-locale para detectar textos rotos.
- MessageFormat 2.0 / MF2 como contrato moderno de mensajes, plurales, selectores y variantes.
- Extraccion de mensajes desde codigo.
- Bundles por idioma/modulo.
- Integracion con `sium` para mensajes de validacion y con `uix` para labels.

### format

Estado: bastante completo en numeros, fechas, monedas y unidades.

Mejoras v2:

- Relative time.
- ListFormat, DisplayNames y segmentos localizados.
- Perfiles de unidades por dominio.
- Conversiones de unidades donde tenga sentido.
- Integracion con timezone/calendar.
- Formatters declarativos para tablas/formularios.
- Cache de formatters coordinada con lang/prefs.

### logger

Estado: motor fuerte y grande. Falta explotarlo como observabilidad de plataforma.

Mejoras v2:

- Trace context compatible con `http`, `orca`, `bus` y `session`.
- Redaction policies para datos sensibles.
- Sampling y niveles por modulo.
- Transport health y backpressure.
- Live log viewer en `uix`.
- Export a OpenTelemetry o formato compatible.
- Correlacion de errores de build/runtime/devtools.

### bus

Estado: bus central solido.

Mejoras v2:

- Catalogo tipado de eventos por modulo.
- Validacion de payloads con schemas.
- Replay/recording para depuracion.
- Bridges cross-tab y servidor.
- Timeline visual en devtools.
- Politicas de error: retry, dead letter, fallback.
- Integracion con orca para orquestaciones declarativas.

### timer

Estado: servicio estable y probado.

Mejoras v2:

- Schedulers nombrados por prioridad.
- Cron/calendar schedules.
- Timers persistentes.
- Politica para background tabs.
- Integracion con performance budgets.
- Timer inspector en devtools.
- Coordinacion con orca para tareas cancelables.

### orca

Estado: engine avanzado. Ya hay senales de roadmap v2 como `replace-current`.

Mejoras v2:

- Politica `replace-current` / takeLatest con abort real.
- Visual timeline de eventos, acciones, fan-in y cancelaciones.
- Validacion de grafos/orquestaciones antes de runtime.
- Presets de orquestacion por dominio.
- Persistencia/replay de traces.
- Integracion con logger/bus/timer/http.
- Mercado interno de actions reutilizables.

### connection

Estado: modulo grande y avanzado, con tests y refactors recientes.

Mejoras v2:

- Canales multiplexados.
- Presence y heartbeats de estado.
- Offline queue con storage.
- Backpressure y flow control.
- Reauth/rekeying de conexiones vivas.
- Negociacion de protocolo/version.
- Request/reply validado con schemas.
- Dashboard de reconnect, latencia, cola y errores.

### svrs/auth

Estado: servidor amplio, pero con problemas actuales de imports/exports.

Mejoras v2:

- Handlers SvelteKit canonicos.
- Adapters DB oficiales.
- Migraciones y seeds.
- Hooks de auditoria y logger.
- OpenAPI o contratos HTTP generables.
- Test matrix por flujo: login, refresh, logout, MFA, recovery, device revoke.

### svrs/cache

Estado: existe, pero su frontera con `arts/cache` esta contaminada.

Mejoras v2:

- Separar motor comun de servidor.
- Adapters para Redis, memory, KV y edge.
- Invalidation bus server-side.
- Metrics endpoint.
- Politicas multi-tenant.
- Contract tests compartidos con cliente.

### svrs/perm

Estado: servidor funcional con cobertura limitada.

Mejoras v2:

- PDP server-side explicable.
- Adapters DB.
- Policy migrations.
- Batch authorization endpoint.
- Audit log de decisiones.
- Herramientas para simular usuario/tenant/recurso.

### libs

Estado: muchas piezas compartidas, barrels y contratos; algunos nucleos grandes tienen poca prueba directa.

Mejoras v2:

- Separar `public` e `internal`.
- API snapshots para barrels publicos.
- Contract tests por adapter.
- Fixtures reutilizables.
- Versionado semantico interno por modulo.
- Limpieza de exports ambiguos.
- Mayor cobertura directa en `libs/auth`, `libs/cache`, `libs/perm`, `libs/lang`.

### web

Estado: mezcla docs, demo, test pages y rutas temporales. No debe confundirse con producto.

Mejoras v2:

- Docs generadas desde metadata real de modulos.
- Playground unico con `ActiveApp` canonica.
- Route smoke tests.
- Matrix visual de modulos, servicios, dependencias y estado.
- Demos que consuman `uix` y APIs publicas, no implementaciones internas.
- Separar claramente `/docs`, `/playground`, `/test` y `/demo`.

## Integraciones clave de v2

### Formularios completos

`sium` define schema e introspeccion. `uix` renderiza. `lang` traduce. `format` presenta valores. `prefs/frontend` aplican densidad/tema. `http` envia. `logger` traza. `storage` guarda borradores.

Resultado esperado: formularios complejos generados, validables, localizados, accesibles y testeables.

### Seguridad completa

`auth` autentica. `session` mantiene estado. `perm` decide autorizacion. `uix` muestra guards y explicaciones. `logger` audita. `storage` conserva solo lo permitido.

Resultado esperado: flujos reales de login, MFA, sesiones, roles, permisos y auditoria.

### Datos offline/cacheados

`http` habla con servidor. `cache` deduplica e invalida. `storage` persiste. `connection` informa red/offline. `bus` propaga eventos. `orca` coordina flujos.

Resultado esperado: operaciones robustas con retry, offline queue, cache visible y rollback.

### Observabilidad

`logger`, `bus`, `timer`, `orca`, `connection`, `http` y `cache` comparten trace ids.

Resultado esperado: devtools capaces de explicar que paso, cuando, por que fallo y que modulo participo.

## Resultado esperado de Ecosistema 2.0

La v2 deberia dejar de ser solo una coleccion de motores y convertirse en una plataforma integrada:

- Componentes UI reales en `uix`.
- Motores estables en `arts`.
- Contratos compartidos en `libs`.
- Servidores/adapters en `svrs`.
- Demos y docs que consumen APIs publicas.
- Devtools para inspeccionar el sistema entero.
- Integraciones oficiales entre modulos.

El mayor salto no esta en tocar un modulo aislado. Esta en completar las capas que faltan entre ellos: UI, adapters, presets, diagnostico, contratos publicos e integracion transversal.