smart-lifecycle 0.1.1

package/dist/decorators/index.js

@@ -0,0 +1,8 @@
+/**
+ * Decorator barrel exports for SmartComponents.
+ */
+export { Listen } from "./listen.decorator.js";
+export { SmartRender } from "./smart-render.decorator.js";
+export { Smart } from "./smart.decorator.js";
+export { Reactive } from "./reactive.decorator.js";
+//# sourceMappingURL=index.js.map

package/dist/decorators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAG/C,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE1D,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAG7C,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/decorators/listen/listener-initializer.d.ts

@@ -0,0 +1,23 @@
+import type { IDomContext } from "../../rendering/dom-context/dom-context.interface.js";
+import type { IListenerInitializer } from "./listener-initializer.interface.js";
+/**
+ * Implements the responsibility of binding DOM event listeners to a component after render.
+ *
+ * @description
+ * Reads listener metadata via `IListenerMetadataRegistry` and wires up DOM event handlers
+ * using the provided `IDomContext`. Subscriptions are managed by the context for
+ * automatic cleanup on destroy or re-render.
+ *
+ * Registered in the service container under `'IListenerInitializer'` by `bootstrapFramework`.
+ */
+export declare class DefaultListenerInitializer implements IListenerInitializer {
+    /**
+     * Binds all `@Listen`-registered event handlers to the component's DOM context.
+     *
+     * @param domContext - DOM context for querying elements and managing subscriptions
+     * @param component - Component instance whose methods should be bound
+     * @throws Error if domContext or component is null or undefined
+     */
+    initialize(domContext: IDomContext, component: unknown): void;
+}
+//# sourceMappingURL=listener-initializer.d.ts.map

package/dist/decorators/listen/listener-initializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-initializer.d.ts","sourceRoot":"","sources":["../../../src/decorators/listen/listener-initializer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sDAAsD,CAAC;AAGxF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAEhF;;;;;;;;;GASG;AACH,qBAAa,0BAA2B,YAAW,oBAAoB;IACrE;;;;;;OAMG;IACH,UAAU,CAAC,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI;CAwC9D"}

package/dist/decorators/listen/listener-initializer.interface.d.ts

@@ -0,0 +1,20 @@
+import type { IDomContext } from "../../rendering/dom-context/dom-context.interface.js";
+/**
+ * Defines the responsibility of binding DOM event listeners to a component after render.
+ *
+ * @description
+ * Reads listener metadata from the component and wires up DOM event handlers
+ * via `IDomContext`. Consumers depend on this abstraction — resolved from the
+ * service container — instead of coupling to the concrete binding function.
+ */
+export interface IListenerInitializer {
+    /**
+     * Binds all `@Listen`-registered event handlers to the component's DOM context.
+     *
+     * @param domContext - DOM context for querying elements and managing subscriptions
+     * @param component - Component instance whose methods should be bound
+     * @throws Error if domContext or component is null or undefined
+     */
+    initialize(domContext: IDomContext, component: unknown): void;
+}
+//# sourceMappingURL=listener-initializer.interface.d.ts.map

package/dist/decorators/listen/listener-initializer.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-initializer.interface.d.ts","sourceRoot":"","sources":["../../../src/decorators/listen/listener-initializer.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sDAAsD,CAAC;AAExF;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,UAAU,CAAC,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/D"}

package/dist/decorators/listen/listener-initializer.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=listener-initializer.interface.js.map

package/dist/decorators/listen/listener-initializer.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-initializer.interface.js","sourceRoot":"","sources":["../../../src/decorators/listen/listener-initializer.interface.ts"],"names":[],"mappings":""}

package/dist/decorators/listen/listener-initializer.js

