El Runtime de eQuantic.UI es la biblioteca que da vida a la aplicación en el navegador. Es responsable de transformar el árbol virtual que genera el código compilado en elementos del DOM reales y de reaccionar a los cambios de estado.

📦 Distribución del runtime

El runtime se distribuye como un único archivo empaquetado (runtime.js; su tamaño no se cita aquí, porque su tamaño gzip es un presupuesto que ServedRuntimeBudgetTests hace cumplir, vea Flujo de build) que incluye:

•

Runtime central: el reconciliador de DOM virtual, el ciclo de vida de los componentes

•

Gestión de estado: el sistema de estado reactivo

•

Sistema de eventos: el seguimiento de eventos basado en WeakMap

•

Puente de Server Actions: la comunicación RPC entre cliente y servidor

•

Herramientas de desarrollo: logger y overlay de errores (solo en desarrollo)

•

Proveedor de servicios: el contenedor de inyección de dependencias

Empaquetado y despliegue

El runtime viaja dentro del paquete que lo sirve, eQuantic.UI.Server: el Server incrusta el bundle y responde /_equantic/runtime.js con él, y lleva los mismos bytes como archivo en tools/runtime/runtime.js. El SDK copia ese archivo al wwwroot/_equantic/ de la aplicación durante el build (el target de MSBuild CopyEQuanticRuntime) para las herramientas que cargan los módulos de una aplicación fuera de un servidor, como la vista previa de VS Code; a una aplicación en marcha siempre se le responde con el bundle incrustado.

Flujo de build:

Fuente TypeScript (src/eQuantic.UI.Runtime/src) + boot.ts (src/eQuantic.UI.Sdk/Resources)

↓ target BundleRuntime de eQuantic.UI.Server (bun embebido), antes de cada build

src/eQuantic.UI.Server/wwwroot/runtime.js (UN bundle, y su único escritor)

├─ incrustado en eQuantic.UI.Server.dll → servido en /_equantic/runtime.js

↓ target CollectServedRuntime, al empaquetar

eQuantic.UI.Server.nupkg/tools/runtime/runtime.js

↓ el SDK lo resuelve vía $(PkgeQuantic_UI_Server)

↓ target de MSBuild CopyEQuanticRuntime

wwwroot/_equantic/runtime.js del consumidor (los mismos bytes)

Beneficios de la arquitectura:

•

✅ Un solo escritor: el bundle se escribe una vez, por el paquete que lo sirve; el SDK solo lo referencia

•

✅ La copia ES el runtime servido: lo que una aplicación encuentra en wwwroot/_equantic/runtime.js es byte por byte lo que responde /_equantic/runtime.js

•

✅ Sin duplicación: una única fuente de verdad para runtime.js

•

✅ Cero dependencias: quien lo consume recibe el runtime automáticamente, sin Node.js ni npm

🔄 El reconciliador

A diferencia de los frameworks que recrean el DOM entero, el Reconciler de eQuantic.UI compara la página actual con la nueva versión deseada y aplica solo los cambios mínimos necesarios.

Algoritmo de diffing:

Comparación de tipo: si un nodo cambió de etiqueta (por ejemplo, de div a span), se reemplaza por completo.

Actualización de atributos: solo los atributos modificados se cambian en el DOM.

Gestión de hijos: el reconciliador recorre recursivamente la lista de hijos.

🗝️ Identidad por clave

El reconciliador soporta el Keyed Diffing a través de la propiedad key.

•

Si dos nodos en posiciones distintas tienen la misma clave, el framework entiende que el elemento se movió, y preserva el estado interno del navegador (como la posición del cursor en un campo o el estado del scroll).

🧠 Gestión de eventos y de memoria

Para prevenir fugas de memoria, el runtime usa un sistema de seguimiento de eventos basado en WeakMap.

Ventajas de WeakMap:

•

Los listeners de eventos se mapean directamente al HTMLElement.

•

Cuando un elemento se retira del DOM y no quedan más referencias a él, el recolector de basura del navegador puede limpiar automáticamente los metadatos del evento, lo que asegura que el consumo de memoria de la aplicación se mantenga estable incluso en sesiones largas.

