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.