@@ -0,0 +1,53 @@
+import { Services } from "../../providers/service-provider.js";
+/**
+ * Implements the responsibility of binding DOM event listeners to a component after render.
+ *
+ * @description
+ * Reads listener metadata via `IListenerMetadataRegistry` and wires up DOM event handlers
+ * using the provided `IDomContext`. Subscriptions are managed by the context for
+ * automatic cleanup on destroy or re-render.
+ *
+ * Registered in the service container under `'IListenerInitializer'` by `bootstrapFramework`.
+ */
+export class DefaultListenerInitializer {
+    /**
+     * Binds all `@Listen`-registered event handlers to the component's DOM context.
+     *
+     * @param domContext - DOM context for querying elements and managing subscriptions
+     * @param component - Component instance whose methods should be bound
+     * @throws Error if domContext or component is null or undefined
+     */
+    initialize(domContext, component) {
+        if (!domContext)
+            throw new Error("DomContext is required");
+        if (!component || typeof component !== "object")
+            throw new Error("Component is required");
+        const listeners = Services.get("IListenerMetadataRegistry").get(component);
+        const comp = component;
+        listeners.forEach(({ methodName, eventName, selector }) => {
+            const method = comp[methodName];
+            if (typeof method !== "function") {
+                return;
+            }
+            let targetElement = null;
+            if (selector) {
+                targetElement = domContext.query(selector);
+                if (!targetElement) {
+                    return;
+                }
+            }
+            else {
+                targetElement = domContext.getElement();
+                if (!targetElement) {
+                    return;
+                }
+            }
+            const element = targetElement;
+            const handler = (event) => method.call(component, event);
+            element.addEventListener(eventName, handler);
+            const unsub = () => element.removeEventListener(eventName, handler);
+            domContext.addSubscription(unsub);
+        });
+    }
+}
+//# sourceMappingURL=listener-initializer.js.map

package/dist/decorators/listen/listener-initializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-initializer.js","sourceRoot":"","sources":["../../../src/decorators/listen/listener-initializer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AAI/D;;;;;;;;;GASG;AACH,MAAM,OAAO,0BAA0B;IACrC;;;;;;OAMG;IACH,UAAU,CAAC,UAAuB,EAAE,SAAkB;QACpD,IAAI,CAAC,UAAU;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC3D,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS,KAAK,QAAQ;YAC7C,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QAE3C,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAC5B,2BAA2B,CAC5B,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACjB,MAAM,IAAI,GAAG,SAAoC,CAAC;QAElD,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,EAAE;YACxD,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;YAChC,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;gBACjC,OAAO;YACT,CAAC;YAED,IAAI,aAAa,GAAuB,IAAI,CAAC;YAE7C,IAAI,QAAQ,EAAE,CAAC;gBACb,aAAa,GAAG,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAC3C,IAAI,CAAC,aAAa,EAAE,CAAC;oBACnB,OAAO;gBACT,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,aAAa,GAAG,UAAU,CAAC,UAAU,EAAE,CAAC;gBACxC,IAAI,CAAC,aAAa,EAAE,CAAC;oBACnB,OAAO;gBACT,CAAC;YACH,CAAC;YAED,MAAM,OAAO,GAAG,aAAa,CAAC;YAC9B,MAAM,OAAO,GAAG,CAAC,KAAY,EAAE,EAAE,CAC9B,MAAiC,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;YAC5D,OAAO,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YAE7C,MAAM,KAAK,GAAgB,GAAG,EAAE,CAC9B,OAAO,CAAC,mBAAmB,CAAC,SAAS,EAAE,OAAwB,CAAC,CAAC;YACnE,UAAU,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/decorators/listen/listener-metadata-registry.d.ts

@@ -0,0 +1,27 @@
+import type { IListenerMetadataRegistry } from "./listener-metadata-registry.interface.js";
+import type { ListenerMetadata } from "../listen.decorator.js";
+/**
+ * Implements the responsibility of storing and retrieving listener metadata for component prototypes.
+ *
+ * @description
+ * Stores metadata directly on component prototypes via a Symbol key,
+ * ensuring per-class isolation with inherited deduplication.
+ * Registered in the service container under `'IListenerMetadataRegistry'`.
+ */
+export declare class DefaultListenerMetadataRegistry implements IListenerMetadataRegistry {
+    /**
+     * Registers listener metadata on a component prototype with deduplication.
+     *
+     * @param prototype - Component prototype to register metadata on
+     * @param metadata - Listener metadata to register
+     */
+    register(prototype: unknown, metadata: ListenerMetadata): void;
+    /**
+     * Retrieves all listener metadata for a component instance.
+     *
+     * @param component - Component instance to read metadata from
+     * @returns Array of listener metadata, or empty array if none registered
+     */
+    get(component: unknown): ListenerMetadata[];
+}
+//# sourceMappingURL=listener-metadata-registry.d.ts.map

