snice 1.14.3 → 2.1.0

package/dist/index.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v1.14.2
+ * snice v1.14.3
  * Imperative TypeScript framework for building vanilla web components with decorators, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.
@@ -80,24 +80,27 @@ function on(eventName, selectorOrOptions, options) {
         selector = undefined;
         opts = selectorOrOptions;
     }
-    return function (target, propertyKey, descriptor) {
-        // Store event handler metadata
-        if (!target[ON_HANDLERS]) {
-            target[ON_HANDLERS] = [];
-        }
-        // Normalize to array and expand at decoration time
-        const eventNames = Array.isArray(eventName) ? eventName : [eventName];
-        // Create a handler entry for each event
-        for (const event of eventNames) {
-            target[ON_HANDLERS].push({
-                eventName: event,
-                selector,
-                methodName: propertyKey,
-                method: descriptor.value,
-                options: opts
-            });
-        }
-        return descriptor;
+    return function (target, context) {
+        const propertyKey = context.name;
+        context.addInitializer(function () {
+            const constructor = this.constructor;
+            // Store event handler metadata
+            if (!constructor.prototype[ON_HANDLERS]) {
+                constructor.prototype[ON_HANDLERS] = [];
+            }
+            // Normalize to array and expand at decoration time
+            const eventNames = Array.isArray(eventName) ? eventName : [eventName];
+            // Create a handler entry for each event
+            for (const event of eventNames) {
+                constructor.prototype[ON_HANDLERS].push({
+                    eventName: event,
+                    selector,
+                    methodName: propertyKey,
+                    method: target,
+                    options: opts
+                });
+            }
+        });
     };
 }
 // Helper to setup event handlers for elements
