eleva 1.0.1 → 1.1.0

package/types/core/Eleva.d.ts

@@ -1,167 +1,194 @@
 /**
- * @typedef {Object} ElevaConfig
- * @property {boolean} [debug=false]
- *           Enable debug mode for verbose logging
- * @property {string} [prefix='e']
- *           Prefix for component style scoping
- * @property {boolean} [async=true]
- *           Enable async component setup
+ * Configuration options for the Eleva instance (reserved for future use).
+ * @typedef {Record<string, unknown>} ElevaConfig
  */
 /**
+ * Component definition object.
  * @typedef {Object} ComponentDefinition
  * @property {SetupFunction} [setup]
- *           Optional setup function that initializes the component's state and returns reactive data
- * @property {TemplateFunction|string} template
- *           Required function or string that defines the component's HTML structure
- * @property {StyleFunction|string} [style]
- *           Optional function or string that provides component-scoped CSS styles
+ *           Optional setup function that initializes the component's state and returns reactive data.
+ * @property {TemplateFunction | string} template
+ *           Required function or string that defines the component's HTML structure.
+ * @property {StyleFunction | string} [style]
+ *           Optional function or string that provides CSS styles for the component.
+ *           Styles are preserved across DOM diffs via data-e-style markers.
  * @property {ChildrenMap} [children]
- *           Optional object defining nested child components
+ *           Optional object defining nested child components.
  */
 /**
+ * Setup function that initializes component state.
  * @callback SetupFunction
- * @param {ComponentContext} ctx - The component context with props, emitter, and signal factory
- * @returns {SetupResult|Promise<SetupResult>} Reactive data and lifecycle hooks
+ * @param {ComponentContext} ctx
+ *        The component context with props, emitter, and signal factory.
+ * @returns {SetupResult | Promise<SetupResult>}
+ *          Reactive data and lifecycle hooks.
  */
 /**
+ * Data returned from setup function, may include lifecycle hooks.
  * @typedef {Record<string, unknown> & LifecycleHooks} SetupResult
- *           Data returned from setup function, may include lifecycle hooks
  */
 /**
+ * Template function that returns HTML markup.
  * @callback TemplateFunction
- * @param {ComponentContext} ctx - The component context
- * @returns {string|Promise<string>} HTML template string
+ * @param {ComponentContext & SetupResult} ctx
+ *        The merged component context and setup data.
+ * @returns {string | Promise<string>}
+ *          HTML template string.
  */
 /**
+ * Style function that returns CSS styles.
  * @callback StyleFunction
- * @param {ComponentContext} ctx - The component context
- * @returns {string} CSS styles string
+ * @param {ComponentContext & SetupResult} ctx
+ *        The merged component context and setup data.
+ * @returns {string}
+ *          CSS styles string.
  */
 /**
- * @typedef {Record<string, ComponentDefinition|string>} ChildrenMap
- *           Map of CSS selectors to component definitions or registered component names
+ * Map of CSS selectors to component definitions or registered component names.
+ * @typedef {Record<string, ComponentDefinition | string>} ChildrenMap
  */
 /**
+ * Context passed to component setup function.
  * @typedef {Object} ComponentContext
  * @property {ComponentProps} props
- *           Component properties passed during mounting
+ *           Component properties passed during mounting.
  * @property {Emitter} emitter
- *           Event emitter instance for component event handling
+ *           Event emitter instance for component event handling.
  * @property {SignalFactory} signal
- *           Factory function to create reactive Signal instances
+ *           Factory function to create reactive Signal instances.
+ * @description
+ * Plugins may extend this context with additional properties (e.g., `ctx.router`, `ctx.store`).
+ * @see RouterContext - Router plugin injected context.
+ * @see StoreApi - Store plugin injected context.
  */
 /**
+ * Properties passed to a component during mounting.
  * @typedef {Record<string, unknown>} ComponentProps
- *           Properties passed to a component during mounting
  */
 /**
- * @callback SignalFactory
- * @template T
- * @param {T} initialValue - The initial value for the signal
- * @returns {Signal<T>} A new Signal instance
+ * Factory function to create reactive Signal instances.
+ * @typedef {<T>(initialValue: T) => Signal<T>} SignalFactory
  */
 /**
+ * Lifecycle hooks that can be returned from setup function.
  * @typedef {Object} LifecycleHooks
  * @property {LifecycleHook} [onBeforeMount]
- *           Hook called before component mounting
+ *           Called before component mounting.
  * @property {LifecycleHook} [onMount]
- *           Hook called after component mounting
+ *           Called after component mounting.
  * @property {LifecycleHook} [onBeforeUpdate]
- *           Hook called before component update
+ *           Called before component update.
  * @property {LifecycleHook} [onUpdate]
- *           Hook called after component update
+ *           Called after component update.
  * @property {UnmountHook} [onUnmount]
- *           Hook called during component unmounting
+ *           Called during component unmounting.
  */
 /**
+ * Lifecycle hook function.
  * @callback LifecycleHook
- * @param {LifecycleHookContext} ctx - Context with container and component data
- * @returns {void|Promise<void>}
+ * @param {LifecycleHookContext} ctx
+ *        Context with container and component data.
+ * @returns {void | Promise<void>}
  */
 /**
+ * Unmount hook function with cleanup resources.
  * @callback UnmountHook
- * @param {UnmountHookContext} ctx - Context with cleanup resources
- * @returns {void|Promise<void>}
+ * @param {UnmountHookContext} ctx
+ *        Context with cleanup resources.
+ * @returns {void | Promise<void>}
  */
 /**
+ * Context passed to lifecycle hooks.
  * @typedef {Object} LifecycleHookContext
  * @property {HTMLElement} container
- *           The DOM element where the component is mounted
+ *           The DOM element where the component is mounted.
  * @property {ComponentContext & SetupResult} context
- *           The component's reactive state and context data
+ *           The component's reactive state and context data.
  */
 /**
+ * Context passed to unmount hook with cleanup resources.
  * @typedef {Object} UnmountHookContext
  * @property {HTMLElement} container
- *           The DOM element where the component is mounted
+ *           The DOM element where the component is mounted.
  * @property {ComponentContext & SetupResult} context
- *           The component's reactive state and context data
+ *           The component's reactive state and context data.
  * @property {CleanupResources} cleanup
- *           Object containing cleanup functions and instances
+ *           Object containing cleanup functions and instances.
  */
 /**
+ * Resources available for cleanup during unmount.
  * @typedef {Object} CleanupResources
- * @property {Array<UnsubscribeFunction>} watchers
- *           Signal watcher cleanup functions
- * @property {Array<UnsubscribeFunction>} listeners
- *           Event listener cleanup functions
- * @property {Array<MountResult>} children
- *           Child component instances
+ * @property {UnsubscribeFunction[]} watchers
+ *           Signal watcher cleanup functions.
+ * @property {UnsubscribeFunction[]} listeners
+ *           Event listener cleanup functions.
+ * @property {MountResult[]} children
+ *           Child component instances.
  */
 /**
+ * Result of mounting a component.
  * @typedef {Object} MountResult
  * @property {HTMLElement} container
- *           The DOM element where the component is mounted
+ *           The DOM element where the component is mounted.
  * @property {ComponentContext & SetupResult} data
- *           The component's reactive state and context data
+ *           The component's reactive state and context data.
  * @property {UnmountFunction} unmount
- *           Function to clean up and unmount the component
+ *           Function to clean up and unmount the component.
  */
 /**
+ * Function to unmount a component and clean up resources.
  * @callback UnmountFunction
  * @returns {Promise<void>}
  */
 /**
+ * Function to unsubscribe from events or watchers.
  * @callback UnsubscribeFunction
- * @returns {void|boolean}
+ * @returns {void | boolean}
  */
 /**
+ * Plugin interface for extending Eleva.
  * @typedef {Object} ElevaPlugin
- * @property {PluginInstallFunction} install
- *           Function that installs the plugin into the Eleva instance
  * @property {string} name
- *           Unique identifier name for the plugin
+ *           Unique identifier name for the plugin.
+ * @property {string} [version]
+ *           Optional version string for the plugin.
+ * @property {PluginInstallFunction} install
+ *           Function that installs the plugin.
  * @property {PluginUninstallFunction} [uninstall]
- *           Optional function to uninstall the plugin
+ *           Optional function to uninstall the plugin.
  */
 /**
+ * Plugin install function.
  * @callback PluginInstallFunction
- * @param {Eleva} eleva - The Eleva instance
- * @param {PluginOptions} options - Plugin configuration options
- * @returns {void|Eleva|unknown} Optionally returns the Eleva instance or plugin result
+ * @param {Eleva} eleva
+ *        The Eleva instance.
+ * @param {PluginOptions} [options]
+ *        Plugin configuration options.
+ * @returns {void | Eleva | unknown}
  */
 /**
+ * Plugin uninstall function.
  * @callback PluginUninstallFunction
- * @param {Eleva} eleva - The Eleva instance
- * @returns {void}
+ * @param {Eleva} eleva
+ *        The Eleva instance.
+ * @returns {void | Promise<void>}
  */
 /**
+ * Configuration options passed to a plugin during installation.
  * @typedef {Record<string, unknown>} PluginOptions
- *           Configuration options passed to a plugin during installation
  */
 /**
- * @callback EventHandler
- * @param {Event} event - The DOM event object
- * @returns {void}
+ * Handler function for DOM events (e.g., click, input, submit).
+ * @typedef {(event: Event) => void} DOMEventHandler
  */
 /**
+ * Common DOM event names (prefixed with @ in templates).
  * @typedef {'click'|'submit'|'input'|'change'|'focus'|'blur'|'keydown'|'keyup'|'keypress'|'mouseenter'|'mouseleave'|'mouseover'|'mouseout'|'mousedown'|'mouseup'|'touchstart'|'touchend'|'touchmove'|'scroll'|'resize'|'load'|'error'|string} DOMEventName
- *           Common DOM event names (prefixed with @ in templates)
  */
 /**
  * @class 🧩 Eleva
  * @classdesc A modern, signal-based component runtime framework that provides lifecycle hooks,
- * scoped styles, and plugin support. Eleva manages component registration, plugin integration,
+ * component styles, and plugin support. Eleva manages component registration, plugin integration,
  * event handling, and DOM rendering with a focus on performance and developer experience.
  *
  * @example
@@ -191,11 +218,10 @@ export class Eleva {
      * Creates a new Eleva instance with the specified name and configuration.
      *
      * @public
+     * @constructor
      * @param {string} name - The unique identifier name for this Eleva instance.
-     * @param {Record<string, unknown>} [config={}] - Optional configuration object for the instance.
-     *        May include framework-wide settings and default behaviors.
+     * @param {ElevaConfig} [config={}] - Optional configuration object for the instance.
      * @throws {Error} If the name is not provided or is not a string.
-     * @returns {Eleva} A new Eleva instance.
      *
      * @example
      * const app = new Eleva("myApp");
@@ -206,19 +232,19 @@ export class Eleva {
      * app.mount(document.getElementById("app"), "myComponent", { name: "World" });
      *
      */