package/dist/decorators/listen/listener-metadata-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-metadata-registry.d.ts","sourceRoot":"","sources":["../../../src/decorators/listen/listener-metadata-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC;AAC3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAY/D;;;;;;;GAOG;AACH,qBAAa,+BAAgC,YAAW,yBAAyB;IAC/E;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IA2B9D;;;;;OAKG;IACH,GAAG,CAAC,SAAS,EAAE,OAAO,GAAG,gBAAgB,EAAE;CAK5C"}

package/dist/decorators/listen/listener-metadata-registry.interface.d.ts

@@ -0,0 +1,26 @@
+import type { ListenerMetadata } from "../listen.decorator.js";
+/**
+ * Defines the responsibility of storing and retrieving listener metadata for component prototypes.
+ *
+ * @description
+ * Acts as the coordination point between the `@Listen` decorator (which writes metadata)
+ * and the listener initializer (which reads metadata at render time).
+ * Consumers resolve this via the service container to avoid coupling to the concrete implementation.
+ */
+export interface IListenerMetadataRegistry {
+    /**
+     * Registers listener metadata on a component prototype with deduplication.
+     *
+     * @param prototype - Component prototype to register metadata on
+     * @param metadata - Listener metadata to register
+     */
+    register(prototype: unknown, metadata: ListenerMetadata): void;
+    /**
+     * Retrieves all listener metadata for a component instance.
+     *
+     * @param component - Component instance to read metadata from
+     * @returns Array of listener metadata, or empty array if none registered
+     */
+    get(component: unknown): ListenerMetadata[];
+}
+//# sourceMappingURL=listener-metadata-registry.interface.d.ts.map

package/dist/decorators/listen/listener-metadata-registry.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-metadata-registry.interface.d.ts","sourceRoot":"","sources":["../../../src/decorators/listen/listener-metadata-registry.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAE/D;;;;;OAKG;IACH,GAAG,CAAC,SAAS,EAAE,OAAO,GAAG,gBAAgB,EAAE,CAAC;CAC7C"}

package/dist/decorators/listen/listener-metadata-registry.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=listener-metadata-registry.interface.js.map

package/dist/decorators/listen/listener-metadata-registry.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-metadata-registry.interface.js","sourceRoot":"","sources":["../../../src/decorators/listen/listener-metadata-registry.interface.ts"],"names":[],"mappings":""}

package/dist/decorators/listen/listener-metadata-registry.js

@@ -0,0 +1,51 @@
+/**
+ * Symbol key for storing listener metadata on component prototypes.
+ * Prevents property name collisions and enables private metadata storage.
+ */
+const LISTENERS_SYMBOL = Symbol("smartcomponents:listeners");
+/**
+ * Implements the responsibility of storing and retrieving listener metadata for component prototypes.
+ *
+ * @description
+ * Stores metadata directly on component prototypes via a Symbol key,
+ * ensuring per-class isolation with inherited deduplication.
+ * Registered in the service container under `'IListenerMetadataRegistry'`.
+ */
+export class DefaultListenerMetadataRegistry {
+    /**
+     * Registers listener metadata on a component prototype with deduplication.
+     *
+     * @param prototype - Component prototype to register metadata on
+     * @param metadata - Listener metadata to register
+     */
+    register(prototype, metadata) {
+        if (typeof prototype !== "object" || prototype === null)
+            return;
+        if (!Object.prototype.hasOwnProperty.call(prototype, LISTENERS_SYMBOL)) {
+            const inherited = (prototype[LISTENERS_SYMBOL] || []);
+            prototype[LISTENERS_SYMBOL] = [
+                ...inherited,
+            ];
+        }
+        const listeners = prototype[LISTENERS_SYMBOL];
+        const isDuplicate = listeners.some((l) => l.methodName === metadata.methodName &&
+            l.eventName === metadata.eventName &&
+            l.selector === metadata.selector);
+        if (!isDuplicate) {
+            listeners.push(metadata);
+        }
+    }
+    /**
+     * Retrieves all listener metadata for a component instance.
+     *
+     * @param component - Component instance to read metadata from
+     * @returns Array of listener metadata, or empty array if none registered
+     */
+    get(component) {
+        if (typeof component !== "object" || component === null)
+            return [];
+        const prototype = Object.getPrototypeOf(component);
+        return prototype[LISTENERS_SYMBOL] || [];
+    }
+}
+//# sourceMappingURL=listener-metadata-registry.js.map