🎯 Dos contratos de eventos que vale conocer

Desde 0.2.0-preview.24

El espejo de HtmlElement baja las propiedades on* a nombres de eventos del DOM, con la grafía propia del DOM allí donde pasarlo a minúsculas no basta: OnDoubleClick registra dblclick (la única divergencia del EventNameMap de C#: un listener de doubleclick se engancha bien y no se dispara nunca). Y fijar OnSubmit toma la PROPIEDAD del envío: el runtime llama a preventDefault() antes de invocar, así que el envío con navegación propio del navegador nunca corre, y el manejador valida y llama a una server action en su lugar. Un formulario que quiere el envío nativo simplemente no fija ningún manejador. click conserva los valores por defecto del navegador que siempre tuvo: un clic en una etiqueta debe seguir alternando su casilla.

Desde 0.2.0-preview.24

Las capas de overlay modales llegan de los dos productores llevando role="dialog", aria-modal, tabindex="-1" y un marcador data-eq-trap. El controlador del cliente reconcilia las trampas contra el DOM en el mismo momento en que el conjunto de Shortcuts se confirma después de cada pasada del reconciliador: una capa que apareció registra a quien la invocó y toma el foco después del siguiente frame (una capa que se desvanece desde visibility:hidden no es enfocable hasta que el estilo aterriza); Tab y Shift+Tab circulan dentro, y una guarda de focusin recupera lo que se escapa; una capa que dejó de estar marcada (retirada, cerrada manteniéndose montada, o reparentada para su animación de salida) devuelve el foco a quien la invocó. Descubrir por marcador en lugar de por ruta es lo que mantiene a los dos productores idénticos byte a byte.

💧 Hidratación (SSR)

El runtime soporta el proceso de "hidratación", en el que toma el control del HTML que el servidor ya renderizó (SSR). En lugar de destruir y recrear, el runtime solo engancha los listeners de eventos necesarios a los elementos existentes, lo que asegura una carga inicial instantánea.

🔧 Modo de desarrollo

El runtime detecta el entorno vía el flag window.__EQ_DEV__ (que fija el servidor a partir de IWebHostEnvironment.IsDevelopment()).

Funcionalidades solo de desarrollo

Sistema de logger (utils/logger.ts)

Sistema de logging profesional que solo emite en modo de desarrollo:

import { logger } from './utils/logger';

logger.debug('Boot process started'); // Solo en desarrollo

logger.info('Component rendered'); // Solo en desarrollo

logger.warn('Deprecated API used'); // Siempre registra

logger.error('Failed to load data'); // Siempre registra

Todos los logs llevan el prefijo [eQuantic.UI] para filtrarlos con facilidad.

Overlay de errores (dev/error-overlay.ts)

Overlay de errores al estilo de Next.js que muestra los errores de runtime en una interfaz a pantalla completa (solo en desarrollo):

•

Captura automática: errores no manejados y rechazos de promesas

•

Stack traces: el contexto completo del error con información de la fuente

•

Soporte de teclado: pulsa Esc para cerrar

•

UX limpia: similar al overlay de errores de Next.js

El overlay de errores se importa y se activa automáticamente cuando window.__EQ_DEV__ === true.

Modo de producción

En los builds de producción:

•

logger.debug() y logger.info() quedan silenciados

•

El overlay de errores nunca se carga

•

Solo logger.warn() y logger.error() emiten a la consola

•

Coste mínimo de runtime: un bundle, cuyo tamaño gzip es un presupuesto que la suite hace cumplir, en lugar de un número citado aquí

🎨 Puente del tema

El tema de la aplicación es C# tipado en el servidor (IAppTheme, seleccionado vía UseTheme, vea DesignSystem). El servidor serializa el tema seleccionado en window.__EQ_THEME__ al lado de la configuración de boot, y el puente de tema del runtime (shared/theme-bridge.ts) lo adopta en el boot, así que los píxeles del SSR y el lowering del cliente resuelven los mismos tokens, y un cambio claro/oscuro en tiempo de ejecución voltea una sola declaración color-scheme.

PREVIOUSResolución de tipos externos

NEXTRendimiento

ON THIS PAGE