-    constructor(name: string, config?: Record<string, unknown>);
-    /** @public {string} The unique identifier name for this Eleva instance */
-    public name: string;
-    /** @public {Object<string, unknown>} Optional configuration object for the Eleva instance */
-    public config: Record<string, unknown>;
-    /** @public {Emitter} Instance of the event emitter for handling component events */
-    public emitter: Emitter;
-    /** @public {typeof Signal} Static reference to the Signal class for creating reactive state */
-    public signal: typeof Signal;
-    /** @public {typeof TemplateEngine} Static reference to the TemplateEngine class for template parsing */
-    public templateEngine: typeof TemplateEngine;
-    /** @public {Renderer} Instance of the renderer for handling DOM updates and patching */
-    public renderer: Renderer;
+    constructor(name: string, config?: ElevaConfig);
+    /** @public @readonly {string} The unique identifier name for this Eleva instance */
+    public readonly name: string;
+    /** @public @readonly {Record<string, unknown>} Configuration object for the Eleva instance */
+    public readonly config: ElevaConfig;
+    /** @public @readonly {Emitter} Event emitter for handling component events */
+    public readonly emitter: Emitter;
+    /** @public @readonly {typeof Signal} Signal class for creating reactive state */
+    public readonly signal: typeof Signal;
+    /** @public @readonly {typeof TemplateEngine} TemplateEngine class for template parsing */
+    public readonly templateEngine: typeof TemplateEngine;
+    /** @public @readonly {Renderer} Renderer for handling DOM updates and patching */
+    public readonly renderer: Renderer;
     /** @private {Map<string, ComponentDefinition>} Registry of all component definitions by name */
     private _components;
     /** @private {Map<string, ElevaPlugin>} Collection of installed plugin instances by name */