package/dist/decorators/listen/listener-metadata-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-metadata-registry.js","sourceRoot":"","sources":["../../../src/decorators/listen/listener-metadata-registry.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,gBAAgB,GAAG,MAAM,CAAC,2BAA2B,CAAC,CAAC;AAM7D;;;;;;;GAOG;AACH,MAAM,OAAO,+BAA+B;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,SAAkB,EAAE,QAA0B;QACrD,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI;YAAE,OAAO;QAEhE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,gBAAgB,CAAC,EAAE,CAAC;YACvE,MAAM,SAAS,GAAG,CAAE,SAAqC,CACvD,gBAAgB,CACjB,IAAI,EAAE,CAAuB,CAAC;YAC9B,SAAgD,CAAC,gBAAgB,CAAC,GAAG;gBACpE,GAAG,SAAS;aACb,CAAC;QACJ,CAAC;QAED,MAAM,SAAS,GAAI,SAAgD,CACjE,gBAAgB,CACjB,CAAC;QACF,MAAM,WAAW,GAAG,SAAS,CAAC,IAAI,CAChC,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU;YACpC,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,SAAS;YAClC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,CACnC,CAAC;QAEF,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,SAAkB;QACpB,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI;YAAE,OAAO,EAAE,CAAC;QACnE,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,SAAS,CAAwB,CAAC;QAC1E,OAAO,SAAS,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC;IAC3C,CAAC;CACF"}

package/dist/decorators/listen.decorator.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Defines the responsibility of storing listener metadata registered by @Listen decorator.
+ *
+ * @example
+ * ```typescript
+ * const metadata: ListenerMetadata = {
+ *   methodName: 'onClick',
+ *   eventName: 'click',
+ *   selector: null
+ * };
+ * ```
+ */
+export interface ListenerMetadata {
+    /** The method name to be called when event fires */
+    methodName: string;
+    /** The DOM event name (e.g., 'click', 'input', 'keydown') */
+    eventName: string;
+    /** CSS selector for event delegation (null = root element when omitted) */
+    selector: string | null;
+}
+/**
+ * @Listen decorator - Registers event listeners for component methods.
+ *
+ * @description
+ * Declarative event binding that stores metadata without touching DOM.
+ * Actual listener binding happens after render via `IListenerInitializer`.
+ * Supports both root element binding and selector-based delegation.
+ *
+ * **Overloads:**
+ * - `@Listen('click')` - Binds to root element
+ * - `@Listen('.btn', 'click')` - Binds to selector (delegation)
+ * - `@Listen({ selector: '.btn' }, 'click')` - Explicit selector object
+ *
+ * @param selectorOrEvent - CSS selector string, config object, or event name
+ * @param eventName - Event name (when first param is selector)
+ * @returns Method decorator
+ *
+ * @throws Error if event name is not provided
+ *
+ * @example
+ * ```typescript
+ * class MyComponent extends SmartComponent {
+ *   // Bind to root element
+ *   @Listen('click')
+ *   onClick(event: Event) {
+ *     console.log('Root clicked');
+ *   }
+ *
+ *   // Bind with selector (delegation)
+ *   @Listen('.submit-btn', 'click')
+ *   onSubmit(event: Event) {
+ *     console.log('Button clicked');
+ *   }
+ *
+ *   // Alternative selector syntax
+ *   @Listen({ selector: 'input' }, 'input')
+ *   onInput(event: Event) {
+ *     console.log('Input changed');
+ *   }
+ * }
+ * ```
+ */
+export declare function Listen(selectorOrEvent: string | {
+    selector: string;
+}, eventName?: string): (value: (...args: never[]) => unknown, context: ClassMethodDecoratorContext) => void;
+//# sourceMappingURL=listen.decorator.d.ts.map

package/dist/decorators/listen.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/listen.decorator.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,MAAM,CACpB,eAAe,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC9C,SAAS,CAAC,EAAE,MAAM,GACjB,CACD,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,EACpC,OAAO,EAAE,2BAA2B,KACjC,IAAI,CAiCR"}

package/dist/decorators/listen.decorator.js