@@ -291,13 +294,12 @@ function cleanupEventHandlers(instance) {
  * @param options Optional configuration extending EventInit
  */
 function dispatch(eventName, options) {
-    return function (_target, _propertyKey, descriptor) {
-        const originalMethod = descriptor.value;
+    return function (originalMethod, _context) {
         // Create timing wrappers for dispatch
         let debounceTimeout;
         let throttleLastCall = 0;
         let throttleTimeout;
-        descriptor.value = function (...args) {
+        return function (...args) {
             // Call the original method
             const result = originalMethod.apply(this, args);
             // Helper to dispatch the event
@@ -352,7 +354,6 @@ function dispatch(eventName, options) {
             timedDispatch(result);
             return result;
         };
-        return descriptor;
     };
 }
 
@@ -379,27 +380,30 @@ function observe(observeTarget, selectorOrOptions, options) {
         selector = undefined;
         opts = selectorOrOptions;
     }
-    return function (target, propertyKey, descriptor) {
-        // Store observer metadata
-        if (!target[OBSERVERS]) {
-            target[OBSERVERS] = [];
-        }
-        // Normalize to array
-        const observeTargets = Array.isArray(observeTarget) ? observeTarget : [observeTarget];
-        // Create an observer entry for each target
-        for (const targetString of observeTargets) {
-            // Parse the observation type from the observeTarget string
-            const [type, ...modifiers] = targetString.split(':');
-            target[OBSERVERS].push({
-                type,
-                target: modifiers.join(':'), // Rejoin for media queries or mutation types
-                selector,
-                methodName: propertyKey,
-                method: descriptor.value,
-                options: opts
-            });
-        }
-        return descriptor;
+    return function (target, context) {
+        const propertyKey = context.name;
+        context.addInitializer(function () {
+            const constructor = this.constructor;
+            // Store observer metadata
+            if (!constructor.prototype[OBSERVERS]) {
+                constructor.prototype[OBSERVERS] = [];
+            }
+            // Normalize to array
+            const observeTargets = Array.isArray(observeTarget) ? observeTarget : [observeTarget];
+            // Create an observer entry for each target
+            for (const targetString of observeTargets) {
+                // Parse the observation type from the observeTarget string
+                const [type, ...modifiers] = targetString.split(':');
+                constructor.prototype[OBSERVERS].push({
+                    type,
+                    target: modifiers.join(':'), // Rejoin for media queries or mutation types
+                    selector,
+                    methodName: propertyKey,
+                    method: target,
+                    options: opts
+                });
+            }
+        });
     };
 }
 // Helper to setup observers for elements
@@ -692,13 +696,12 @@ function cleanupObservers(instance) {
  * @param options Optional configuration
  */
 function request(requestName, options) {
-    return function (_target, _propertyKey, descriptor) {
-        const originalMethod = descriptor.value;
+    return function (originalMethod, _context) {
         // Create timing variables for debounce/throttle
         let debounceTimeout;
         let throttleLastCall = 0;
         let throttleTimeout;
-        descriptor.value = async function (...args) {
+        return async function (...args) {
             const actualRequest = async () => {
                 // @request always acts as requester (client side)
                 const responseTimeout = options?.timeout ?? 120000; // Default 2 minute timeout
@@ -822,7 +825,6 @@ function request(requestName, options) {
             // No timing applied, execute immediately
             return actualRequest();
         };
-        return descriptor;
     };
 }
 /**
@@ -832,20 +834,22 @@ function request(requestName, options) {
  * @param options Optional configuration
  */
 function respond(requestName, options) {
-    return function (target, propertyKey, descriptor) {
-        const originalMethod = descriptor.value;
-        // Store response metadata on the prototype
-        // This will be picked up by setupResponseHandlers
-        if (!target[CHANNEL_HANDLERS]) {
-            target[CHANNEL_HANDLERS] = [];
-        }
-        target[CHANNEL_HANDLERS].push({
-            channelName: requestName,
-            methodName: propertyKey,
-            method: originalMethod,
-            options: options
+    return function (target, context) {
+        const propertyKey = context.name;
+        context.addInitializer(function () {
+            const constructor = this.constructor;
+            // Store response metadata on the prototype
+            // This will be picked up by setupResponseHandlers
+            if (!constructor.prototype[CHANNEL_HANDLERS]) {
+                constructor.prototype[CHANNEL_HANDLERS] = [];
+            }
+            constructor.prototype[CHANNEL_HANDLERS].push({
+                channelName: requestName,
+                methodName: propertyKey,
+                method: target,
+                options: options
+            });
         });
-        return descriptor;
     };
 }
 // Helper to setup response handlers for elements and controllers
@@ -996,7 +1000,7 @@ class ControllerScope {
  * @param name The name to register the controller under
  */
 function controller(name) {
-    return function (constructor) {
+    return function (constructor, _context) {
         snice.controllerRegistry.set(name, constructor);
         // Mark as controller class for channel decorator detection
         constructor.prototype[IS_CONTROLLER_CLASS] = true;
@@ -1343,10 +1347,12 @@ function applyElementFunctionality(constructor) {
             // Mark that properties have been initialized
             this[PROPERTIES_INITIALIZED] = true;
             // Reflect properties that were explicitly set before connection
-            // but skip default values that were never explicitly set
-            if (properties && this[EXPLICITLY_SET_PROPERTIES]) {
+            // AND also reflect initial values that have reflect: true
+            if (properties) {
                 for (const [propName, propOptions] of properties) {
-                    if (propOptions.reflect && this[EXPLICITLY_SET_PROPERTIES].has(propName) && propName in this[PROPERTY_VALUES]) {
+                    const wasExplicitlySet = this[EXPLICITLY_SET_PROPERTIES] && this[EXPLICITLY_SET_PROPERTIES].has(propName);
+                    const hasInitialValue = propName in this[PROPERTY_VALUES];
+                    if (propOptions.reflect && hasInitialValue && (wasExplicitlySet || this[PROPERTY_VALUES][propName] !== undefined)) {
                         const value = this[PROPERTY_VALUES][propName];
                         const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName.toLowerCase();
                         if (value !== null && value !== undefined && value !== false &&
@@ -1595,176 +1601,224 @@ function applyElementFunctionality(constructor) {
     };
 }
 function element(tagName) {
-    return function (constructor) {
+    return function (constructor, context) {
+        // Transfer metadata from context to constructor
+        if (context.metadata && context.metadata[PROPERTIES]) {
+            if (!constructor[PROPERTIES]) {
+                constructor[PROPERTIES] = new Map();
+            }
+            for (const [key, value] of context.metadata[PROPERTIES]) {
+                constructor[PROPERTIES].set(key, value);
+            }
+        }
         applyElementFunctionality(constructor);
         customElements.define(tagName, constructor);
+        return constructor;
     };
 }
 function layout(tagName) {
-    return function (constructor) {
+    return function (constructor, context) {
+        // Transfer metadata from context to constructor
+        if (context.metadata && context.metadata[PROPERTIES]) {
+            if (!constructor[PROPERTIES]) {
+                constructor[PROPERTIES] = new Map();
+            }
+            for (const [key, value] of context.metadata[PROPERTIES]) {
+                constructor[PROPERTIES].set(key, value);
+            }
+        }
         applyElementFunctionality(constructor);
         customElements.define(tagName, constructor);
+        return constructor;
     };
 }
 function property(options) {
-    return function (target, propertyKey) {
-        const constructor = target.constructor;
-        // Warn about problematic reflection usage
+    return function (_value, context) {
+        const propertyKey = context.name;
+        // Use metadata to store property information at decoration time
+        if (!context.metadata) {
+            context.metadata = {};
+        }
+        if (!context.metadata[PROPERTIES]) {
+            context.metadata[PROPERTIES] = new Map();
+        }
+        context.metadata[PROPERTIES].set(propertyKey, options || {});
+        // Warn about problematic reflection usage at decoration time
         if (options?.reflect && options?.type === Array) {
             console.warn(`⚠️  Property '${propertyKey}' uses reflect:true with Array type.`);
         }
         if (options?.reflect && options?.type === Object) {
             console.warn(`⚠️  Property '${propertyKey}' uses reflect:true with Object type.`);
         }
-        if (!constructor[PROPERTIES]) {
-            constructor[PROPERTIES] = new Map();
-        }
-        constructor[PROPERTIES].set(propertyKey, options || {});
-        const descriptor = {
-            get() {
-                if (!this[PROPERTY_VALUES]) {
-                    this[PROPERTY_VALUES] = {};
-                }
-                return this[PROPERTY_VALUES][propertyKey];
-            },
-            set(value) {
-                if (!this[PROPERTY_VALUES]) {
-                    this[PROPERTY_VALUES] = {};
-                }
-                if (!this[EXPLICITLY_SET_PROPERTIES]) {
-                    this[EXPLICITLY_SET_PROPERTIES] = new Set();
-                }
-                const oldValue = this[PROPERTY_VALUES][propertyKey];
-                // Don't update if value hasn't changed
-                if (oldValue === value)
-                    return;
-                // Mark as explicitly set in these cases:
-                // 1. There was a previous value (normal property update)
-                // 2. This is during element construction and we have a non-null/non-undefined value
-                //    (this handles default values declared in class properties)
-                const isInitialDefaultValue = oldValue === undefined && !this[PROPERTIES_INITIALIZED];
-                if (oldValue !== undefined || (isInitialDefaultValue && value !== null && value !== undefined)) {
-                    this[EXPLICITLY_SET_PROPERTIES].add(propertyKey);
-                }
-                this[PROPERTY_VALUES][propertyKey] = value;
-                // Only reflect to attributes if:
-                // 1. Properties have been initialized from attributes  
-                // 2. The property was explicitly set (not just default value)
-                // This prevents default values from creating attributes
-                if (options?.reflect && this.setAttribute && this[PROPERTIES_INITIALIZED] && this[EXPLICITLY_SET_PROPERTIES].has(propertyKey)) {
-                    const attributeName = typeof options.attribute === 'string' ? options.attribute : propertyKey.toLowerCase();
-                    if (value === null || value === undefined || value === false ||
-                        (options?.type === SimpleArray && Array.isArray(value) && value.length === 0)) {
-                        this.removeAttribute(attributeName);
-                    }
-                    else {
-                        // Handle special types for reflection
-                        let attributeValue;
-                        if (value instanceof Date) {
-                            attributeValue = value.toISOString();
+        context.addInitializer(function () {
+            // No longer need warnings here since they're at decoration time
+        });
+        // Return a field initializer function for new decorators
+        return function (initialValue) {
+            // Set up the property descriptor on first access
+            if (!Object.hasOwnProperty.call(this.constructor.prototype, propertyKey)) {
+                const descriptor = {
+                    get() {
+                        if (!this[PROPERTY_VALUES]) {
+                            this[PROPERTY_VALUES] = {};
                         }
-                        else if (typeof value === 'bigint') {
-                            attributeValue = value.toString() + 'n';
+                        return this[PROPERTY_VALUES][propertyKey];
+                    },
+                    set(newValue) {
+                        if (!this[PROPERTY_VALUES]) {
+                            this[PROPERTY_VALUES] = {};
                         }
-                        else if (options?.type === SimpleArray && Array.isArray(value)) {
-                            attributeValue = SimpleArray.serialize(value);
+                        if (!this[EXPLICITLY_SET_PROPERTIES]) {
+                            this[EXPLICITLY_SET_PROPERTIES] = new Set();
                         }
-                        else {
-                            attributeValue = String(value);
+                        const oldValue = this[PROPERTY_VALUES][propertyKey];
+                        if (oldValue === newValue)
+                            return;
+                        const isInitialDefaultValue = oldValue === undefined && !this[PROPERTIES_INITIALIZED];
+                        if (oldValue !== undefined || (isInitialDefaultValue && newValue !== null && newValue !== undefined)) {
+                            this[EXPLICITLY_SET_PROPERTIES].add(propertyKey);
                         }
-                        this.setAttribute(attributeName, attributeValue);
-                    }
-                }
-                // Call watchers for this property
-                const watchers = constructor[PROPERTY_WATCHERS];
-                if (watchers) {
-                    // Call specific property watchers
-                    if (watchers.has(propertyKey)) {
-                        const propertyWatchers = watchers.get(propertyKey);
-                        for (const watcher of propertyWatchers) {
-                            try {
-                                // Always pass oldValue, newValue, and propertyName
-                                watcher.method.call(this, oldValue, value, propertyKey);
+                        this[PROPERTY_VALUES][propertyKey] = newValue;
+                        if (options?.reflect && this.setAttribute && this[PROPERTIES_INITIALIZED] && this[EXPLICITLY_SET_PROPERTIES].has(propertyKey)) {
+                            const attributeName = typeof options.attribute === 'string' ? options.attribute : propertyKey.toLowerCase();
+                            if (newValue === null || newValue === undefined || newValue === false ||
+                                (options?.type === SimpleArray && Array.isArray(newValue) && newValue.length === 0)) {
+                                this.removeAttribute(attributeName);
                             }
-                            catch (error) {
-                                console.error(`Error in @watch('${propertyKey}') method ${watcher.methodName}:`, error);
+                            else {
+                                let attributeValue;
+                                if (newValue instanceof Date) {
+                                    attributeValue = newValue.toISOString();
+                                }
+                                else if (typeof newValue === 'bigint') {
+                                    attributeValue = newValue.toString() + 'n';
+                                }
+                                else if (options?.type === SimpleArray && Array.isArray(newValue)) {
+                                    attributeValue = SimpleArray.serialize(newValue);
+                                }
+                                else {
+                                    attributeValue = String(newValue);
+                                }
+                                this.setAttribute(attributeName, attributeValue);
                             }
                         }
-                    }
-                    // Call wildcard watchers (watching "*")
-                    if (watchers.has('*')) {
-                        const wildcardWatchers = watchers.get('*');
-                        for (const watcher of wildcardWatchers) {
-                            try {
-                                // Same signature for consistency
-                                watcher.method.call(this, oldValue, value, propertyKey);
+                        const constructor = this.constructor;
+                        const watchers = constructor[PROPERTY_WATCHERS];
+                        if (watchers) {
+                            if (watchers.has(propertyKey)) {
+                                const propertyWatchers = watchers.get(propertyKey);
+                                for (const watcher of propertyWatchers) {
+                                    try {
+                                        watcher.method.call(this, oldValue, newValue, propertyKey);
+                                    }
+                                    catch (error) {
+                                        console.error(`Error in @watch('${propertyKey}') method ${watcher.methodName}:`, error);
+                                    }
+                                }
                             }
-                            catch (error) {
-                                console.error(`Error in @watch('*') method ${watcher.methodName}:`, error);
+                            if (watchers.has('*')) {
+                                const wildcardWatchers = watchers.get('*');
+                                for (const watcher of wildcardWatchers) {
+                                    try {
+                                        watcher.method.call(this, oldValue, newValue, propertyKey);
+                                    }
+                                    catch (error) {
+                                        console.error(`Error in @watch('*') method ${watcher.methodName}:`, error);
+                                    }
+                                }
                             }
                         }
-                    }
-                }
-                // Call requestUpdate if available and value changed
-                if (this.requestUpdate) {
-                    this.requestUpdate(propertyKey, oldValue);
-                }
-            },
-            enumerable: true,
-            configurable: true,
+                        if (this.requestUpdate) {
+                            this.requestUpdate(propertyKey, oldValue);
+                        }
+                    },
+                    configurable: true,
+                    enumerable: true
+                };
+                Object.defineProperty(this.constructor.prototype, propertyKey, descriptor);
+            }
+            // Initialize the property value
+            if (!this[PROPERTY_VALUES]) {
+                this[PROPERTY_VALUES] = {};
+            }
+            this[PROPERTY_VALUES][propertyKey] = initialValue;
+            return initialValue;
         };
-        Object.defineProperty(target, propertyKey, descriptor);
     };
 }
 function query(selector, options = {}) {
-    return function (target, propertyKey) {
+    return function (_value, context) {
         // Default to shadow DOM only
         const { light = false, shadow = true } = options;
-        Object.defineProperty(target, propertyKey, {
-            get() {
-                // Check if this is a controller using the symbol
-                const isController = this[IS_CONTROLLER_INSTANCE] === true;
-                const root = isController && this.element ? this.element : this;
-                // Query in specified contexts
-                let result = null;
-                if (shadow && root.shadowRoot) {
-                    result = root.shadowRoot.querySelector(selector);
-                }
-                if (!result && light) {
-                    result = root.querySelector(selector);
-                }
-                return result || null;
-            },
-            enumerable: true,
-            configurable: true,
-        });
+        const propertyKey = context.name;
+        // Return a field initializer function for new decorators
+        return function (initialValue) {
+            // Set up the property descriptor on first access
+            if (!Object.hasOwnProperty.call(this.constructor.prototype, propertyKey)) {
+                const descriptor = {
+                    get() {
+                        // Check if this is a controller using the symbol
+                        const isController = this[IS_CONTROLLER_INSTANCE] === true;
+                        const root = isController && this.element ? this.element : this;
+                        // Query in specified contexts
+                        let result = null;
+                        if (shadow && root.shadowRoot) {
+                            result = root.shadowRoot.querySelector(selector);
+                        }
+                        if (!result && light) {
+                            result = root.querySelector(selector);
+                        }
+                        return result || null;
+                    },
+                    set() {
+                        // Query results are read-only
+                    },
+                    configurable: true,
+                    enumerable: true
+                };
+                Object.defineProperty(this.constructor.prototype, propertyKey, descriptor);
+            }
+            return initialValue;
+        };
     };
 }
 function queryAll(selector, options = {}) {
-    return function (target, propertyKey) {
+    return function (_value, context) {
         // Default to shadow DOM only
         const { light = false, shadow = true } = options;
-        Object.defineProperty(target, propertyKey, {
-            get() {
-                // Check if this is a controller using the symbol
-                const isController = this[IS_CONTROLLER_INSTANCE] === true;
-                const root = isController && this.element ? this.element : this;
-                // Query in specified contexts and combine results
-                const results = [];
-                if (shadow && root.shadowRoot) {
-                    const shadowResults = root.shadowRoot.querySelectorAll(selector);
-                    results.push(...shadowResults);
-                }
-                if (light) {
-                    const lightResults = root.querySelectorAll(selector);
-                    results.push(...lightResults);
-                }
-                // Return a static NodeList-like object
-                return results;
-            },
-            enumerable: true,
-            configurable: true,
-        });
+        const propertyKey = context.name;
+        // Return a field initializer function for new decorators
+        return function (initialValue) {
+            // Set up the property descriptor on first access
+            if (!Object.hasOwnProperty.call(this.constructor.prototype, propertyKey)) {
+                const descriptor = {
+                    get() {
+                        // Check if this is a controller using the symbol
+                        const isController = this[IS_CONTROLLER_INSTANCE] === true;
+                        const root = isController && this.element ? this.element : this;
+                        // Query in specified contexts and combine results
+                        const results = [];
+                        if (shadow && root.shadowRoot) {
+                            const shadowResults = root.shadowRoot.querySelectorAll(selector);
+                            results.push(...shadowResults);
+                        }
+                        if (light) {
+                            const lightResults = root.querySelectorAll(selector);
+                            results.push(...lightResults);
+                        }
+                        // Return a static NodeList-like object
+                        return results;
+                    },
+                    set() {
+                        // Query results are read-only
+                    },
+                    configurable: true,
+                    enumerable: true
+                };
+                Object.defineProperty(this.constructor.prototype, propertyKey, descriptor);
+            }
+            return initialValue;
+        };
     };
 }
 /**
@@ -1774,6 +1828,7 @@ function queryAll(selector, options = {}) {
  * Strings cannot contain the full-width comma character
  */
 class SimpleArray {
+    static { this.SEPARATOR = '，'; } // U+FF0C Full-width comma
     /**
      * Serialize array to string for attribute storage
      */
@@ -1823,24 +1878,25 @@ class SimpleArray {
         });
     }
 }
-SimpleArray.SEPARATOR = '，'; // U+FF0C Full-width comma
 function watch(...propertyNames) {
-    return function (target, methodName, descriptor) {
-        const constructor = target.constructor;
-        if (!constructor[PROPERTY_WATCHERS]) {
-            constructor[PROPERTY_WATCHERS] = new Map();
-        }
-        // Store the watcher method for each property
-        for (const propertyName of propertyNames) {
-            if (!constructor[PROPERTY_WATCHERS].has(propertyName)) {
-                constructor[PROPERTY_WATCHERS].set(propertyName, []);
+    return function (target, context) {
+        const methodName = context.name;
+        context.addInitializer(function () {
+            const constructor = this.constructor;
+            if (!constructor[PROPERTY_WATCHERS]) {
+                constructor[PROPERTY_WATCHERS] = new Map();
+            }
+            // Store the watcher method for each property
+            for (const propertyName of propertyNames) {
+                if (!constructor[PROPERTY_WATCHERS].has(propertyName)) {
+                    constructor[PROPERTY_WATCHERS].set(propertyName, []);
+                }
+                constructor[PROPERTY_WATCHERS].get(propertyName).push({
+                    methodName,
+                    method: target
+                });
             }
-            constructor[PROPERTY_WATCHERS].get(propertyName).push({
-                methodName,
-                method: descriptor.value
-            });
-        }
-        return descriptor;
+        });
     };
 }
 /**
@@ -1848,46 +1904,57 @@ function watch(...propertyNames) {
  * The context is automatically provided to page components by the router
  */
 function context() {
-    return function (target, propertyKey) {
-        // Define property getter that returns the context
-        Object.defineProperty(target, propertyKey, {
-            get() {
-                // First check if context is stored directly on this element
-                if (this[ROUTER_CONTEXT] !== undefined) {
-                    return this[ROUTER_CONTEXT];
-                }
-                // Otherwise, request context from parent page via event
-                const detail = { target: this };
-                const event = new CustomEvent('@context/request', {
-                    bubbles: true,
-                    cancelable: true,
-                    detail
-                });
-                // Dispatch event and wait for response
-                // Check if this is a controller using the symbol
-                const isController = this[IS_CONTROLLER_INSTANCE] === true;
-                let targetElement = isController && this.element ? this.element : this;
-                // If element is null (e.g., controller was detached), can't get context
-                if (!targetElement || !targetElement.dispatchEvent) {
-                    return undefined;
-                }
-                // If we're in shadow DOM, dispatch on the host element to ensure proper bubbling
-                if (targetElement.getRootNode && targetElement.getRootNode() instanceof ShadowRoot) {
-                    const shadowRoot = targetElement.getRootNode();
-                    targetElement = shadowRoot.host;
-                }
-                targetElement.dispatchEvent(event);
-                // Check if context was provided via the event
-                if (detail.context !== undefined) {
-                    // Cache it for future use
-                    this[ROUTER_CONTEXT] = detail.context;
-                    return detail.context;
-                }
-                return undefined;
-            },
-            enumerable: true,
-            configurable: true
-        });
+    return function (_value, context) {
+        const propertyKey = context.name;
+        // Return a field initializer function for new decorators
+        return function (initialValue) {
+            // Set up the property descriptor on first access
+            if (!Object.hasOwnProperty.call(this.constructor.prototype, propertyKey)) {
+                const descriptor = {
+                    get() {
+                        // First check if context is stored directly on this element
+                        if (this[ROUTER_CONTEXT] !== undefined) {
+                            return this[ROUTER_CONTEXT];
+                        }
+                        // Otherwise, request context from parent page via event
+                        const detail = { target: this };
+                        const event = new CustomEvent('@context/request', {
+                            bubbles: true,
+                            cancelable: true,
+                            detail
+                        });
+                        // Dispatch event and wait for response
+                        // Check if this is a controller using the symbol
+                        const isController = this[IS_CONTROLLER_INSTANCE] === true;
+                        let targetElement = isController && this.element ? this.element : this;
+                        // If element is null (e.g., controller was detached), can't get context
+                        if (!targetElement || !targetElement.dispatchEvent) {
+                            return undefined;
+                        }
+                        // If we're in shadow DOM, dispatch on the host element to ensure proper bubbling
+                        if (targetElement.getRootNode && targetElement.getRootNode() instanceof ShadowRoot) {
+                            const shadowRoot = targetElement.getRootNode();
+                            targetElement = shadowRoot.host;
+                        }
+                        targetElement.dispatchEvent(event);
+                        // Check if context was provided via the event
+                        if (detail.context !== undefined) {
+                            // Cache it for future use
+                            this[ROUTER_CONTEXT] = detail.context;
+                            return detail.context;
+                        }
+                        return undefined;
+                    },
+                    set() {
+                        // Context is read-only
+                    },
+                    configurable: true,
+                    enumerable: true
+                };
+                Object.defineProperty(this.constructor.prototype, propertyKey, descriptor);
+            }
+            return initialValue;
+        };
     };
 }
 /**
@@ -1896,16 +1963,18 @@ function context() {
  * Supports async methods
  */
 function ready() {
-    return function (target, methodName, descriptor) {
-        const constructor = target.constructor;
-        if (!constructor[READY_HANDLERS]) {
-            constructor[READY_HANDLERS] = [];
-        }
-        constructor[READY_HANDLERS].push({
-            methodName,
-            method: descriptor.value
+    return function (target, context) {
+        const methodName = context.name;
+        context.addInitializer(function () {
+            const constructor = this.constructor;
+            if (!constructor[READY_HANDLERS]) {
+                constructor[READY_HANDLERS] = [];
+            }
+            constructor[READY_HANDLERS].push({
+                methodName,
+                method: target
+            });
         });
-        return descriptor;
     };
 }
 /**
@@ -1913,16 +1982,18 @@ function ready() {
  * Used for cleanup tasks when element is removed from DOM
  */
 function dispose() {
-    return function (target, methodName, descriptor) {
-        const constructor = target.constructor;
-        if (!constructor[DISPOSE_HANDLERS]) {
-            constructor[DISPOSE_HANDLERS] = [];
-        }
-        constructor[DISPOSE_HANDLERS].push({
-            methodName,
-            method: descriptor.value
+    return function (target, context) {
+        const methodName = context.name;
+        context.addInitializer(function () {
+            const constructor = this.constructor;
+            if (!constructor[DISPOSE_HANDLERS]) {
+                constructor[DISPOSE_HANDLERS] = [];
+            }
+            constructor[DISPOSE_HANDLERS].push({
+                methodName,
+                method: target
+            });
         });
-        return descriptor;
     };
 }
 /**
@@ -1931,27 +2002,20 @@ function dispose() {
  * When the decorated method is called, it automatically re-renders its part
  */
 function part(partName, options = {}) {
-    return function (target, methodName, descriptor) {
-        const constructor = target.constructor;
-        // Handle case where descriptor might be undefined (TypeScript experimental decorators)
-        if (!descriptor) {
-            descriptor = Object.getOwnPropertyDescriptor(target, methodName) || {
-                value: target[methodName],
-                writable: true,
-                enumerable: true,
-                configurable: true
-            };
-        }
-        const originalMethod = descriptor.value;
-        if (!constructor[PARTS]) {
-            constructor[PARTS] = new Map();
-        }
-        constructor[PARTS].set(partName, {
-            methodName,
-            method: originalMethod
+    return function (originalMethod, context) {
+        const methodName = context.name;
+        context.addInitializer(function () {
+            const constructor = this.constructor;
+            if (!constructor[PARTS]) {
+                constructor[PARTS] = new Map();
+            }
+            constructor[PARTS].set(partName, {
+                methodName,
+                method: originalMethod
+            });
         });
-        // Wrap the original method to automatically re-render the part when called
-        descriptor.value = async function (...args) {
+        // Return wrapped method that automatically re-renders the part when called
+        return function (...args) {
             // Initialize timers storage if not present
             if (!this[PART_TIMERS]) {
                 this[PART_TIMERS] = new Map();
@@ -1965,58 +2029,96 @@ function part(partName, options = {}) {
                 });
             }
             const timers = this[PART_TIMERS].get(partName);
-            // Create the render function
-            const renderPart = async () => {
-                // Call the original method to get the content
-                const result = originalMethod.apply(this, args);
-                const content = result instanceof Promise ? await result : result;
-                // Re-render the part if shadow DOM exists and content is defined
+            // Call the original method first to get its result
+            const result = originalMethod.apply(this, args);
+            // Helper function to update DOM
+            const updateDOM = (content) => {
                 if (this.shadowRoot && content !== undefined) {
                     const partElement = this.shadowRoot.querySelector(`[part="${partName}"]`);
                     if (partElement) {
                         partElement.innerHTML = content;
                     }
                 }
-                return content;
             };
-            // Handle debounce (only if positive value)
-            if (options.debounce !== undefined && options.debounce > 0) {
-                if (timers.debounceTimer) {
-                    clearTimeout(timers.debounceTimer);
-                }
-                return new Promise((resolve) => {
+            // Check if result is a Promise (async method)
+            if (result instanceof Promise) {
+                // Handle async method
+                if (options.debounce !== undefined && options.debounce > 0) {
+                    // Debounce: defer DOM update, return original Promise
+                    if (timers.debounceTimer) {
+                        clearTimeout(timers.debounceTimer);
+                    }
                     timers.debounceTimer = setTimeout(async () => {
-                        const result = await renderPart();
-                        resolve(result);
+                        const content = await result;
+                        updateDOM(content);
                     }, options.debounce);
+                    return result;
+                }
+                if (options.throttle !== undefined && options.throttle > 0) {
+                    // Throttle: handle timing but return original Promise
+                    const now = Date.now();
+                    if (timers.lastThrottleCall === 0 || now - timers.lastThrottleCall >= options.throttle) {
+                        timers.lastThrottleCall = now;
+                        return result.then(content => {
+                            updateDOM(content);
+                            return content;
+                        });
+                    }
+                    else {
+                        if (!timers.throttleTimer) {
+                            const remainingTime = options.throttle - (now - timers.lastThrottleCall);
+                            timers.throttleTimer = setTimeout(async () => {
+                                timers.throttleTimer = null;
+                                timers.lastThrottleCall = Date.now();
+                                const content = await result;
+                                updateDOM(content);
+                            }, remainingTime);
+                        }
+                        return result;
+                    }
+                }
+                // No timing: update DOM after Promise resolves
+                return result.then(content => {
+                    updateDOM(content);
+                    return content;
                 });
             }
-            // Handle throttle (only if positive value)
-            if (options.throttle !== undefined && options.throttle > 0) {
-                const now = Date.now();
-                if (timers.lastThrottleCall === 0 || now - timers.lastThrottleCall >= options.throttle) {
-                    timers.lastThrottleCall = now;
-                    return await renderPart();
+            else {
+                // Handle sync method
+                if (options.debounce !== undefined && options.debounce > 0) {
+                    // Debounce: defer DOM update, return result immediately
+                    if (timers.debounceTimer) {
+                        clearTimeout(timers.debounceTimer);
+                    }
+                    timers.debounceTimer = setTimeout(() => {
+                        updateDOM(result);
+                    }, options.debounce);
+                    return result;
                 }
-                else {
-                    // If throttled, schedule the next call if not already scheduled
-                    if (!timers.throttleTimer) {
-                        const remainingTime = options.throttle - (now - timers.lastThrottleCall);
-                        timers.throttleTimer = setTimeout(async () => {
-                            timers.throttleTimer = null;
-                            timers.lastThrottleCall = Date.now();
-                            await renderPart();
-                        }, remainingTime);
+                if (options.throttle !== undefined && options.throttle > 0) {
+                    // Throttle: handle timing for DOM updates
+                    const now = Date.now();
+                    if (timers.lastThrottleCall === 0 || now - timers.lastThrottleCall >= options.throttle) {
+                        timers.lastThrottleCall = now;
+                        updateDOM(result);
+                    }
+                    else {
+                        if (!timers.throttleTimer) {
+                            const remainingTime = options.throttle - (now - timers.lastThrottleCall);
+                            timers.throttleTimer = setTimeout(() => {
+                                timers.throttleTimer = null;
+                                timers.lastThrottleCall = Date.now();
+                                updateDOM(result);
+                            }, remainingTime);
+                        }
                     }
-                    // For throttled calls, don't execute the original method, just return undefined
-                    // The actual render will happen in the scheduled timeout
-                    return undefined;
+                    return result;
                 }
+                // No timing: update DOM immediately
+                updateDOM(result);
+                return result;
             }
-            // No throttle/debounce - render immediately
-            return await renderPart();
         };
-        return descriptor;
     };
 }
 
@@ -2788,7 +2890,16 @@ function Router(options) {
      * @returns A decorator function to apply to a custom element class.
      */
     function page(pageOptions) {
-        return function (constructor) {
+        return function (constructor, context) {
+            // Transfer metadata from context to constructor (for new decorators)
+            if (context.metadata && context.metadata[PROPERTIES]) {
+                if (!constructor[PROPERTIES]) {
+                    constructor[PROPERTIES] = new Map();
+                }
+                for (const [key, value] of context.metadata[PROPERTIES]) {
+                    constructor[PROPERTIES].set(key, value);
+                }
+            }
             // Apply all element functionality (properties, queries, watchers, controllers, etc.)
             applyElementFunctionality(constructor);
             // Store transition config on constructor for later use
@@ -2828,6 +2939,7 @@ function Router(options) {
             customElements.define(pageOptions.tag, constructor);
             // Register the routes with guards and layout
             pageOptions.routes.forEach(route => register(route, pageOptions.tag, pageOptions.transition, pageOptions.guards, pageOptions.layout));
+            return constructor;
         };
     }
     /**