@@ -230,14 +256,16 @@ export class Eleva {
      * The plugin's install function will be called with the Eleva instance and provided options.
      * After installation, the plugin will be available for use by components.
      *
-     * Note: Plugins that wrap core methods (e.g., mount) must be uninstalled in reverse order
+     * @note Plugins that wrap core methods (e.g., mount) must be uninstalled in reverse order
      * of installation (LIFO - Last In, First Out) to avoid conflicts.
      *
      * @public
      * @param {ElevaPlugin} plugin - The plugin object which must have an `install` function.
-     * @param {Object<string, unknown>} [options={}] - Optional configuration options for the plugin.
-     * @returns {Eleva} The Eleva instance (for method chaining).
+     * @param {PluginOptions} [options={}] - Optional configuration options for the plugin.
+     * @returns {Eleva | unknown} The Eleva instance (for method chaining) or the result returned by the plugin.
      * @throws {Error} If plugin does not have an install function.
+     * @see component - Register components after installing plugins.
+     * @see mount - Mount components to the DOM.
      * @example
      * app.use(myPlugin, { option1: "value1" });
      *
@@ -249,9 +277,7 @@ export class Eleva {
      * PluginB.uninstall(app);
      * PluginA.uninstall(app);
      */
-    public use(plugin: ElevaPlugin, options?: {
-        [x: string]: unknown;
-    }): Eleva;
+    public use(plugin: ElevaPlugin, options?: PluginOptions): Eleva | unknown;
     /**
      * Registers a new component with the Eleva instance.
      * The component will be available for mounting using its registered name.
@@ -261,6 +287,7 @@ export class Eleva {
      * @param {ComponentDefinition} definition - The component definition including setup, template, style, and children.
      * @returns {Eleva} The Eleva instance (for method chaining).
      * @throws {Error} If name is not a non-empty string or definition has no template.
+     * @see mount - Mount this component to the DOM.
      * @example
      * app.component("myButton", {
      *   template: (ctx) => `<button>${ctx.props.text}</button>`,
@@ -271,45 +298,57 @@ export class Eleva {
     /**
      * Mounts a registered component to a DOM element.
      * This will initialize the component, set up its reactive state, and render it to the DOM.
+     * If the container already has a mounted Eleva instance, it is returned as-is.
+     * Unmount clears the container contents and removes the internal instance marker.
      *
      * @public
+     * @async
      * @param {HTMLElement} container - The DOM element where the component will be mounted.
-     * @param {string|ComponentDefinition} compName - The name of the registered component or a direct component definition.
-     * @param {Object<string, unknown>} [props={}] - Optional properties to pass to the component.
+     * @param {string | ComponentDefinition} compName - The name of the registered component or a direct component definition.
+     * @param {ComponentProps} [props={}] - Optional properties to pass to the component.
      * @returns {Promise<MountResult>}
      *          A Promise that resolves to an object containing:
      *          - container: The mounted component's container element
      *          - data: The component's reactive state and context
      *          - unmount: Function to clean up and unmount the component
      * @throws {Error} If container is not a DOM element or component is not registered.
+     * @throws {Error} If setup function, template function, or style function throws.
      * @example
      * const instance = await app.mount(document.getElementById("app"), "myComponent", { text: "Click me" });
      * // Later...
-     * instance.unmount();
+     * await instance.unmount();
      */
-    public mount(container: HTMLElement, compName: string | ComponentDefinition, props?: {
-        [x: string]: unknown;
-    }): Promise<MountResult>;
+    public mount(container: HTMLElement, compName: string | ComponentDefinition, props?: ComponentProps): Promise<MountResult>;
     /**
      * Processes DOM elements for event binding based on attributes starting with "@".
-     * This method handles the event delegation system and ensures proper cleanup of event listeners.
+     * This method attaches event listeners directly to elements and ensures proper cleanup.
+     * Bound `@event` attributes are removed after listeners are attached.
+     *
+     * Handler resolution order:
+     * 1. Direct context property lookup (e.g., context["handleClick"])
+     * 2. Template expression evaluation via TemplateEngine (e.g., "increment()")
      *
      * @private
      * @param {HTMLElement} container - The container element in which to search for event attributes.
-     * @param {ComponentContext} context - The current component context containing event handler definitions.
-     * @param {Array<() => void>} listeners - Array to collect cleanup functions for each event listener.
+     * @param {ComponentContext & SetupResult} context - The merged component context and setup data.
+     * @param {UnsubscribeFunction[]} listeners - Array to collect cleanup functions for each event listener.
      * @returns {void}
+     * @see TemplateEngine.evaluate - Expression evaluation. fallback.
      */
     private _processEvents;
     /**
-     * Injects scoped styles into the component's container.
-     * The styles are automatically prefixed to prevent style leakage to other components.
+     * Injects styles into the component's container.
+     * Styles are placed in a `<style>` element with a `data-e-style` attribute for identification.
+     *
+     * @note Styles are not automatically scoped - use unique class names or CSS nesting for isolation.
+     *
+     * Optimization: Skips DOM update if style content hasn't changed.
      *
      * @private
      * @param {HTMLElement} container - The container element where styles should be injected.
      * @param {string} compId - The component ID used to identify the style element.
-     * @param {(function(ComponentContext): string)|string} styleDef - The component's style definition (function or string).
-     * @param {ComponentContext} context - The current component context for style interpolation.
+     * @param {StyleFunction | string} styleDef - The component's style definition (function or string).
+     * @param {ComponentContext & SetupResult} context - The merged component context and setup data.
      * @returns {void}
      */
     private _injectStyles;
@@ -317,11 +356,13 @@ export class Eleva {
      * Extracts and evaluates props from an element's attributes that start with `:`.
      * Prop values are evaluated as expressions against the component context,
      * allowing direct passing of objects, arrays, and other complex types.
+     * Processed attributes are removed from the element after extraction.
      *
      * @private
-     * @param {HTMLElement} element - The DOM element to extract props from
-     * @param {ComponentContext} context - The component context for evaluating prop expressions
-     * @returns {Record<string, string>} An object containing the evaluated props
+     * @param {HTMLElement} element - The DOM element to extract props from.
+     * @param {ComponentContext & SetupResult} context - The merged component context and setup data.
+     * @returns {ComponentProps} An object containing the evaluated props.
+     * @see TemplateEngine.evaluate - Expression evaluation.
      * @example
      * // For an element with attributes:
      * // <div :name="user.name" :data="items">
@@ -334,188 +375,241 @@ export class Eleva {
      * This method handles mounting of explicitly defined children components.
      *
      * The mounting process follows these steps:
-     * 1. Cleans up any existing component instances
+     * 1. Finds matching DOM nodes within the container
      * 2. Mounts explicitly defined children components
      *
      * @private
-     * @param {HTMLElement} container - The container element to mount components in
-     * @param {Object<string, ComponentDefinition>} children - Map of selectors to component definitions for explicit children
-     * @param {Array<MountResult>} childInstances - Array to store all mounted component instances
-     * @param {ComponentContext} context - The parent component context for evaluating prop expressions
+     * @async
+     * @param {HTMLElement} container - The container element to mount components in.
+     * @param {ChildrenMap} children - Map of selectors to component definitions for explicit children.
+     * @param {MountResult[]} childInstances - Array to store all mounted component instances.
+     * @param {ComponentContext & SetupResult} context - The merged component context and setup data.
      * @returns {Promise<void>}
      *
      * @example
      * // Explicit children mounting:
      * const children = {
-     *   'UserProfile': UserProfileComponent,
+     *   'user-profile': UserProfileComponent,
      *   '#settings-panel': "settings-panel"
      * };
      */
     private _mountComponents;
 }
-export type ElevaConfig = {
-    /**
-     * Enable debug mode for verbose logging
-     */
-    debug?: boolean | undefined;
-    /**
-     * Prefix for component style scoping
-     */
-    prefix?: string | undefined;
-    /**
-     * Enable async component setup
-     */
-    async?: boolean | undefined;
-};
+/**
+ * Configuration options for the Eleva instance (reserved for future use).
+ */
+export type ElevaConfig = Record<string, unknown>;
+/**
+ * Component definition object.
+ */
 export type ComponentDefinition = {
     /**
-     * Optional setup function that initializes the component's state and returns reactive data
+     * Optional setup function that initializes the component's state and returns reactive data.
      */
     setup?: SetupFunction | undefined;
     /**
-     *           Required function or string that defines the component's HTML structure
+     *           Required function or string that defines the component's HTML structure.
      */
     template: TemplateFunction | string;
     /**
-     * Optional function or string that provides component-scoped CSS styles
+     * Optional function or string that provides CSS styles for the component.
+     * Styles are preserved across DOM diffs via data-e-style markers.
      */
     style?: string | StyleFunction | undefined;
     /**
-     * Optional object defining nested child components
+     * Optional object defining nested child components.
      */
     children?: ChildrenMap | undefined;
 };
+/**
+ * Setup function that initializes component state.
+ */
 export type SetupFunction = (ctx: ComponentContext) => SetupResult | Promise<SetupResult>;
 /**
- * Data returned from setup function, may include lifecycle hooks
+ * Data returned from setup function, may include lifecycle hooks.
  */
 export type SetupResult = Record<string, unknown> & LifecycleHooks;
-export type TemplateFunction = (ctx: ComponentContext) => string | Promise<string>;
-export type StyleFunction = (ctx: ComponentContext) => string;
 /**
- * Map of CSS selectors to component definitions or registered component names
+ * Template function that returns HTML markup.
+ */
+export type TemplateFunction = (ctx: ComponentContext & SetupResult) => string | Promise<string>;
+/**
+ * Style function that returns CSS styles.
+ */
+export type StyleFunction = (ctx: ComponentContext & SetupResult) => string;
+/**
+ * Map of CSS selectors to component definitions or registered component names.
  */
 export type ChildrenMap = Record<string, ComponentDefinition | string>;
+/**
+ * Context passed to component setup function.
+ */
 export type ComponentContext = {
     /**
-     *           Component properties passed during mounting
+     *           Component properties passed during mounting.
      */
     props: ComponentProps;
     /**
-     *           Event emitter instance for component event handling
+     *           Event emitter instance for component event handling.
      */
     emitter: Emitter;
     /**
-     *           Factory function to create reactive Signal instances
+     *           Factory function to create reactive Signal instances.
      */
     signal: SignalFactory;
 };
 /**
- * Properties passed to a component during mounting
+ * Properties passed to a component during mounting.
  */
 export type ComponentProps = Record<string, unknown>;
-export type SignalFactory = () => any;
+/**
+ * Factory function to create reactive Signal instances.
+ */
+export type SignalFactory = <T>(initialValue: T) => Signal<T>;
+/**
+ * Lifecycle hooks that can be returned from setup function.
+ */
 export type LifecycleHooks = {
     /**
-     * Hook called before component mounting
+     * Called before component mounting.
      */
     onBeforeMount?: LifecycleHook | undefined;
     /**
-     * Hook called after component mounting
+     * Called after component mounting.
      */
     onMount?: LifecycleHook | undefined;
     /**
-     * Hook called before component update
+     * Called before component update.
      */
     onBeforeUpdate?: LifecycleHook | undefined;
     /**
-     * Hook called after component update
+     * Called after component update.
      */
     onUpdate?: LifecycleHook | undefined;
     /**
-     * Hook called during component unmounting
+     * Called during component unmounting.
      */
     onUnmount?: UnmountHook | undefined;
 };
+/**
+ * Lifecycle hook function.
+ */
 export type LifecycleHook = (ctx: LifecycleHookContext) => void | Promise<void>;
+/**
+ * Unmount hook function with cleanup resources.
+ */
 export type UnmountHook = (ctx: UnmountHookContext) => void | Promise<void>;
+/**
+ * Context passed to lifecycle hooks.
+ */
 export type LifecycleHookContext = {
     /**
-     *           The DOM element where the component is mounted
+     *           The DOM element where the component is mounted.
      */
     container: HTMLElement;
     /**
-     *           The component's reactive state and context data
+     *           The component's reactive state and context data.
      */
     context: ComponentContext & SetupResult;
 };
+/**
+ * Context passed to unmount hook with cleanup resources.
+ */
 export type UnmountHookContext = {
     /**
-     *           The DOM element where the component is mounted
+     *           The DOM element where the component is mounted.
      */
     container: HTMLElement;
     /**
-     *           The component's reactive state and context data
+     *           The component's reactive state and context data.
      */
     context: ComponentContext & SetupResult;
     /**
-     *           Object containing cleanup functions and instances
+     *           Object containing cleanup functions and instances.
      */
     cleanup: CleanupResources;
 };
+/**
+ * Resources available for cleanup during unmount.
+ */
 export type CleanupResources = {
     /**
-     *           Signal watcher cleanup functions
+     *           Signal watcher cleanup functions.
      */
-    watchers: Array<UnsubscribeFunction>;
+    watchers: UnsubscribeFunction[];
     /**
-     *           Event listener cleanup functions
+     *           Event listener cleanup functions.
      */
-    listeners: Array<UnsubscribeFunction>;
+    listeners: UnsubscribeFunction[];
     /**
-     *           Child component instances
+     *           Child component instances.
      */
-    children: Array<MountResult>;
+    children: MountResult[];
 };
+/**
+ * Result of mounting a component.
+ */
 export type MountResult = {
     /**
-     *           The DOM element where the component is mounted
+     *           The DOM element where the component is mounted.
      */
     container: HTMLElement;
     /**
-     *           The component's reactive state and context data
+     *           The component's reactive state and context data.
      */
     data: ComponentContext & SetupResult;
     /**
-     *           Function to clean up and unmount the component
+     *           Function to clean up and unmount the component.
      */
     unmount: UnmountFunction;
 };
+/**
+ * Function to unmount a component and clean up resources.
+ */
 export type UnmountFunction = () => Promise<void>;
+/**
+ * Function to unsubscribe from events or watchers.
+ */
 export type UnsubscribeFunction = () => void | boolean;
+/**
+ * Plugin interface for extending Eleva.
+ */
 export type ElevaPlugin = {
     /**
-     *           Function that installs the plugin into the Eleva instance
+     *           Unique identifier name for the plugin.
      */
-    install: PluginInstallFunction;
+    name: string;
     /**
-     *           Unique identifier name for the plugin
+     * Optional version string for the plugin.
      */
-    name: string;
+    version?: string | undefined;
+    /**
+     *           Function that installs the plugin.
+     */
+    install: PluginInstallFunction;
     /**
-     * Optional function to uninstall the plugin
+     * Optional function to uninstall the plugin.
      */
     uninstall?: PluginUninstallFunction | undefined;
 };
-export type PluginInstallFunction = (eleva: Eleva, options: PluginOptions) => void | Eleva | unknown;
-export type PluginUninstallFunction = (eleva: Eleva) => void;
 /**
- * Configuration options passed to a plugin during installation
+ * Plugin install function.
+ */
+export type PluginInstallFunction = (eleva: Eleva, options?: PluginOptions | undefined) => void | Eleva | unknown;
+/**
+ * Plugin uninstall function.
+ */
+export type PluginUninstallFunction = (eleva: Eleva) => void | Promise<void>;
+/**
+ * Configuration options passed to a plugin during installation.
  */
 export type PluginOptions = Record<string, unknown>;
-export type EventHandler = (event: Event) => void;
 /**
- * Common DOM event names (prefixed with @ in templates)
+ * Handler function for DOM events (e.g., click, input, submit).
+ */
+export type DOMEventHandler = (event: Event) => void;
+/**
+ * Common DOM event names (prefixed with @ in templates).
  */
 export type DOMEventName = "click" | "submit" | "input" | "change" | "focus" | "blur" | "keydown" | "keyup" | "keypress" | "mouseenter" | "mouseleave" | "mouseover" | "mouseout" | "mousedown" | "mouseup" | "touchstart" | "touchend" | "touchmove" | "scroll" | "resize" | "load" | "error" | string;
 import { Emitter } from "../modules/Emitter.js";