@@ -0,0 +1,72 @@
+import { Services } from "../providers/service-provider.js";
+/**
+ * @Listen decorator - Registers event listeners for component methods.
+ *
+ * @description
+ * Declarative event binding that stores metadata without touching DOM.
+ * Actual listener binding happens after render via `IListenerInitializer`.
+ * Supports both root element binding and selector-based delegation.
+ *
+ * **Overloads:**
+ * - `@Listen('click')` - Binds to root element
+ * - `@Listen('.btn', 'click')` - Binds to selector (delegation)
+ * - `@Listen({ selector: '.btn' }, 'click')` - Explicit selector object
+ *
+ * @param selectorOrEvent - CSS selector string, config object, or event name
+ * @param eventName - Event name (when first param is selector)
+ * @returns Method decorator
+ *
+ * @throws Error if event name is not provided
+ *
+ * @example
+ * ```typescript
+ * class MyComponent extends SmartComponent {
+ *   // Bind to root element
+ *   @Listen('click')
+ *   onClick(event: Event) {
+ *     console.log('Root clicked');
+ *   }
+ *
+ *   // Bind with selector (delegation)
+ *   @Listen('.submit-btn', 'click')
+ *   onSubmit(event: Event) {
+ *     console.log('Button clicked');
+ *   }
+ *
+ *   // Alternative selector syntax
+ *   @Listen({ selector: 'input' }, 'input')
+ *   onInput(event: Event) {
+ *     console.log('Input changed');
+ *   }
+ * }
+ * ```
+ */
+export function Listen(selectorOrEvent, eventName) {
+    let finalSelector = null;
+    let finalEventName;
+    if (typeof selectorOrEvent === "string" && eventName) {
+        finalSelector = selectorOrEvent;
+        finalEventName = eventName;
+    }
+    else if (typeof selectorOrEvent === "object" && eventName) {
+        finalSelector = selectorOrEvent.selector;
+        finalEventName = eventName;
+    }
+    else if (typeof selectorOrEvent === "string" && !eventName) {
+        finalEventName = selectorOrEvent;
+    }
+    else {
+        throw new Error('@Listen requires event name. Usage: @Listen("click") or @Listen(".btn", "click")');
+    }
+    return function (_value, context) {
+        context.addInitializer(function () {
+            const prototype = Object.getPrototypeOf(this);
+            Services.get("IListenerMetadataRegistry").register(prototype, {
+                methodName: context.name,
+                eventName: finalEventName,
+                selector: finalSelector,
+            });
+        });
+    };
+}
+//# sourceMappingURL=listen.decorator.js.map

package/dist/decorators/listen.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen.decorator.js","sourceRoot":"","sources":["../../src/decorators/listen.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAwB5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,UAAU,MAAM,CACpB,eAA8C,EAC9C,SAAkB;IAKlB,IAAI,aAAa,GAAkB,IAAI,CAAC;IACxC,IAAI,cAAsB,CAAC;IAE3B,IAAI,OAAO,eAAe,KAAK,QAAQ,IAAI,SAAS,EAAE,CAAC;QACrD,aAAa,GAAG,eAAe,CAAC;QAChC,cAAc,GAAG,SAAS,CAAC;IAC7B,CAAC;SAAM,IAAI,OAAO,eAAe,KAAK,QAAQ,IAAI,SAAS,EAAE,CAAC;QAC5D,aAAa,GAAG,eAAe,CAAC,QAAQ,CAAC;QACzC,cAAc,GAAG,SAAS,CAAC;IAC7B,CAAC;SAAM,IAAI,OAAO,eAAe,KAAK,QAAQ,IAAI,CAAC,SAAS,EAAE,CAAC;QAC7D,cAAc,GAAG,eAAe,CAAC;IACnC,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CACb,kFAAkF,CACnF,CAAC;IACJ,CAAC;IAED,OAAO,UACL,MAAqC,EACrC,OAAoC;QAEpC,OAAO,CAAC,cAAc,CAAC;YACrB,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;YAC9C,QAAQ,CAAC,GAAG,CACV,2BAA2B,CAC5B,CAAC,QAAQ,CAAC,SAAS,EAAE;gBACpB,UAAU,EAAE,OAAO,CAAC,IAAc;gBAClC,SAAS,EAAE,cAAc;gBACzB,QAAQ,EAAE,aAAa;aACxB,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/decorators/listener-initializer.d.ts

