Runtime

Runtime (TypeScript)

The eQuantic.UI Runtime is the library that brings the application to life in the browser. It is responsible for transforming the virtual tree generated by the compiled code into real DOM elements and reacting to state changes.

📦 Runtime Distribution

The runtime is distributed as a single bundled file (runtime.js, ~49KB minified) that includes:

• Core Runtime: Virtual DOM reconciler, component lifecycle
• State Management: Reactive state system
• Event System: WeakMap-based event tracking
• Server Actions Bridge: Client-server RPC communication
• Development Tools: Logger and error overlay (dev-only)
• Service Provider: Dependency injection container

Packaging & Deployment

The runtime is self-contained in the eQuantic.UI.Runtime package at tools/runtime/runtime.js. The SDK references this package and copies the runtime during build via the CopyEQuanticRuntime MSBuild target.

Build Flow:

TypeScript source (src/eQuantic.UI.Runtime)
    ↓ npm run build (vite + tsc)
dist/index.js (single bundle via inlineDynamicImports)
    ↓ packaged in Runtime package
eQuantic.UI.Runtime.nupkg/tools/runtime/runtime.js
    ↓ SDK resolves via $(PkgeQuantic_UI_Runtime)
    ↓ MSBuild CopyEQuanticRuntime target
Consumer's wwwroot/_equantic/runtime.js

Architecture Benefits:

• ✅ Decoupling: Runtime manages its own artifacts, SDK only references
• ✅ Correct Versioning: Consumer can use different Runtime versions than SDK
• ✅ No Duplication: Single source of truth for runtime.js
• ✅ Zero Dependencies: Consumers get the runtime automatically without Node.js/npm

🔄 The Reconciler

Unlike frameworks that recreate the entire DOM, the eQuantic.UI Reconciler compares the current page with the desired new version and applies only the minimum necessary changes.

Diffing Algorithm:

1. Type Comparison: If a node has changed its tag (e.g., div to span), it is replaced entirely.
2. Attribute Update: Only modified attributes are changed in the DOM.
3. Child Management: The reconciler recursively traverses the list of children.

🗝️ Keyed Identity

With the introduction of Keyed Diffing, the reconciler now supports the key property.

• If two nodes in different positions have the same key, the framework understands that the element has been moved, preserving the browser's internal state (such as the cursor position in an input or the scroll state).

🧠 Event and Memory Management

To prevent memory leaks, the runtime uses an event tracking system based on WeakMap.

Advantages of WeakMap:

• Event listeners are mapped directly to the HTMLElement.
• When an element is removed from the DOM and there are no more references to it, the browser's Garbage Collector can automatically clear the event metadata, ensuring that the application's memory consumption remains stable even in long sessions.

💧 Hydration (SSR)

The runtime supports the "Hydration" process, where it takes control of HTML already rendered by the server (SSR). Instead of destroying and recreating, the runtime only attaches the necessary event listeners to the existing elements, ensuring an instantaneous initial load.

🔧 Development Mode

The runtime detects the environment via the window.__EQ_DEV__ flag (set by the server based on IWebHostEnvironment.IsDevelopment()).

Development-Only Features

Logger System (utils/logger.ts)

Professional logging system that only outputs in development mode:

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

logger.debug('Boot process started');  // Only in dev
logger.info('Component rendered');     // Only in dev
logger.warn('Deprecated API used');    // Always logs
logger.error('Failed to load data');   // Always logs

All logs are prefixed with [eQuantic.UI] for easy filtering.

Error Overlay (dev/error-overlay.ts)

Next.js-style error overlay that displays runtime errors in a full-screen UI (development only):

• Automatic capture: Unhandled errors and promise rejections
• Stack traces: Full error context with source information
• Keyboard support: Press Esc to close
• Clean UX: Similar to Next.js error overlay

The error overlay is automatically imported and activated when window.__EQ_DEV__ === true.

Production Mode

In production builds:

• logger.debug() and logger.info() are silenced
• Error overlay is never loaded
• Only logger.warn() and logger.error() output to console
• Minimal runtime overhead (~49KB gzipped)

🎨 Theme System

The runtime includes a theme registration system that allows components to register CSS class mappings:

window.__registerTheme('Button', {
  variants: {
    primary: 'bg-blue-600 text-white hover:bg-blue-700',
    secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
    // ...
  },
  sizes: {
    small: 'px-2 py-1 text-sm',
    medium: 'px-4 py-2 text-base',
    // ...
  }
});

Themes are resolved during the boot process and applied by the ServiceProvider.