@@ -0,0 +1,33 @@
+import type { IDomContext } from '../rendering/dom-context/dom-context.interface.js';
+/**
+ * Initializes event listeners for a component using @Listen metadata.
+ *
+ * @description
+ * Binds DOM event listeners AFTER render using DomContext.
+ * Reads metadata registered by @Listen decorator and creates subscriptions to handlers.
+ * Supports both root element and selector-based delegation.
+ *
+ * **Features:**
+ * - No component coupling - uses DomContext only
+ * - Automatic subscription management via domContext.addSubscription
+ * - Supports re-render without duplicating listeners (call clearSubscriptions first)
+ * - No manual cleanup needed - handled by DomContext.destroy()
+ *
+ * @param domContext - DOM context for querying elements and managing subscriptions
+ * @param component - Component instance with @Listen decorated methods
+ * @throws Error if domContext or component is null or undefined
+ *
+ * @example
+ * ```typescript
+ * // In RenderPipeline after setting element:
+ * domContext.setElement(compiledElement);
+ * initializeListeners(domContext, component);
+ *
+ * // For re-render:
+ * domContext.clearSubscriptions();
+ * domContext.setElement(newElement);
+ * initializeListeners(domContext, component);
+ * ```
+ */
+export declare function initializeListeners(domContext: IDomContext, component: unknown): void;
+//# sourceMappingURL=listener-initializer.d.ts.map

package/dist/decorators/listener-initializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-initializer.d.ts","sourceRoot":"","sources":["../../src/decorators/listener-initializer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mDAAmD,CAAC;AAGrF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CA2CrF"}

package/dist/decorators/listener-initializer.js

@@ -0,0 +1,67 @@
+import { getListenerMetadata } from './listen.decorator.js';
+/**
+ * Initializes event listeners for a component using @Listen metadata.
+ *
+ * @description
+ * Binds DOM event listeners AFTER render using DomContext.
+ * Reads metadata registered by @Listen decorator and creates subscriptions to handlers.
+ * Supports both root element and selector-based delegation.
+ *
+ * **Features:**
+ * - No component coupling - uses DomContext only
+ * - Automatic subscription management via domContext.addSubscription
+ * - Supports re-render without duplicating listeners (call clearSubscriptions first)
+ * - No manual cleanup needed - handled by DomContext.destroy()
+ *
+ * @param domContext - DOM context for querying elements and managing subscriptions
+ * @param component - Component instance with @Listen decorated methods
+ * @throws Error if domContext or component is null or undefined
+ *
+ * @example
+ * ```typescript
+ * // In RenderPipeline after setting element:
+ * domContext.setElement(compiledElement);
+ * initializeListeners(domContext, component);
+ *
+ * // For re-render:
+ * domContext.clearSubscriptions();
+ * domContext.setElement(newElement);
+ * initializeListeners(domContext, component);
+ * ```
+ */
+export function initializeListeners(domContext, component) {
+    if (!domContext)
+        throw new Error('DomContext is required');
+    if (!component || typeof component !== 'object')
+        throw new Error('Component is required');
+    const listeners = getListenerMetadata(component);
+    const comp = component;
+    listeners.forEach(({ methodName, eventName, selector }) => {
+        const method = comp[methodName];
+        if (typeof method !== 'function') {
+            console.warn(`[@Listen] Method "${methodName}" not found on component. Skipping listener for "${eventName}".`);
+            return;
+        }
+        let targetElement = null;
+        if (selector) {
+            targetElement = domContext.query(selector);
+            if (!targetElement) {
+                console.warn(`[@Listen] Selector "${selector}" did not match any element. Listener for "${eventName}" not bound.`);
+                return;
+            }
+        }
+        else {
+            targetElement = domContext.getElement();
+            if (!targetElement) {
+                console.warn(`[@Listen] Root element not available. Listener for "${eventName}" not bound.`);
+                return;
+            }
+        }
+        const element = targetElement;
+        const handler = (event) => method.call(component, event);
+        element.addEventListener(eventName, handler);
+        const unsub = () => element.removeEventListener(eventName, handler);
+        domContext.addSubscription(unsub);
+    });
+}
+//# sourceMappingURL=listener-initializer.js.map

package/dist/decorators/listener-initializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-initializer.js","sourceRoot":"","sources":["../../src/decorators/listener-initializer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAuB,EAAE,SAAkB;IAC7E,IAAI,CAAC,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC3D,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS,KAAK,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAE1F,MAAM,SAAS,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,SAAoC,CAAC;IAElD,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,EAAE;QACxD,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QAChC,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;YACjC,OAAO,CAAC,IAAI,CACV,qBAAqB,UAAU,oDAAoD,SAAS,IAAI,CACjG,CAAC;YACF,OAAO;QACT,CAAC;QAED,IAAI,aAAa,GAAuB,IAAI,CAAC;QAE7C,IAAI,QAAQ,EAAE,CAAC;YACb,aAAa,GAAG,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC3C,IAAI,CAAC,aAAa,EAAE,CAAC;gBACnB,OAAO,CAAC,IAAI,CACV,uBAAuB,QAAQ,8CAA8C,SAAS,cAAc,CACrG,CAAC;gBACF,OAAO;YACT,CAAC;QACH,CAAC;aAAM,CAAC;YACN,aAAa,GAAG,UAAU,CAAC,UAAU,EAAE,CAAC;YACxC,IAAI,CAAC,aAAa,EAAE,CAAC;gBACnB,OAAO,CAAC,IAAI,CACV,uDAAuD,SAAS,cAAc,CAC/E,CAAC;gBACF,OAAO;YACT,CAAC;QACH,CAAC;QAED,MAAM,OAAO,GAAG,aAAa,CAAC;QAC9B,MAAM,OAAO,GAAG,CAAC,KAAY,EAAE,EAAE,CAAE,MAAiC,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QAC5F,OAAO,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAE7C,MAAM,KAAK,GAAgB,GAAG,EAAE,CAAC,OAAO,CAAC,mBAAmB,CAAC,SAAS,EAAE,OAAwB,CAAC,CAAC;QAClG,UAAU,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/decorators/reactive.decorator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @Reactive decorator (TC39 Stage 3 standard decorators — TypeScript 5.0+)
+ *
+ * @description
+ * Marks a property as reactive — automatically triggers a property-specific signal when changed.
+ * Only notifies subscribers listening to THIS specific property, avoiding unnecessary updates.
+ *
+ * Supports two TC39 Stage 3 decorator forms:
+ * - **Accessor form** (`@Reactive accessor count = 0`): preferred, uses the TC39 `accessor` keyword
+ *   which provides a dedicated private backing field per-spec.
+ * - **Field form** (`@Reactive count = 0`): alternative without `accessor`, installs a per-instance
+ *   getter/setter via `Object.defineProperty` in the field initializer.
+ *
+ * Additionally supports legacy `experimentalDecorators` when the framework is bootstrapped with
+ * `{ decorators: 'auto' }`. In `'strict'` mode (default), legacy usage throws an error.
+ *
+ * Both TC39 forms produce identical reactive behaviour. The accessor form is idiomatic TC39.
+ *
+ * @architecture
+ * - Captures property name from decorator context
+ * - On property change: calls `component.getPropertyObservable(propName).notify()`
+ * - On property read: calls `IDependencyTracker.trackAccess(propName)` so computed getters
+ *   can discover dependencies
+ * - RenderEngine subscribes to specific properties used in template bindings
+ * - Result: `{{count}}` only updates when `count` changes, not when other properties change
+ *
+ * @example
+ * ```typescript
+ * class MyComponent extends SmartComponent {
+ *   // Accessor form (recommended — TC39 Stage 3):
+ *   @Reactive accessor count = 0;
+ *
+ *   // Field form (TC39 Stage 3, no accessor keyword):
+ *   @Reactive items: string[] = [];
+ *
+ *   increment() {
+ *     this.count++; // Only triggers 'count' signal
+ *   }
+ * }
+ * ```
+ */
+export declare function Reactive<T extends object, V>(target: ClassAccessorDecoratorTarget<T, V>, context: ClassAccessorDecoratorContext<T, V>): ClassAccessorDecoratorResult<T, V> | void;
+export declare function Reactive<T extends object, V>(target: undefined, context: ClassFieldDecoratorContext<T, V>): ((initialValue: V) => V) | void;
+export declare function Reactive(target: object | undefined, context: string | symbol): void;
+//# sourceMappingURL=reactive.decorator.d.ts.map

package/dist/decorators/reactive.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactive.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/reactive.decorator.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAC1C,MAAM,EAAE,4BAA4B,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1C,OAAO,EAAE,6BAA6B,CAAC,CAAC,EAAE,CAAC,CAAC,GAC3C,4BAA4B,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AAE7C,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAC1C,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,0BAA0B,CAAC,CAAC,EAAE,CAAC,CAAC,GACxC,CAAC,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC;AAEnC,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,MAAM,GAAG,MAAM,GACvB,IAAI,CAAC"}