snice 2.5.4 → 3.2.0

package/dist/index.esm.js

@@ -1,6 +1,6 @@
 /*!
- * snice v2.5.3
- * Imperative TypeScript framework for building vanilla web components with decorators, routing, and controllers. No virtual DOM, no build complexity.
+ * snice v3.1.0
+ * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.
  */
@@ -36,10 +36,12 @@ const CHANNEL_HANDLERS = getSymbol('channel-handlers');
 // Internal element state symbols
 const READY_PROMISE = getSymbol('ready-promise');
 const READY_RESOLVE = getSymbol('ready-resolve');
+getSymbol('rendered-promise');
+getSymbol('rendered-resolve');
 const CONTROLLER = getSymbol('controller');
 const INITIALIZED = getSymbol('initialized');
 // Event handler symbols
-const ON_HANDLERS = getSymbol('on-handlers');
+getSymbol('on-handlers');
 // Controller symbols
 const CONTROLLER_KEY = getSymbol('controller-key');
 const CONTROLLER_NAME_KEY = getSymbol('controller-name');
@@ -51,13 +53,14 @@ const CLEANUP = getSymbol('cleanup');
 // Property symbols
 const PROPERTIES = getSymbol('properties');
 const PROPERTY_VALUES = getSymbol('property-values');
+const PRE_INIT_PROPERTY_VALUES = getSymbol('pre-init-property-values');
 const PROPERTIES_INITIALIZED = getSymbol('properties-initialized');
 const PROPERTY_WATCHERS = getSymbol('property-watchers');
 const EXPLICITLY_SET_PROPERTIES = getSymbol('explicitly-set-properties');
 // Router context symbol
 const ROUTER_CONTEXT = getSymbol('router-context');
 getSymbol('current-page-marker');
-const CONTEXT_REQUEST_HANDLER = getSymbol('context-request-handler');
+getSymbol('context-request-handler');
 const PAGE_TRANSITION = getSymbol('page-transition');
 const CREATED_AT = getSymbol('created-at');
 // Lifecycle symbols
@@ -68,313 +71,34 @@ const ADOPTED_HANDLERS = getSymbol('adopted-handlers');
 // Observer symbols
 const OBSERVERS = getSymbol('observers');
 // Part symbols
-const PARTS = getSymbol('parts');
-const PART_TIMERS = getSymbol('part-timers');
+getSymbol('parts');
+getSymbol('part-timers');
 // Lifecycle callback timers
 const MOVED_TIMERS = getSymbol('moved-timers');
 const ADOPTED_TIMERS = getSymbol('adopted-timers');
 // Dispatch timing symbols
 const DISPATCH_TIMERS = getSymbol('dispatch-timers');
-
-function on(eventName, selectorOrOptions, options) {
-    // Handle overloaded parameters
-    let selector;
-    let opts;
-    if (typeof selectorOrOptions === 'string') {
-        selector = selectorOrOptions;
-        opts = options;
-    }
-    else {
-        selector = undefined;
-        opts = selectorOrOptions;
-    }
-    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
-function setupEventHandlers(instance, element) {
-    const handlers = instance.constructor.prototype[ON_HANDLERS];
-    if (!handlers)
-        return;
-    // Initialize cleanup object if needed
-    if (!instance[CLEANUP]) {
-        instance[CLEANUP] = { events: [], channels: [] };
-    }
-    for (const handler of handlers) {
-        // Get the current method from the instance (preserves decorator stacking)
-        const currentMethod = instance[handler.method.name];
-        const originalMethod = currentMethod ? currentMethod.bind(instance) : handler.method.bind(instance);
-        const handlerOptions = handler.options || {};
-        // Parse event name for key modifiers
-        const [baseEventName, keyModifier] = handler.eventName.split(':');
-        // Create debounced/throttled wrapper if needed
-        const createTimedWrapper = (method) => {
-            if (handlerOptions.debounce) {
-                let timeoutId;
-                return function (...args) {
-                    clearTimeout(timeoutId);
-                    timeoutId = setTimeout(() => method.apply(this, args), handlerOptions.debounce);
-                };
-            }
-            if (handlerOptions.throttle) {
-                let lastCall = 0;
-                let timeoutId;
-                return function (...args) {
-                    const now = Date.now();
-                    const remaining = handlerOptions.throttle - (now - lastCall);
-                    if (remaining <= 0) {
-                        clearTimeout(timeoutId);
-                        lastCall = now;
-                        method.apply(this, args);
-                    }
-                    else if (!timeoutId) {
-                        timeoutId = setTimeout(() => {
-                            lastCall = Date.now();
-                            timeoutId = null;
-                            method.apply(this, args);
-                        }, remaining);
-                    }
-                };
-            }
-            return method;
-        };
-        // Create the event handler with key modifier support
-        const createEventHandler = (method) => {
-            if (keyModifier && (baseEventName === 'keydown' || baseEventName === 'keyup' || baseEventName === 'keypress')) {
-                return (event) => {
-                    const keyEvent = event;
-                    // Helper to normalize key names (e.g., "Space" -> " ")
-                    const normalizeKey = (key) => {
-                        if (key === 'Space')
-                            return ' ';
-                        return key;
-                    };
-                    // Check for "any modifiers" match with ~ prefix
-                    if (keyModifier.startsWith('~')) {
-                        const key = normalizeKey(keyModifier.slice(1)); // Remove the ~ and normalize
-                        // Match if key matches, regardless of modifiers
-                        if (keyEvent.key === key) {
-                            method(event);
-                        }
-                        return;
-                    }
-                    // Check for modifier combinations using +
-                    if (keyModifier.includes('+')) {
-                        const parts = keyModifier.split('+');
-                        const key = normalizeKey(parts[parts.length - 1]); // Last part is the actual key
-                        const modifiers = parts.slice(0, -1); // Everything else is modifiers
-                        // Check the actual key
-                        if (keyEvent.key !== key)
-                            return;
-                        // Create a set of expected modifiers
-                        const expectedModifiers = new Set(modifiers.map((m) => m.toLowerCase()));
-                        const hasCtrl = expectedModifiers.has('ctrl');
-                        const hasShift = expectedModifiers.has('shift');
-                        const hasAlt = expectedModifiers.has('alt');
-                        const hasMeta = expectedModifiers.has('meta') || expectedModifiers.has('cmd');
-                        // Check that expected modifiers are pressed and unexpected ones are not
-                        const modifiersMatch = keyEvent.ctrlKey === hasCtrl &&
-                            keyEvent.shiftKey === hasShift &&
-                            keyEvent.altKey === hasAlt &&
-                            keyEvent.metaKey === hasMeta;
-                        if (modifiersMatch) {
-                            method(event);
-                        }
-                    }
-                    else {
-                        // Default: exact match (no modifiers allowed)
-                        const key = normalizeKey(keyModifier);
-                        // Only match if key matches AND no modifiers are pressed
-                        if (keyEvent.key === key &&
-                            !keyEvent.ctrlKey &&
-                            !keyEvent.shiftKey &&
-                            !keyEvent.altKey &&
-                            !keyEvent.metaKey) {
-                            method(event);
-                        }
-                    }
-                };
-            }
-            return method;
-        };
-        // Apply timing wrapper (debounce/throttle)
-        const timedMethod = createTimedWrapper(originalMethod);
-        // Wrap boundMethod in try-catch for error isolation
-        const wrappedMethod = createEventHandler((event) => {
-            try {
-                // Apply automatic preventDefault/stopPropagation if configured
-                if (handlerOptions.preventDefault) {
-                    event.preventDefault();
-                }
-                if (handlerOptions.stopPropagation) {
-                    event.stopPropagation();
-                }
-                return timedMethod(event);
-            }
-            catch (error) {
-                console.error(`Error in event handler ${handler.methodName}:`, error);
-                // Don't rethrow - allow other handlers to continue
-            }
-        });
-        if (handler.selector) {
-            // Delegated event handling - use shadow root if available
-            const eventRoot = element.shadowRoot || element;
-            const delegatedHandler = (event) => {
-                const target = event.target;
-                let shouldHandle = false;
-                if (target.matches && target.matches(handler.selector)) {
-                    shouldHandle = true;
-                }
-                else if (target.closest) {
-                    const closest = target.closest(handler.selector);
-                    if (closest) {
-                        shouldHandle = true;
-                    }
-                }
-                if (shouldHandle) {
-                    // Apply automatic preventDefault/stopPropagation only if we're handling this event
-                    if (handlerOptions.preventDefault) {
-                        event.preventDefault();
-                    }
-                    if (handlerOptions.stopPropagation) {
-                        event.stopPropagation();
-                        event.stopImmediatePropagation(); // Also stop other handlers on same element
-                    }
-                    wrappedMethod(event);
-                }
-            };
-            const listenerOptions = {
-                capture: handlerOptions.capture || false,
-                once: handlerOptions.once || false,
-                passive: handlerOptions.passive || false
-            };
-            eventRoot.addEventListener(baseEventName, delegatedHandler, listenerOptions);
-            instance[CLEANUP].events.push(() => {
-                eventRoot.removeEventListener(baseEventName, delegatedHandler, listenerOptions);
-            });
-        }
-        else {
-            // Direct event handling - always on the element itself
-            const listenerOptions = {
-                capture: handlerOptions.capture || false,
-                once: handlerOptions.once || false,
-                passive: handlerOptions.passive || false
-            };
-            element.addEventListener(baseEventName, wrappedMethod, listenerOptions);
-            instance[CLEANUP].events.push(() => {
-                element.removeEventListener(baseEventName, wrappedMethod, listenerOptions);
-            });
-        }
-    }
-}
-// Helper to cleanup event handlers
-function cleanupEventHandlers(instance) {
-    if (instance[CLEANUP]?.events) {
-        for (const cleanup of instance[CLEANUP].events) {
-            cleanup();
-        }
-        instance[CLEANUP].events = [];
-    }
-}
-/**
- * Decorator that automatically dispatches a custom event after a method is called.
- * The return value of the method becomes the event detail.
- *
- * @param eventName The name of the event to dispatch
- * @param options Optional configuration extending EventInit
- */
-function dispatch(eventName, options) {
-    return function (originalMethod, _context) {
-        return function (...args) {
-            // Create timing wrappers for dispatch (per-instance)
-            if (!this[DISPATCH_TIMERS]) {
-                this[DISPATCH_TIMERS] = new Map();
-            }
-            const timerKey = `${eventName}_${_context.name}`;
-            if (!this[DISPATCH_TIMERS].has(timerKey)) {
-                this[DISPATCH_TIMERS].set(timerKey, {
-                    debounceTimeout: null,
-                    throttleLastCall: 0,
-                    throttleTimeout: null
-                });
-            }
-            const timers = this[DISPATCH_TIMERS].get(timerKey);
-            // Call the original method with preserved this context
-            const result = originalMethod.apply(this, args);
-            // Helper to dispatch the event
-            const doDispatch = (detail) => {
-                // Skip dispatch if result is undefined and dispatchOnUndefined is false
-                if (detail === undefined && options?.dispatchOnUndefined === false) {
-                    return;
-                }
-                // Create event with spread operator for options
-                const event = new CustomEvent(eventName, {
-                    bubbles: true, // Default to true for component events
-                    composed: true, // Allow crossing shadow DOM boundaries
-                    ...options, // Spread all EventInit options
-                    detail
-                });
-                this.dispatchEvent(event);
-            };
-            // Helper to handle timed dispatch
-            const timedDispatch = (detail) => {
-                if (options?.debounce) {
-                    clearTimeout(timers.debounceTimeout);
-                    timers.debounceTimeout = setTimeout(() => doDispatch(detail), options.debounce);
-                }
-                else if (options?.throttle) {
-                    const now = Date.now();
-                    const remaining = options.throttle - (now - timers.throttleLastCall);
-                    if (remaining <= 0) {
-                        clearTimeout(timers.throttleTimeout);
-                        timers.throttleLastCall = now;
-                        doDispatch(detail);
-                    }
-                    else if (!timers.throttleTimeout) {
-                        timers.throttleTimeout = setTimeout(() => {
-                            timers.throttleLastCall = Date.now();
-                            timers.throttleTimeout = null;
-                            doDispatch(detail);
-                        }, remaining);
-                    }
-                }
-                else {
-                    doDispatch(detail);
-                }
-            };
-            // Handle async methods
-            if (result instanceof Promise) {
-                return result.then((resolvedResult) => {
-                    timedDispatch(resolvedResult);
-                    return resolvedResult;
-                });
-            }
-            // Sync method
-            timedDispatch(result);
-            return result;
-        };
-    };
-}
+// Render symbols (v3.0.0)
+const RENDER_METHOD = getSymbol('render-method');
+const RENDER_OPTIONS = getSymbol('render-options');
+const RENDER_INSTANCE = getSymbol('render-instance');
+const RENDER_SCHEDULED = getSymbol('render-scheduled');
+const RENDER_TIMERS = getSymbol('render-timers');
+const RENDER_CALLBACKS = getSymbol('render-callbacks');
+const STYLES_METHOD = getSymbol('styles-method');
+const STYLES_APPLIED = getSymbol('styles-applied');
+// Navigation context symbols
+const CONTEXT_HANDLER = getSymbol('context-handler');
+getSymbol('context-method-name');
+const NAVIGATION_CONTEXT_INSTANCE = getSymbol('navigation-context-instance');
+const REGISTERED_ELEMENTS = getSymbol('registered-elements');
+const IS_UPDATING = getSymbol('is-updating');
+const CONTEXT_REGISTER = getSymbol('context-register');
+const CONTEXT_UNREGISTER = getSymbol('context-unregister');
+const CONTEXT_NOTIFY_ELEMENT = getSymbol('context-notify-element');
+getSymbol('context-options');
+const CONTEXT_TIMER = getSymbol('context-timer');
+const CONTEXT_CALLED = getSymbol('context-called');
 
 // Global cache for MediaQueryList objects
 const mediaQueryCache = new Map();
@@ -401,21 +125,22 @@ function observe(observeTarget, selectorOrOptions, options) {
     }
     return function (target, context) {
         const propertyKey = context.name;
+        const initKey = `__observe_init_${propertyKey}`;
         context.addInitializer(function () {
             const constructor = this.constructor;
-            // Store observer metadata
-            if (!constructor.prototype[OBSERVERS]) {
-                constructor.prototype[OBSERVERS] = [];
+            if (constructor[initKey])
+                return;
+            constructor[initKey] = true;
+            if (!constructor[OBSERVERS]) {
+                constructor[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({
+                const targetStr = modifiers.join(':');
+                constructor[OBSERVERS].push({
                     type,
-                    target: modifiers.join(':'), // Rejoin for media queries or mutation types
+                    target: targetStr,
                     selector,
                     methodName: propertyKey,
                     method: target,
@@ -427,8 +152,7 @@ function observe(observeTarget, selectorOrOptions, options) {
 }
 // Helper to setup observers for elements
 function setupObservers(instance, element) {
-    // Only check the prototype, not the instance itself to avoid property access issues
-    const observers = instance.constructor.prototype[OBSERVERS];
+    const observers = instance.constructor[OBSERVERS];
     if (!observers || !Array.isArray(observers) || observers.length === 0) {
         return;
     }
@@ -856,14 +580,16 @@ function request(requestName, options) {
 function respond(requestName, options) {
     return function (target, context) {
         const propertyKey = context.name;
+        const initKey = `__respond_init_${requestName}_${propertyKey}`;
         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] = [];
+            if (constructor[initKey])
+                return;
+            constructor[initKey] = true;
+            if (!constructor[CHANNEL_HANDLERS]) {
+                constructor[CHANNEL_HANDLERS] = [];
             }
-            constructor.prototype[CHANNEL_HANDLERS].push({
+            constructor[CHANNEL_HANDLERS].push({
                 channelName: requestName,
                 methodName: propertyKey,
                 method: target,
@@ -874,7 +600,7 @@ function respond(requestName, options) {
 }
 // Helper to setup response handlers for elements and controllers
 function setupResponseHandlers(instance, element) {
-    const handlers = instance.constructor.prototype[CHANNEL_HANDLERS];
+    const handlers = instance.constructor[CHANNEL_HANDLERS];
     if (!handlers)
         return;
     // Store cleanup functions
@@ -974,71 +700,1263 @@ function cleanupResponseHandlers(instance) {
     }
 }
 
-// Controller-scoped cleanup registry
-class ControllerScope {
-    constructor() {
-        this.cleanupFns = new Map();
-        this.pendingOperations = new Set();
-    }
-    register(key, cleanup) {
-        this.cleanupFns.set(key, cleanup);
-    }
-    unregister(key) {
-        this.cleanupFns.delete(key);
-    }
-    async cleanup() {
-        // Wait for all pending operations
-        await Promise.all(this.pendingOperations);
-        // Run all cleanup functions
-        for (const cleanup of this.cleanupFns.values()) {
-            try {
-                await cleanup();
-            }
-            catch (error) {
-                console.error('Error during cleanup:', error);
-            }
-        }
-        this.cleanupFns.clear();
+/**
+ * Template system for Snice v3.0.0
+ * Provides html`` and css`` tagged template processors with differential rendering
+ */
+// Unique symbols for type checking
+const HTML_RESULT = Symbol('html-result');
+const CSS_RESULT = Symbol('css-result');
+/**
+ * Tagged template function for creating HTML templates
+ *
+ * @example
+ * ```typescript
+ * html`<div class="card">
+ *   <h1>${this.title}</h1>
+ *   <button @click=${this.handleClick}>Click me</button>
+ * </div>`
+ * ```
+ */
+function html(strings, ...values) {
+    return {
+        _$litType$: HTML_RESULT,
+        strings,
+        values
+    };
+}
+/**
+ * Tagged template function for creating CSS
+ *
+ * @example
+ * ```typescript
+ * css`:host {
+ *   display: block;
+ *   padding: 1rem;
+ * }`
+ * ```
+ */
+function css(strings, ...values) {
+    // Combine strings and values into final CSS text
+    let cssText = strings[0];
+    for (let i = 0; i < values.length; i++) {
+        cssText += String(values[i]) + strings[i + 1];
     }
-    async runOperation(operation) {
-        const promise = operation();
-        const voidPromise = promise.then(() => { }, () => { });
-        this.pendingOperations.add(voidPromise);
+    const result = {
+        _$litType$: CSS_RESULT,
+        cssText
+    };
+    // Try to create constructable stylesheet for better performance
+    // This will be cached and reused across instances
+    if (typeof CSSStyleSheet !== 'undefined' && 'adoptedStyleSheets' in Document.prototype) {
         try {
-            const result = await promise;
-            this.pendingOperations.delete(voidPromise);
-            return result;
+            const sheet = new CSSStyleSheet();
+            sheet.replaceSync(cssText);
+            result.styleSheet = sheet;
         }
-        catch (error) {
-            this.pendingOperations.delete(voidPromise);
-            throw error;
+        catch (e) {
+            // Fall back to regular <style> tag if constructable stylesheets fail
         }
     }
+    return result;
 }
 /**
- * Decorator to register a controller class with a name
- * @param name The name to register the controller under
+ * Check if a value is a TemplateResult
  */
-function controller(name) {
-    return function (constructor, _context) {
-        snice.controllerRegistry.set(name, constructor);
-        // Mark as controller class for channel decorator detection
-        constructor.prototype[IS_CONTROLLER_CLASS] = true;
-        return constructor;
-    };
+function isTemplateResult(value) {
+    return value && value._$litType$ === HTML_RESULT;
 }
 /**
- * Attaches a controller to an element
- * @param element The element to attach the controller to
- * @param controllerName The name of the controller to attach
+ * Check if a value is a CSSResult
  */
-async function attachController(element, controllerName) {
-    const existingController = element[CONTROLLER_KEY];
-    const existingName = element[CONTROLLER_NAME_KEY];
-    // For native elements, check if this is actually the desired controller
-    const nativeController = element[NATIVE_CONTROLLER];
-    if (nativeController !== undefined && nativeController !== controllerName) {
-        // This attachment is outdated, skip it
+function isCSSResult(value) {
+    return value && value._$litType$ === CSS_RESULT;
+}
+/**
+ * Nothing - represents no value (different from null/undefined)
+ * Used to remove content from templates
+ */
+const nothing = Symbol('nothing');
+// Unique symbol for unsafe HTML
+const UNSAFE_HTML = Symbol('unsafe-html');
+/**
+ * Mark a string as raw HTML that should not be escaped
+ * WARNING: Only use with sanitized content - using user input can lead to XSS!
+ *
+ * @example
+ * ```typescript
+ * const htmlString = '<span class="bold">Hello</span>';
+ * html`<div>${unsafeHTML(htmlString)}</div>`
+ * ```
+ */
+function unsafeHTML(html) {
+    return {
+        _$litType$: UNSAFE_HTML,
+        html
+    };
+}
+/**
+ * Check if a value is an UnsafeHTML wrapper
+ */
+function isUnsafeHTML(value) {
+    return value && value._$litType$ === UNSAFE_HTML;
+}
+
+// Unique marker for dynamic parts
+// This parses as a comment node but doesn't get escaped in attributes
+const marker = `snice$${Math.random().toFixed(9).slice(2)}$`;
+const markerMatch = '?' + marker;
+const nodeMarker = `<${markerMatch}>`;
+const markerRegex = new RegExp(marker, 'g');
+// Template cache - templates with same string array can be reused
+const templateCache = new WeakMap();
+/**
+ * A prepared template ready for rendering
+ */
+class Template {
+    constructor(result, element, attrNamesForParts) {
+        this.parts = [];
+        this.element = element;
+        const walker = document.createTreeWalker(element.content, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_COMMENT | NodeFilter.SHOW_TEXT);
+        let partIndex = 0;
+        const nodesToRemove = [];
+        let node;
+        while ((node = walker.nextNode()) !== null) {
+            if (node.nodeType === Node.ELEMENT_NODE) {
+                const element = node;
+                const tagName = element.tagName.toLowerCase();
+                // Handle virtual elements: <if>, <case>
+                // Keep them in the DOM with display:contents for now
+                // Will optimize later with proper template extraction
+                if (tagName === 'if') {
+                    // <if value="${condition}">children</if>
+                    const valueAttr = element.getAttribute('value');
+                    if (valueAttr && valueAttr.includes(marker)) {
+                        // Remove the value attribute
+                        element.removeAttribute('value');
+                        this.parts.push({
+                            type: 'conditional-if',
+                            index: partIndex++,
+                            element // Keep the <if> element
+                        });
+                        // Continue processing children normally
+                    }
+                    continue;
+                }
+                // Handle <case> element
+                if (tagName === 'case') {
+                    // <case value="${value}">children</case>
+                    const valueAttr = element.getAttribute('value');
+                    if (valueAttr && valueAttr.includes(marker)) {
+                        // Remove the value attribute
+                        element.removeAttribute('value');
+                        this.parts.push({
+                            type: 'conditional-case',
+                            index: partIndex++,
+                            element // Keep the <case> element
+                        });
+                        // Continue processing children normally
+                    }
+                    continue;
+                }
+                if (element.hasAttributes()) {
+                    const attributes = element.attributes;
+                    const attrsToRemove = [];
+                    for (let i = 0; i < attributes.length; i++) {
+                        const attr = attributes[i];
+                        const value = attr.value;
+                        // Check for attribute bindings
+                        if (value.includes(marker)) {
+                            attrsToRemove.push(attr);
+                            // Get original attribute name with preserved case
+                            const originalName = attrNamesForParts[partIndex] || attr.name;
+                            // Extract static string segments by splitting on marker
+                            const attrStrings = value.split(marker);
+                            if (originalName.startsWith('@')) {
+                                // Event binding
+                                this.parts.push({
+                                    type: 'event',
+                                    index: partIndex++,
+                                    name: originalName.slice(1),
+                                    element
+                                });
+                            }
+                            else if (originalName.startsWith('.')) {
+                                // Property binding - preserve original case for JavaScript properties
+                                this.parts.push({
+                                    type: 'property',
+                                    index: partIndex++,
+                                    name: originalName.slice(1),
+                                    element
+                                });
+                            }
+                            else if (originalName.startsWith('?')) {
+                                // Boolean attribute
+                                this.parts.push({
+                                    type: 'boolean-attribute',
+                                    index: partIndex++,
+                                    name: originalName.slice(1),
+                                    element
+                                });
+                            }
+                            else {
+                                // Regular attribute - use lowercased name from DOM
+                                // Store static string segments for interpolation
+                                this.parts.push({
+                                    type: 'attribute',
+                                    index: partIndex++,
+                                    name: attr.name,
+                                    element,
+                                    attrStrings
+                                });
+                            }
+                        }
+                    }
+                    // Remove marker attributes
+                    for (const attr of attrsToRemove) {
+                        element.removeAttribute(attr.name);
+                    }
+                }
+            }
+            else if (node.nodeType === Node.COMMENT_NODE) {
+                const comment = node;
+                // Check for marker match (processing instruction becomes comment)
+                if (comment.data === markerMatch) {
+                    // Node part
+                    const parent = comment.parentNode;
+                    const endNode = document.createComment('');
+                    parent.insertBefore(endNode, comment.nextSibling);
+                    this.parts.push({
+                        type: 'node',
+                        index: partIndex++,
+                        startNode: comment,
+                        endNode
+                    });
+                }
+            }
+            else if (node.nodeType === Node.TEXT_NODE) {
+                const text = node;
+                const data = text.data;
+                if (data.includes(marker)) {
+                    // Split text node at markers
+                    const parent = text.parentNode;
+                    const parts = data.split(markerRegex);
+                    const lastIndex = parts.length - 1;
+                    for (let i = 0; i < lastIndex; i++) {
+                        parent.insertBefore(document.createTextNode(parts[i]), text);
+                        const comment = document.createComment('');
+                        const endNode = document.createComment('');
+                        parent.insertBefore(comment, text);
+                        parent.insertBefore(endNode, text);
+                        this.parts.push({
+                            type: 'node',
+                            index: partIndex++,
+                            startNode: comment,
+                            endNode
+                        });
+                    }
+                    // Last part
+                    if (parts[lastIndex] !== '') {
+                        text.data = parts[lastIndex];
+                    }
+                    else {
+                        nodesToRemove.push(text);
+                    }
+                }
+            }
+        }
+        // Remove marker nodes
+        for (const node of nodesToRemove) {
+            node.parentNode?.removeChild(node);
+        }
+    }
+}
+/**
+ * Prepare a template for rendering
+ */
+function prepareTemplate(result) {
+    // Check cache first
+    const { strings } = result;
+    const cached = templateCache.get(strings);
+    if (cached) {
+        return cached;
+    }
+    // Build HTML with markers and extract original attribute names
+    const htmlParts = [];
+    const attrNamesForParts = [];
+    for (let i = 0; i < strings.length; i++) {
+        const str = strings[i];
+        htmlParts.push(str);
+        if (i < strings.length - 1) {
+            // Check if we're in an attribute context
+            // Look backwards for = sign
+            const lastEquals = str.lastIndexOf('=');
+            const lastCloseTag = str.lastIndexOf('>');
+            if (lastEquals > lastCloseTag) {
+                // We're in an attribute value - extract and preserve the original attribute name
+                let attrStart = lastEquals - 1;
+                while (attrStart >= 0 && /\S/.test(str[attrStart])) {
+                    attrStart--;
+                }
+                const attrName = str.substring(attrStart + 1, lastEquals).trim();
+                attrNamesForParts.push(attrName);
+                htmlParts.push(marker);
+            }
+            else {
+                // Check if this is a meta element (<if> or <case>) by looking backwards
+                // Match pattern: <if or <case followed by whitespace or >
+                const metaElementMatch = str.match(/<(if|case)\s*$/);
+                if (metaElementMatch) {
+                    // This is a meta element - add value attribute
+                    attrNamesForParts.push('value');
+                    htmlParts.push(`value="${marker}"`);
+                }
+                else {
+                    // We're in node content
+                    attrNamesForParts.push(''); // Empty string for node parts
+                    htmlParts.push(nodeMarker);
+                }
+            }
+        }
+    }
+    const html = htmlParts.join('');
+    const template = document.createElement('template');
+    template.innerHTML = html;
+    const tmpl = new Template(result, template, attrNamesForParts);
+    // Cache the template for reuse
+    templateCache.set(strings, tmpl);
+    return tmpl;
+}
+/**
+ * Instance of a rendered template
+ */
+class TemplateInstance {
+    constructor(result) {
+        this.parts = [];
+        this.fragment = null;
+        this.conditionalParts = []; // if/case parts with their indices
+        this.regularParts = []; // all other parts with their indices
+        this.template = prepareTemplate(result);
+    }
+    renderFragment() {
+        if (!this.fragment) {
+            // First render - clone template and create parts
+            this.fragment = this.template.element.content.cloneNode(true);
+            // Build a map of nodes from template to cloned fragment
+            const walker = document.createTreeWalker(this.template.element.content, NodeFilter.SHOW_ALL);
+            const clonedWalker = document.createTreeWalker(this.fragment, NodeFilter.SHOW_ALL);
+            const nodeMap = new Map();
+            let templateNode = walker.currentNode;
+            let clonedNode = clonedWalker.currentNode;
+            while (templateNode && clonedNode) {
+                nodeMap.set(templateNode, clonedNode);
+                templateNode = walker.nextNode();
+                clonedNode = clonedWalker.nextNode();
+            }
+            for (let i = 0; i < this.template.parts.length; i++) {
+                const partDef = this.template.parts[i];
+                let part;
+                switch (partDef.type) {
+                    case 'node':
+                        const startNode = nodeMap.get(partDef.startNode);
+                        const endNode = nodeMap.get(partDef.endNode);
+                        part = new NodePart(startNode, endNode);
+                        break;
+                    case 'attribute':
+                        const attrElement = nodeMap.get(partDef.element);
+                        part = new AttributePart(attrElement, partDef.name, partDef.attrStrings);
+                        break;
+                    case 'property':
+                        const propElement = nodeMap.get(partDef.element);
+                        part = new PropertyPart(propElement, partDef.name);
+                        break;
+                    case 'boolean-attribute':
+                        const boolElement = nodeMap.get(partDef.element);
+                        part = new BooleanAttributePart(boolElement, partDef.name);
+                        break;
+                    case 'event':
+                        const eventElement = nodeMap.get(partDef.element);
+                        part = new EventPart(eventElement, partDef.name);
+                        break;
+                    case 'conditional-if':
+                        const conditionalIfElement = nodeMap.get(partDef.element);
+                        part = new ConditionalIfPart(conditionalIfElement);
+                        break;
+                    case 'conditional-case':
+                        const conditionalCaseElement = nodeMap.get(partDef.element);
+                        part = new ConditionalCasePart(conditionalCaseElement);
+                        break;
+                    default:
+                        throw new Error(`Unknown part type: ${partDef.type}`);
+                }
+                this.parts.push(part);
+                // Separate conditional parts from regular parts for optimized update
+                if (part instanceof ConditionalIfPart || part instanceof ConditionalCasePart) {
+                    this.conditionalParts.push({ part, index: i });
+                }
+                else {
+                    this.regularParts.push({ part, index: i });
+                }
+            }
+        }
+        return this.fragment;
+    }
+    render(values) {
+        const fragment = this.renderFragment();
+        // Commit values to parts
+        this.update(values);
+        return fragment;
+    }
+    update(values) {
+        // Optimized: Process conditional parts first (if any), then regular parts
+        // Using pre-separated arrays with cached indices avoids instanceof and indexOf calls
+        // Process conditional parts first (they control visibility)
+        for (const { part, index } of this.conditionalParts) {
+            part.commit(values[index]);
+        }
+        // Then process regular parts
+        for (const { part, index } of this.regularParts) {
+            part.commit(values[index]);
+        }
+    }
+    clear() {
+        for (const part of this.parts) {
+            part.clear();
+        }
+    }
+}
+/**
+ * Base class for all parts
+ */
+class Part {
+}
+/**
+ * NodePart handles text content and nested templates
+ */
+class NodePart extends Part {
+    constructor(startNode, endNode) {
+        super();
+        this.value = undefined;
+        this.startNode = startNode;
+        this.endNode = endNode;
+    }
+    commit(value) {
+        if (value === this.value)
+            return;
+        this.value = value;
+        // Handle arrays
+        if (Array.isArray(value)) {
+            this.commitArray(value);
+            return;
+        }
+        // Handle nested templates
+        if (isTemplateResult(value)) {
+            this.commitTemplate(value);
+            return;
+        }
+        // Handle unsafe HTML
+        if (isUnsafeHTML(value)) {
+            this.commitUnsafeHTML(value);
+            return;
+        }
+        // Handle primitives
+        this.commitPrimitive(value);
+    }
+    commitPrimitive(value) {
+        this.clear();
+        const text = value === null || value === undefined ? '' : String(value);
+        const textNode = document.createTextNode(text);
+        this.insertBefore(textNode);
+    }
+    commitTemplate(template) {
+        this.clear();
+        const instance = new TemplateInstance(template);
+        const fragment = instance.render(template.values);
+        this.insertBefore(fragment);
+    }
+    commitArray(values) {
+        this.clear();
+        // Template caching (via prepareTemplate) still provides significant performance benefit
+        for (const value of values) {
+            if (isTemplateResult(value)) {
+                const instance = new TemplateInstance(value);
+                const fragment = instance.render(value.values);
+                this.insertBefore(fragment);
+            }
+            else {
+                const text = value === null || value === undefined ? '' : String(value);
+                const textNode = document.createTextNode(text);
+                this.insertBefore(textNode);
+            }
+        }
+    }
+    commitUnsafeHTML(value) {
+        this.clear();
+        // Create a temporary container to parse the HTML
+        const temp = document.createElement('template');
+        temp.innerHTML = value.html;
+        // Insert all parsed nodes
+        const fragment = temp.content;
+        this.insertBefore(fragment);
+    }
+    insertBefore(node) {
+        this.endNode.parentNode?.insertBefore(node, this.endNode);
+    }
+    clear() {
+        const parent = this.startNode.parentNode;
+        if (!parent)
+            return;
+        let node = this.startNode.nextSibling;
+        while (node && node !== this.endNode) {
+            const next = node.nextSibling;
+            parent.removeChild(node);
+            node = next;
+        }
+    }
+}
+/**
+ * AttributePart handles regular attribute updates
+ */
+class AttributePart extends Part {
+    constructor(element, name, attrStrings) {
+        super();
+        this.value = undefined;
+        this.element = element;
+        this.name = name;
+        this.attrStrings = attrStrings;
+    }
+    commit(value) {
+        if (value === this.value)
+            return;
+        this.value = value;
+        if (value === null || value === undefined) {
+            this.element.removeAttribute(this.name);
+        }
+        else {
+            // Inline attribute value computation for performance
+            let finalValue;
+            if (!this.attrStrings || this.attrStrings.length === 0) {
+                finalValue = String(value);
+            }
+            else if (this.attrStrings.length === 1) {
+                finalValue = this.attrStrings[0];
+            }
+            else {
+                // Multiple segments: "prefix" + value + "suffix"
+                finalValue = this.attrStrings[0] + String(value) + this.attrStrings[1];
+            }
+            this.element.setAttribute(this.name, finalValue);
+        }
+    }
+    clear() {
+        this.element.removeAttribute(this.name);
+    }
+}
+/**
+ * PropertyPart handles property bindings
+ */
+class PropertyPart extends Part {
+    constructor(element, name) {
+        super();
+        this.value = undefined;
+        this.element = element;
+        this.name = name;
+    }
+    commit(value) {
+        if (value === this.value)
+            return;
+        this.value = value;
+        this.element[this.name] = value;
+    }
+    clear() {
+        this.element[this.name] = undefined;
+    }
+}
+/**
+ * BooleanAttributePart handles boolean attributes
+ */
+class BooleanAttributePart extends Part {
+    constructor(element, name) {
+        super();
+        this.value = undefined;
+        this.element = element;
+        this.name = name;
+    }
+    commit(value) {
+        if (value === this.value)
+            return;
+        this.value = value;
+        if (value) {
+            this.element.setAttribute(this.name, '');
+        }
+        else {
+            this.element.removeAttribute(this.name);
+        }
+    }
+    clear() {
+        this.element.removeAttribute(this.name);
+    }
+}
+/**
+ * EventPart handles event listener bindings with keyboard shortcut support
+ */
+class EventPart extends Part {
+    constructor(element, eventName) {
+        super();
+        this.listener = null;
+        this.value = undefined;
+        this.keyFilter = null;
+        this.host = null; // Cache host element
+        this.element = element;
+        // Parse keyboard shortcuts:
+        // Supports both dot notation (@keydown.enter) and colon notation (@keydown:Enter) to match @on decorator
+        const dotIndex = eventName.indexOf('.');
+        const colonIndex = eventName.indexOf(':');
+        // Use whichever delimiter comes first (dot or colon)
+        const delimiterIndex = dotIndex > 0 && colonIndex > 0
+            ? Math.min(dotIndex, colonIndex)
+            : Math.max(dotIndex, colonIndex);
+        if (delimiterIndex > 0) {
+            const baseEvent = eventName.substring(0, delimiterIndex);
+            const keySpec = eventName.substring(delimiterIndex + 1);
+            this.eventName = baseEvent;
+            this.keyFilter = parseKeyboardFilter(keySpec);
+        }
+        else {
+            this.eventName = eventName;
+        }
+    }
+    commit(value) {
+        // Skip if same value (but null/undefined always triggers update)
+        if (value === this.value && value !== null && value !== undefined)
+            return;
+        // Remove old listener
+        if (this.listener) {
+            this.element.removeEventListener(this.eventName, this.listener);
+            this.listener = null;
+        }
+        this.value = value;
+        // Add new listener
+        if (value === null || value === undefined) {
+            return;
+        }
+        if (typeof value === 'function') {
+            // Auto-bind to host element (the custom element with shadow root)
+            // Cache host lookup for performance
+            if (!this.host) {
+                const rootNode = this.element.getRootNode();
+                this.host = rootNode.host || null;
+            }
+            // Create a wrapper that calls the handler with the host as context
+            if (this.host) {
+                const host = this.host; // Capture for closure
+                this.listener = ((event) => {
+                    if (this.keyFilter && !matchesKeyboardFilter(event, this.keyFilter)) {
+                        return;
+                    }
+                    value.call(host, event);
+                });
+            }
+            else {
+                this.listener = ((event) => {
+                    if (this.keyFilter && !matchesKeyboardFilter(event, this.keyFilter)) {
+                        return;
+                    }
+                    value.call(null, event);
+                });
+            }
+            this.element.addEventListener(this.eventName, this.listener);
+        }
+    }
+    clear() {
+        if (this.listener) {
+            this.element.removeEventListener(this.eventName, this.listener);
+            this.listener = null;
+        }
+    }
+}
+/**
+ * Parse keyboard shortcut specification
+ * Examples:
+ *   "enter" -> { key: "Enter" }
+ *   "ctrl+s" -> { key: "s", ctrl: true }
+ *   "ctrl+shift+s" -> { key: "s", ctrl: true, shift: true }
+ *   "~enter" -> { key: "Enter", anyModifiers: true }
+ */
+function parseKeyboardFilter(spec) {
+    // Handle ~ prefix for matching regardless of modifiers
+    const anyModifiers = spec.startsWith('~');
+    if (anyModifiers) {
+        spec = spec.substring(1);
+    }
+    const parts = spec.split('+');
+    const filter = {
+        key: '',
+        anyModifiers
+    };
+    for (const part of parts) {
+        const lower = part.toLowerCase();
+        if (lower === 'ctrl' || lower === 'control') {
+            filter.ctrl = true;
+        }
+        else if (lower === 'alt') {
+            filter.alt = true;
+        }
+        else if (lower === 'shift') {
+            filter.shift = true;
+        }
+        else if (lower === 'meta' || lower === 'cmd' || lower === 'command') {
+            filter.meta = true;
+        }
+        else {
+            // This is the key itself - normalize common keys
+            filter.key = normalizeKey(part);
+        }
+    }
+    return filter;
+}
+/**
+ * Normalize key names to match KeyboardEvent.key
+ */
+function normalizeKey(key) {
+    const keyMap = {
+        'esc': 'Escape',
+        'escape': 'Escape',
+        'enter': 'Enter',
+        'return': 'Enter',
+        'space': ' ',
+        'spacebar': ' ',
+        'up': 'ArrowUp',
+        'down': 'ArrowDown',
+        'left': 'ArrowLeft',
+        'right': 'ArrowRight',
+        'arrowup': 'ArrowUp',
+        'arrowdown': 'ArrowDown',
+        'arrowleft': 'ArrowLeft',
+        'arrowright': 'ArrowRight',
+        'delete': 'Delete',
+        'del': 'Delete',
+        'backspace': 'Backspace',
+        'tab': 'Tab',
+        'home': 'Home',
+        'end': 'End',
+        'pageup': 'PageUp',
+        'pagedown': 'PageDown'
+    };
+    const lower = key.toLowerCase();
+    return keyMap[lower] || key;
+}
+/**
+ * Check if keyboard event matches the filter
+ */
+function matchesKeyboardFilter(event, filter) {
+    // Check key match
+    if (event.key !== filter.key) {
+        return false;
+    }
+    // If anyModifiers is true, we don't care about modifiers
+    if (filter.anyModifiers) {
+        return true;
+    }
+    // Check modifiers - by default, exact match
+    // If filter specifies ctrl: true, event must have ctrlKey
+    // If filter doesn't specify ctrl, event must NOT have ctrlKey
+    const ctrlMatch = filter.ctrl ? event.ctrlKey : !event.ctrlKey;
+    const altMatch = filter.alt ? event.altKey : !event.altKey;
+    const shiftMatch = filter.shift ? event.shiftKey : !event.shiftKey;
+    const metaMatch = filter.meta ? event.metaKey : !event.metaKey;
+    return ctrlMatch && altMatch && shiftMatch && metaMatch;
+}
+/**
+ * ConditionalIfPart handles <if> conditional rendering
+ * Removes/inserts DOM nodes based on condition
+ */
+class ConditionalIfPart extends Part {
+    constructor(ifElement) {
+        super();
+        this.value = undefined;
+        this.fragment = null;
+        this.ifElement = ifElement;
+        this.ifElement.style.display = 'contents';
+    }
+    commit(value) {
+        const condition = Boolean(value);
+        if (this.value === value)
+            return;
+        this.value = value;
+        if (condition) {
+            // Show: restore children from fragment
+            if (this.fragment && this.fragment.hasChildNodes()) {
+                this.ifElement.appendChild(this.fragment);
+            }
+        }
+        else {
+            // Hide: move children to fragment
+            if (!this.fragment) {
+                this.fragment = document.createDocumentFragment();
+            }
+            while (this.ifElement.firstChild) {
+                this.fragment.appendChild(this.ifElement.firstChild);
+            }
+        }
+    }
+    clear() {
+        if (!this.fragment) {
+            this.fragment = document.createDocumentFragment();
+        }
+        while (this.ifElement.firstChild) {
+            this.fragment.appendChild(this.ifElement.firstChild);
+        }
+    }
+}
+/**
+ * ConditionalCasePart handles <case>/<when>/<default> conditional rendering
+ * Removes/inserts matching branch based on value
+ */
+class ConditionalCasePart extends Part {
+    constructor(caseElement) {
+        super();
+        this.value = undefined;
+        this.childrenMap = new Map();
+        this.fragments = new Map();
+        this.defaultChild = null;
+        this.currentChild = null;
+        this.caseElement = caseElement;
+        // Build map and store children in fragments initially
+        for (const child of Array.from(this.caseElement.children)) {
+            const childTag = child.tagName.toLowerCase();
+            if (childTag === 'when') {
+                const whenValue = child.getAttribute('value') || '';
+                this.childrenMap.set(whenValue, child);
+                const fragment = document.createDocumentFragment();
+                fragment.appendChild(child);
+                this.fragments.set(child, fragment);
+            }
+            else if (childTag === 'default') {
+                this.defaultChild = child;
+                const fragment = document.createDocumentFragment();
+                fragment.appendChild(child);
+                this.fragments.set(child, fragment);
+            }
+        }
+    }
+    commit(value) {
+        if (this.value === value)
+            return;
+        this.value = value;
+        const valueStr = String(value);
+        // Remove current child
+        if (this.currentChild) {
+            const fragment = this.fragments.get(this.currentChild);
+            if (fragment && !fragment.hasChildNodes()) {
+                fragment.appendChild(this.currentChild);
+            }
+        }
+        // Insert matching child
+        const matchingChild = this.childrenMap.get(valueStr) || this.defaultChild;
+        if (matchingChild) {
+            const fragment = this.fragments.get(matchingChild);
+            if (fragment && fragment.hasChildNodes()) {
+                this.caseElement.appendChild(fragment);
+            }
+            this.currentChild = matchingChild;
+        }
+    }
+    clear() {
+        if (this.currentChild) {
+            const fragment = this.fragments.get(this.currentChild);
+            if (fragment && !fragment.hasChildNodes()) {
+                fragment.appendChild(this.currentChild);
+            }
+            this.currentChild = null;
+        }
+    }
+}
+
+/**
+ * @on decorator for listening to events
+ * Use in elements or controllers to listen to DOM events or custom events
+ */
+const ON_HANDLERS = getSymbol('on-handlers');
+/**
+ * @on decorator for listening to events
+ *
+ * Works in both elements and controllers with full event delegation support.
+ *
+ * @param eventName - Event name(s) to listen for
+ * @param selector - Optional CSS selector for event delegation
+ * @param options - Event listener options including debounce/throttle
+ *
+ * @example
+ * ```typescript
+ * // In elements
+ * @element('my-button')
+ * class MyButton extends HTMLElement {
+ *   @on('click', 'button')
+ *   handleClick(e: MouseEvent) {
+ *     console.log('Button clicked!', e);
+ *   }
+ *
+ *   @on('input', 'input', { debounce: 300 })
+ *   handleInput(e: Event) {
+ *     console.log('Input changed:', (e.target as HTMLInputElement).value);
+ *   }
+ * }
+ *
+ * // In controllers
+ * @controller('my-controller')
+ * class MyController {
+ *   element!: HTMLElement;
+ *
+ *   @on('count-changed')
+ *   handleCountChanged(e: CustomEvent) {
+ *     console.log('Count changed to:', e.detail.count);
+ *   }
+ *
+ *   @on('click', '.item', { throttle: 100 })
+ *   handleItemClick(e: MouseEvent) {
+ *     console.log('Item clicked');
+ *   }
+ * }
+ * ```
+ */
+function on(eventName, selectorOrOptions, options) {
+    // Parse arguments to support multiple call signatures
+    let selector = null;
+    let opts = {};
+    if (typeof selectorOrOptions === 'string') {
+        // With selector: (eventName, selector, options)
+        selector = selectorOrOptions;
+        opts = options || {};
+    }
+    else if (selectorOrOptions === null && options) {
+        // With null selector: (eventName, null, options)
+        opts = options;
+    }
+    else if (selectorOrOptions && typeof selectorOrOptions === 'object') {
+        // Without selector: (eventName, options)
+        opts = selectorOrOptions;
+    }
+    return function (originalMethod, context) {
+        const methodName = context.name;
+        const initKey = `__on_init_${methodName}_${selector || ''}_${JSON.stringify(eventName)}`;
+        context.addInitializer(function () {
+            const constructor = this.constructor;
+            // Only initialize once per class, not per instance
+            if (constructor[initKey])
+                return;
+            constructor[initKey] = true;
+            if (!constructor[ON_HANDLERS]) {
+                constructor[ON_HANDLERS] = [];
+            }
+            const eventNames = Array.isArray(eventName) ? eventName : [eventName];
+            for (const event of eventNames) {
+                constructor[ON_HANDLERS].push({
+                    eventName: event,
+                    selector,
+                    methodName,
+                    method: originalMethod,
+                    options: opts
+                });
+            }
+        });
+        return originalMethod;
+    };
+}
+/**
+ * Create a debounced version of a function
+ */
+function debounce$1(fn, delay) {
+    let timeoutId = null;
+    return function (...args) {
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => {
+            fn.apply(this, args);
+            timeoutId = null;
+        }, delay);
+    };
+}
+/**
+ * Create a throttled version of a function (leading edge only)
+ */
+function throttle$1(fn, delay) {
+    let lastCall = 0;
+    return function (...args) {
+        const now = Date.now();
+        const timeSinceLastCall = now - lastCall;
+        if (timeSinceLastCall >= delay) {
+            lastCall = now;
+            fn.apply(this, args);
+        }
+        // Events within the throttle window are simply ignored (leading edge only)
+    };
+}
+/**
+ * Events that don't bubble - these require capture phase for delegation
+ */
+const NON_BUBBLING_EVENTS = new Set([
+    'scroll',
+    'focus',
+    'blur',
+    'load',
+    'unload',
+    'error',
+    'resize',
+    'abort',
+    'mouseenter',
+    'mouseleave',
+    'pointerenter',
+    'pointerleave',
+]);
+/**
+ * Setup event listeners for an element or controller instance
+ * Called automatically during element connection or controller attachment
+ */
+function setupEventHandlers(instance, targetElement) {
+    const handlers = instance.constructor[ON_HANDLERS];
+    if (!handlers || !Array.isArray(handlers) || handlers.length === 0) {
+        return;
+    }
+    // Initialize cleanup object if needed
+    if (!instance[CLEANUP]) {
+        instance[CLEANUP] = { events: [], channels: [], observers: [] };
+    }
+    else if (!instance[CLEANUP].events) {
+        instance[CLEANUP].events = [];
+    }
+    else if (instance[CLEANUP].events.length > 0) {
+        // Events already set up - clean them up first to avoid duplicates
+        cleanupEventHandlers(instance);
+    }
+    for (const handler of handlers) {
+        // Get current method from instance (preserves decorator stacking)
+        const currentMethod = instance[handler.methodName];
+        let boundMethod = currentMethod ? currentMethod.bind(instance) : handler.method.bind(instance);
+        const handlerOptions = handler.options || {};
+        // Parse event name for key modifiers
+        // Supports both dot notation (@keydown.enter) and colon notation (@keydown:Enter)
+        const dotIndex = handler.eventName.indexOf('.');
+        const colonIndex = handler.eventName.indexOf(':');
+        const delimiterIndex = dotIndex > 0 && colonIndex > 0
+            ? Math.min(dotIndex, colonIndex)
+            : Math.max(dotIndex, colonIndex);
+        const baseEventName = delimiterIndex > 0
+            ? handler.eventName.substring(0, delimiterIndex)
+            : handler.eventName;
+        const keyModifier = delimiterIndex > 0
+            ? handler.eventName.substring(delimiterIndex + 1)
+            : null;
+        // Apply debounce if specified
+        if (handlerOptions.debounce && handlerOptions.debounce > 0) {
+            boundMethod = debounce$1(boundMethod, handlerOptions.debounce);
+        }
+        // Apply throttle if specified (debounce takes precedence)
+        else if (handlerOptions.throttle && handlerOptions.throttle > 0) {
+            boundMethod = throttle$1(boundMethod, handlerOptions.throttle);
+        }
+        // Create event handler with key modifier support
+        // Uses shared keyboard filter implementation from parts.ts
+        let keyFilter = null;
+        if (keyModifier && ['keydown', 'keyup', 'keypress'].includes(baseEventName)) {
+            keyFilter = parseKeyboardFilter(keyModifier);
+        }
+        const createKeyModifierHandler = (method) => {
+            if (!keyFilter) {
+                return method;
+            }
+            return (event) => {
+                const keyEvent = event;
+                if (matchesKeyboardFilter(keyEvent, keyFilter)) {
+                    method(event);
+                }
+            };
+        };
+        // Apply key modifier wrapper
+        const keyModifierMethod = createKeyModifierHandler(boundMethod);
+        // Main event handler with error handling and event delegation
+        if (handler.selector) {
+            // Delegated event handling - use shadow root if available
+            const eventRoot = targetElement.shadowRoot || targetElement;
+            const delegatedHandler = (event) => {
+                const target = event.target;
+                let matchingElement = null;
+                // Check if target itself matches the selector
+                if (target.matches && target.matches(handler.selector)) {
+                    matchingElement = target;
+                }
+                // Check if any parent matches the selector (event delegation)
+                else if (target.closest) {
+                    matchingElement = target.closest(handler.selector);
+                }
+                // Only handle if we found a match
+                // Note: No need to check contains() since the event bubbled to eventRoot
+                if (matchingElement) {
+                    // Apply automatic preventDefault/stopPropagation
+                    if (handlerOptions.preventDefault) {
+                        event.preventDefault();
+                    }
+                    if (handlerOptions.stopPropagation) {
+                        event.stopPropagation();
+                        event.stopImmediatePropagation();
+                    }
+                    try {
+                        keyModifierMethod(event);
+                    }
+                    catch (error) {
+                        console.error(`Error in event handler ${handler.methodName}:`, error);
+                    }
+                }
+            };
+            // Auto-enable capture for non-bubbling events when using delegation
+            const needsCapture = NON_BUBBLING_EVENTS.has(baseEventName);
+            const useCapture = handlerOptions.capture !== undefined
+                ? handlerOptions.capture
+                : needsCapture;
+            const listenerOptions = {
+                capture: useCapture,
+                once: handlerOptions.once || false,
+                passive: handlerOptions.passive || false,
+            };
+            eventRoot.addEventListener(baseEventName, delegatedHandler, listenerOptions);
+            instance[CLEANUP].events.push({
+                target: eventRoot,
+                eventName: baseEventName,
+                handler: delegatedHandler,
+                options: listenerOptions,
+            });
+        }
+        else {
+            // Direct event handling - on the element itself
+            // If element has shadow root, listen on both shadow root AND host element
+            // to catch events from inside shadow DOM (with correct target) and on host itself
+            const shadowRoot = targetElement.shadowRoot;
+            const handledSymbol = Symbol('snice-event-handled');
+            const wrappedMethod = (event) => {
+                // Prevent double-triggering when listening on both shadow root and host
+                if (event[handledSymbol]) {
+                    return;
+                }
+                event[handledSymbol] = true;
+                try {
+                    // Apply automatic preventDefault/stopPropagation
+                    if (handlerOptions.preventDefault) {
+                        event.preventDefault();
+                    }
+                    if (handlerOptions.stopPropagation) {
+                        event.stopPropagation();
+                    }
+                    keyModifierMethod(event);
+                }
+                catch (error) {
+                    console.error(`Error in event handler ${handler.methodName}:`, error);
+                }
+            };
+            const listenerOptions = {
+                capture: handlerOptions.capture || false,
+                once: handlerOptions.once || false,
+                passive: handlerOptions.passive || false,
+            };
+            if (shadowRoot) {
+                // Listen on shadow root for events inside shadow DOM
+                shadowRoot.addEventListener(baseEventName, wrappedMethod, listenerOptions);
+                instance[CLEANUP].events.push({
+                    target: shadowRoot,
+                    eventName: baseEventName,
+                    handler: wrappedMethod,
+                    options: listenerOptions,
+                });
+            }
+            // Also listen on host element (for clicks on host itself or when no shadow root)
+            targetElement.addEventListener(baseEventName, wrappedMethod, listenerOptions);
+            instance[CLEANUP].events.push({
+                target: targetElement,
+                eventName: baseEventName,
+                handler: wrappedMethod,
+                options: listenerOptions,
+            });
+        }
+    }
+}
+/**
+ * Cleanup event listeners for a controller instance
+ * Called automatically by the controller system during detach
+ */
+function cleanupEventHandlers(instance) {
+    if (!instance[CLEANUP]?.events)
+        return;
+    for (const { target, eventName, handler, options } of instance[CLEANUP].events) {
+        target.removeEventListener(eventName, handler, options);
+    }
+    instance[CLEANUP].events = [];
+}
+
+// Controller-scoped cleanup registry
+class ControllerScope {
+    constructor() {
+        this.cleanupFns = new Map();
+        this.pendingOperations = new Set();
+    }
+    register(key, cleanup) {
+        this.cleanupFns.set(key, cleanup);
+    }
+    unregister(key) {
+        this.cleanupFns.delete(key);
+    }
+    async cleanup() {
+        // Wait for all pending operations
+        await Promise.all(this.pendingOperations);
+        // Run all cleanup functions
+        for (const cleanup of this.cleanupFns.values()) {
+            try {
+                await cleanup();
+            }
+            catch (error) {
+                console.error('Error during cleanup:', error);
+            }
+        }
+        this.cleanupFns.clear();
+    }
+    async runOperation(operation) {
+        const promise = operation();
+        const voidPromise = promise.then(() => { }, () => { });
+        this.pendingOperations.add(voidPromise);
+        try {
+            const result = await promise;
+            this.pendingOperations.delete(voidPromise);
+            return result;
+        }
+        catch (error) {
+            this.pendingOperations.delete(voidPromise);
+            throw error;
+        }
+    }
+}
+/**
+ * Decorator to register a controller class with a name
+ * @param name The name to register the controller under
+ */
+function controller(name) {
+    return function (constructor, _context) {
+        snice.controllerRegistry.set(name, constructor);
+        // Mark as controller class for channel decorator detection
+        constructor.prototype[IS_CONTROLLER_CLASS] = true;
+        return constructor;
+    };
+}
+/**
+ * Attaches a controller to an element
+ * @param element The element to attach the controller to
+ * @param controllerName The name of the controller to attach
+ */
+async function attachController(element, controllerName) {
+    const existingController = element[CONTROLLER_KEY];
+    const existingName = element[CONTROLLER_NAME_KEY];
+    // For native elements, check if this is actually the desired controller
+    const nativeController = element[NATIVE_CONTROLLER];
+    if (nativeController !== undefined && nativeController !== controllerName) {
+        // This attachment is outdated, skip it
         return;
     }
     if (existingName === controllerName && existingController) {
@@ -1077,12 +1995,12 @@ async function attachController(element, controllerName) {
     await scope.runOperation(async () => {
         await controllerInstance.attach(element);
     });
-    // Setup @on event handlers for controller
-    setupEventHandlers(controllerInstance, element);
     // Setup @observe observers for controller
     setupObservers(controllerInstance, element);
     // Setup @channel handlers for controller
     setupResponseHandlers(controllerInstance, element);
+    // Setup @on event handlers for controller
+    setupEventHandlers(controllerInstance, element);
     element.dispatchEvent(new CustomEvent('@snice/controller-attached', {
         detail: { name: controllerName, controller: controllerInstance }
     }));
@@ -1108,12 +2026,12 @@ async function detachController(element) {
         await controllerInstance.detach(element);
     }
     controllerInstance.element = null;
-    // Cleanup @on event handlers for controller
-    cleanupEventHandlers(controllerInstance);
     // Cleanup @observe observers for controller
     cleanupObservers(controllerInstance);
     // Cleanup @channel handlers for controller
     cleanupResponseHandlers(controllerInstance);
+    // Cleanup @on event handlers for controller
+    cleanupEventHandlers(controllerInstance);
     // Cleanup the controller scope
     if (scope) {
         await scope.cleanup();
@@ -1196,33 +2114,168 @@ function useNativeElementControllers() {
                 });
             }
         }
-    });
-    // Start observing when DOM is ready
-    if (document.readyState === 'loading') {
-        document.addEventListener('DOMContentLoaded', () => {
-            // Process existing elements (excluding custom elements)
-            document.querySelectorAll('[controller]:not([class*="-"])').forEach(processElement);
-            // Start observing
-            observer.observe(document.body, {
-                attributes: true,
-                attributeFilter: ['controller'],
-                childList: true,
-                subtree: true
-            });
-        });
+    });
+    // Start observing when DOM is ready
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', () => {
+            // Process existing elements (excluding custom elements)
+            document.querySelectorAll('[controller]:not([class*="-"])').forEach(processElement);
+            // Start observing
+            observer.observe(document.body, {
+                attributes: true,
+                attributeFilter: ['controller'],
+                childList: true,
+                subtree: true
+            });
+        });
+    }
+    else {
+        // DOM already loaded
+        document.querySelectorAll('[controller]:not([class*="-"])').forEach(processElement);
+        observer.observe(document.body, {
+            attributes: true,
+            attributeFilter: ['controller'],
+            childList: true,
+            subtree: true
+        });
+    }
+    // Store observer reference for cleanup if needed
+    globalThis.sniceNativeControllerObserver = observer;
+}
+
+/**
+ * @context decorator for receiving router context updates
+ */
+const CONTEXT_HANDLERS = getSymbol('context-handlers');
+/**
+ * @context decorator for receiving router context updates
+ *
+ * @example
+ * ```typescript
+ * @element('my-layout')
+ * class MyLayout extends HTMLElement {
+ *   @context
+ *   handleContext(ctx: Context) {
+ *     this.renderNav(ctx.placards, ctx.currentRoute);
+ *   }
+ *
+ *   @context({ debounce: 300 })
+ *   handleContextDebounced(ctx: Context) {
+ *     // Called after 300ms of no updates
+ *   }
+ * }
+ * ```
+ */
+function context$1(options = {}) {
+    return function (originalMethod, context) {
+        const methodName = context.name;
+        const initKey = `__context_init_${methodName}`;
+        context.addInitializer(function () {
+            const constructor = this.constructor;
+            if (constructor[initKey])
+                return;
+            constructor[initKey] = true;
+            if (!constructor[CONTEXT_HANDLERS]) {
+                constructor[CONTEXT_HANDLERS] = [];
+            }
+            constructor[CONTEXT_HANDLERS].push({
+                methodName,
+                method: originalMethod,
+                options,
+            });
+        });
+        return originalMethod;
+    };
+}
+/**
+ * Setup context handler for an element instance
+ * Called automatically during element connection
+ */
+function setupContextHandler(element) {
+    const handlers = element.constructor[CONTEXT_HANDLERS];
+    if (!handlers || !Array.isArray(handlers) || handlers.length === 0) {
+        return;
+    }
+    // Get the Context instance from the router
+    const ctx = element[CONTEXT_HANDLER];
+    if (!ctx) {
+        return;
+    }
+    // Store the Context instance for cleanup
+    element[NAVIGATION_CONTEXT_INSTANCE] = ctx;
+    // Register each handler with the Context
+    for (const handler of handlers) {
+        const { methodName, method, options } = handler;
+        const wrappedMethodName = `__wrapped_${methodName}`;
+        // Create wrapped method with timing controls
+        element[wrappedMethodName] = function (context) {
+            // Skip if already called once
+            if (options.once && element[CONTEXT_CALLED]) {
+                return;
+            }
+            const callMethod = () => {
+                method.call(element, context);
+                // Handle once option
+                if (options.once) {
+                    element[CONTEXT_CALLED] = true;
+                    // Unregister after first call
+                    const ctx = element[NAVIGATION_CONTEXT_INSTANCE];
+                    if (ctx && typeof ctx[CONTEXT_UNREGISTER] === 'function') {
+                        ctx[CONTEXT_UNREGISTER](element);
+                    }
+                }
+            };
+            // Handle debounce
+            if (options.debounce) {
+                clearTimeout(element[CONTEXT_TIMER]);
+                element[CONTEXT_TIMER] = setTimeout(callMethod, options.debounce);
+            }
+            // Handle throttle
+            else if (options.throttle) {
+                const now = Date.now();
+                const lastCall = element[CONTEXT_TIMER] || 0;
+                if (now - lastCall >= options.throttle) {
+                    element[CONTEXT_TIMER] = now;
+                    callMethod();
+                }
+            }
+            // No timing options - call immediately
+            else {
+                callMethod();
+            }
+        };
+        // Register with the Context using the wrapped method name
+        if (typeof ctx[CONTEXT_REGISTER] === 'function') {
+            ctx[CONTEXT_REGISTER](element, wrappedMethodName);
+        }
+    }
+}
+/**
+ * Cleanup context handler for an element instance
+ * Called automatically during element disconnection
+ */
+function cleanupContextHandler(element) {
+    const handlers = element.constructor[CONTEXT_HANDLERS];
+    if (!handlers || !Array.isArray(handlers) || handlers.length === 0) {
+        return;
+    }
+    // Clear any pending debounce timer
+    for (const handler of handlers) {
+        if (handler.options.debounce && element[CONTEXT_TIMER]) {
+            clearTimeout(element[CONTEXT_TIMER]);
+            delete element[CONTEXT_TIMER];
+        }
+        // Clean up wrapped method
+        const wrappedMethodName = `__wrapped_${handler.methodName}`;
+        delete element[wrappedMethodName];
     }
-    else {
-        // DOM already loaded
-        document.querySelectorAll('[controller]:not([class*="-"])').forEach(processElement);
-        observer.observe(document.body, {
-            attributes: true,
-            attributeFilter: ['controller'],
-            childList: true,
-            subtree: true
-        });
+    // Unregister from Context if available
+    const ctx = element[NAVIGATION_CONTEXT_INSTANCE];
+    if (ctx && typeof ctx[CONTEXT_UNREGISTER] === 'function') {
+        ctx[CONTEXT_UNREGISTER](element);
     }
-    // Store observer reference for cleanup if needed
-    globalThis.sniceNativeControllerObserver = observer;
+    delete element[NAVIGATION_CONTEXT_INSTANCE];
+    delete element[CONTEXT_CALLED];
 }
 
 /**
@@ -1283,6 +2336,87 @@ class SimpleArray {
     }
 }
 
+var _a, _b, _c;
+// Symbol for storing the Set of elements
+const REGISTERED_ELEMENTS_SET = Symbol('registered-elements-set');
+// Counter for generating unique context IDs
+let contextIdCounter = 0;
+/**
+ * Represents the bundled router state that can notify registered elements of changes
+ */
+class Context {
+    constructor(context = {}, placards = [], currentRoute = '', routeParams = {}) {
+        this[_a] = new WeakMap();
+        this[_b] = new Set();
+        this[_c] = false;
+        this.id = contextIdCounter++;
+        this.application = context;
+        this.navigation = {
+            placards,
+            route: currentRoute,
+            params: routeParams
+        };
+    }
+    /**
+     * Register an element to receive context updates
+     * @internal Used by @context decorator
+     */
+    [(_a = REGISTERED_ELEMENTS, _b = REGISTERED_ELEMENTS_SET, _c = IS_UPDATING, CONTEXT_REGISTER)](element, methodName) {
+        this[REGISTERED_ELEMENTS].set(element, methodName);
+        this[REGISTERED_ELEMENTS_SET].add(element);
+    }
+    /**
+     * Unregister an element from receiving context updates
+     * @internal Used by @context decorator cleanup
+     */
+    [CONTEXT_UNREGISTER](element) {
+        this[REGISTERED_ELEMENTS].delete(element);
+        this[REGISTERED_ELEMENTS_SET].delete(element);
+    }
+    /**
+     * Update the context and notify all registered elements
+     * Prevents infinite loops by tracking update state
+     */
+    update(context, placards, currentRoute, routeParams) {
+        // Prevent infinite loops
+        if (this[IS_UPDATING]) {
+            return;
+        }
+        this[IS_UPDATING] = true;
+        // Update properties (id remains immutable)
+        this.application = context;
+        this.navigation.placards = placards;
+        this.navigation.route = currentRoute;
+        this.navigation.params = routeParams;
+        // Notify all registered elements by calling their methods directly
+        const elementsSet = this[REGISTERED_ELEMENTS_SET];
+        const elementsMap = this[REGISTERED_ELEMENTS];
+        for (const element of elementsSet) {
+            const methodName = elementsMap.get(element);
+            if (methodName && typeof element[methodName] === 'function') {
+                try {
+                    element[methodName](this);
+                }
+                catch (error) {
+                    // Log error but continue notifying other elements
+                    console.error(`Error calling @context method ${methodName}:`, error);
+                }
+            }
+        }
+        this[IS_UPDATING] = false;
+    }
+    /**
+     * Notify a specific element of the current context state
+     * @internal Used by @context decorator
+     */
+    [CONTEXT_NOTIFY_ELEMENT](element) {
+        const methodName = this[REGISTERED_ELEMENTS].get(element);
+        if (methodName && typeof element[methodName] === 'function') {
+            element[methodName](this);
+        }
+    }
+}
+
 /**
  * Detects the type constructor from an initial value
  * @param initialValue - The default value assigned to a property field (e.g., `name = "default"` -> "default")
@@ -1411,6 +2545,297 @@ function valueToAttribute(value, propertyOptions, initialValue) {
     }
 }
 
+/**
+ * @render and @styles decorators for Snice v3.0.0
+ * Provides automatic differential rendering on property changes
+ */
+/**
+ * Global render scheduler for microtask batching
+ * Batches multiple property changes into a single render
+ */
+class RenderScheduler {
+    constructor() {
+        this.pending = new Set();
+        this.scheduled = false;
+    }
+    /**
+     * Schedule an element for rendering
+     * Batches renders in a microtask unless sync option is enabled
+     */
+    schedule(element, options) {
+        // Sync rendering - execute immediately
+        if (options.sync) {
+            performRender(element, options);
+            return;
+        }
+        // Async rendering - batch in microtask
+        this.pending.add(element);
+        if (!this.scheduled) {
+            this.scheduled = true;
+            queueMicrotask(() => this.flush());
+        }
+    }
+    /**
+     * Flush all pending renders
+     */
+    flush() {
+        const elements = Array.from(this.pending);
+        this.pending.clear();
+        this.scheduled = false;
+        for (const element of elements) {
+            const options = element[RENDER_OPTIONS] || {};
+            performRender(element, options);
+        }
+    }
+}
+const renderScheduler = new RenderScheduler();
+/**
+ * Perform the actual render of an element
+ */
+function performRender(element, options, precomputedResult) {
+    const renderMethod = element[RENDER_METHOD];
+    if (!renderMethod)
+        return;
+    // If once is true and we've already rendered, skip
+    if (options.once && element[RENDER_INSTANCE]) {
+        return;
+    }
+    try {
+        // Use precomputed result if provided, otherwise call the render method
+        const result = precomputedResult !== undefined ? precomputedResult : renderMethod.call(element);
+        // Check if differential rendering is disabled (expects string)
+        const differential = options.differential !== false;
+        if (!differential) {
+            // Non-differential expects string
+            if (typeof result !== 'string') {
+                console.warn('Render method with differential: false must return a string');
+                return;
+            }
+            // Simple string rendering
+            if (!element.shadowRoot) {
+                element.attachShadow({ mode: 'open' });
+            }
+            element.shadowRoot.innerHTML = result;
+            // Mark scheduled flag as false
+            element[RENDER_SCHEDULED] = false;
+            // Call all registered render callbacks
+            const callbacks = element[RENDER_CALLBACKS];
+            if (callbacks && callbacks.length > 0) {
+                const cbs = [...callbacks];
+                element[RENDER_CALLBACKS] = [];
+                cbs.forEach(cb => cb());
+            }
+            return;
+        }
+        if (!isTemplateResult(result)) {
+            console.warn('Render method must return html`` template result');
+            return;
+        }
+        // Get or create template instance (differential rendering)
+        let instance = element[RENDER_INSTANCE];
+        if (!instance) {
+            // First render - create shadow root if needed and initial instance
+            if (!element.shadowRoot) {
+                element.attachShadow({ mode: 'open' });
+            }
+            instance = new TemplateInstance(result);
+            element[RENDER_INSTANCE] = instance;
+            // Create the fragment but don't commit values yet
+            const fragment = instance.renderFragment();
+            // Append to shadow root first so getRootNode() works in event handlers
+            element.shadowRoot.appendChild(fragment);
+            // Now commit values (this binds event handlers with correct host)
+            instance.update(result.values);
+        }
+        else {
+            // Subsequent render - just update the parts (differential rendering!)
+            instance.update(result.values);
+        }
+        // Mark scheduled flag as false
+        element[RENDER_SCHEDULED] = false;
+        // Call all registered render callbacks (for testing/debugging)
+        const callbacks = element[RENDER_CALLBACKS];
+        if (callbacks && callbacks.length > 0) {
+            const cbs = [...callbacks];
+            element[RENDER_CALLBACKS] = [];
+            cbs.forEach(cb => cb());
+        }
+    }
+    catch (error) {
+        console.error('Error rendering element:', error);
+    }
+}
+/**
+ * Request a render for an element
+ * Respects debounce/throttle/once/sync options
+ * @param immediate - Force immediate render (used for initial render)
+ */
+function requestRender(element, immediate = false) {
+    const options = element[RENDER_OPTIONS] || {};
+    // Handle once option
+    if (options.once && element[RENDER_INSTANCE]) {
+        return;
+    }
+    // Force immediate render (for initial render)
+    if (immediate) {
+        performRender(element, options);
+        return;
+    }
+    // Handle debounce
+    if (options.debounce !== undefined && options.debounce > 0) {
+        if (!element[RENDER_TIMERS]) {
+            element[RENDER_TIMERS] = {};
+        }
+        clearTimeout(element[RENDER_TIMERS].debounce);
+        element[RENDER_TIMERS].debounce = setTimeout(() => {
+            renderScheduler.schedule(element, options);
+        }, options.debounce);
+        return;
+    }
+    // Handle throttle
+    if (options.throttle !== undefined && options.throttle > 0) {
+        if (!element[RENDER_TIMERS]) {
+            element[RENDER_TIMERS] = { lastThrottle: 0 };
+        }
+        const timers = element[RENDER_TIMERS];
+        const now = Date.now();
+        if (timers.lastThrottle === 0 || now - timers.lastThrottle >= options.throttle) {
+            timers.lastThrottle = now;
+            renderScheduler.schedule(element, options);
+        }
+        else {
+            // Schedule for later if not already scheduled
+            if (!timers.throttleTimer) {
+                const remaining = options.throttle - (now - timers.lastThrottle);
+                timers.throttleTimer = setTimeout(() => {
+                    timers.throttleTimer = null;
+                    timers.lastThrottle = Date.now();
+                    renderScheduler.schedule(element, options);
+                }, remaining);
+            }
+        }
+        return;
+    }
+    // Normal rendering (with microtask batching unless sync)
+    renderScheduler.schedule(element, options);
+}
+/**
+ * @render decorator for component rendering
+ *
+ * Marks a method as the render method for the component.
+ * The method should return html`...` template.
+ * Automatically re-renders when properties change (unless once: true).
+ *
+ * @example
+ * ```typescript
+ * @render()
+ * renderContent() {
+ *   return html`<div>${this.count}</div>`;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Debounced rendering
+ * @render({ debounce: 100 })
+ * renderContent() {
+ *   return html`<div>${this.searchTerm}</div>`;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Render only once (manual re-renders only)
+ * @render({ once: true })
+ * renderContent() {
+ *   return html`<div>Static content</div>`;
+ * }
+ * ```
+ */
+function render(options = {}) {
+    return function (originalMethod, context) {
+        context.name;
+        context.addInitializer(function () {
+            // Store the render method and options
+            this[RENDER_METHOD] = originalMethod;
+            this[RENDER_OPTIONS] = options;
+        });
+        // Return wrapped method that triggers re-render when called manually
+        return function (...args) {
+            // Call original method to get the template
+            const result = originalMethod.apply(this, args);
+            // Always render when method is called manually (even if once: true)
+            // Force immediate render to bypass all options, pass precomputed result to avoid calling method twice
+            performRender(this, {}, result);
+            return result;
+        };
+    };
+}
+/**
+ * @styles decorator for component styles
+ *
+ * Marks a method as the styles method for the component.
+ * The method should return css`...` template.
+ * Styles are applied once when the component is connected.
+ *
+ * @example
+ * ```typescript
+ * @styles()
+ * styles() {
+ *   return css`:host { display: block; }`;
+ * }
+ * ```
+ */
+function styles() {
+    return function (originalMethod, context) {
+        context.addInitializer(function () {
+            // Store the styles method
+            this[STYLES_METHOD] = originalMethod;
+        });
+        return originalMethod;
+    };
+}
+/**
+ * Apply styles to an element
+ * Called during element initialization
+ */
+function applyStyles(element) {
+    const stylesMethod = element[STYLES_METHOD];
+    if (!stylesMethod)
+        return;
+    // Only apply once
+    if (element[STYLES_APPLIED])
+        return;
+    element[STYLES_APPLIED] = true;
+    try {
+        const result = stylesMethod.call(element);
+        if (!isCSSResult(result)) {
+            console.warn('Styles method must return css`` template result');
+            return;
+        }
+        // Ensure shadow root exists
+        if (!element.shadowRoot) {
+            element.attachShadow({ mode: 'open' });
+        }
+        // Create base styles for meta elements (if, case)
+        const baseStyleSheet = new CSSStyleSheet();
+        baseStyleSheet.replaceSync('if, case { display: contents; }');
+        // Try to use constructable stylesheets for better performance
+        if (element.shadowRoot && result.styleSheet && 'adoptedStyleSheets' in element.shadowRoot) {
+            element.shadowRoot.adoptedStyleSheets = [baseStyleSheet, result.styleSheet];
+        }
+        else if (element.shadowRoot) {
+            // Fallback to <style> tag
+            const style = document.createElement('style');
+            style.textContent = 'if, case { display: contents; }\n' + result.cssText;
+            element.shadowRoot.appendChild(style);
+        }
+    }
+    catch (error) {
+        console.error('Error applying styles:', error);
+    }
+}
+
 /**
  * Applies core element functionality to a constructor
  * This is shared between @element and @page decorators
@@ -1455,6 +2880,9 @@ function applyElementFunctionality(constructor) {
         enumerable: true,
         configurable: true
     });
+    // Note: rendered promise is stored via symbols RENDERED_PROMISE and RENDERED_RESOLVE
+    // It's not exposed as a public property - only accessible via test utilities
+    // This prevents accidental misuse in production code
     // Add controller property
     Object.defineProperty(constructor.prototype, 'controller', {
         get() {
@@ -1492,6 +2920,7 @@ function applyElementFunctionality(constructor) {
             // Re-establish handlers that get cleaned up on disconnect
             setupEventHandlers(this, this);
             setupResponseHandlers(this, this);
+            setupContextHandler(this);
             // Re-establish observers that get cleaned up on disconnect
             try {
                 setupObservers(this, this);
@@ -1506,6 +2935,9 @@ function applyElementFunctionality(constructor) {
             return;
         }
         try {
+            // Mark that properties are being initialized from attributes
+            // This allows property setters to work during initialization
+            this[PROPERTIES_INITIALIZED] = true;
             // Initialize properties from attributes before rendering
             const properties = constructor[PROPERTIES];
             if (properties) {
@@ -1524,82 +2956,69 @@ function applyElementFunctionality(constructor) {
                     }
                 }
             }
-            // Mark that properties have been initialized
-            this[PROPERTIES_INITIALIZED] = true;
+            // Apply any properties that were set before element was connected
+            // BUT only if they don't have an HTML attribute (don't override HTML attributes)
+            if (this[PRE_INIT_PROPERTY_VALUES]) {
+                for (const [propName, propValue] of this[PRE_INIT_PROPERTY_VALUES]) {
+                    // Remove from map first so getter doesn't return it during setter call
+                    this[PRE_INIT_PROPERTY_VALUES].delete(propName);
+                    // Only apply pre-init value if NO HTML attribute exists
+                    // This prevents field initializers from overwriting HTML attributes
+                    const propOptions = properties?.get(propName);
+                    const attributeName = typeof propOptions?.attribute === 'string' ? propOptions.attribute : propName.toLowerCase();
+                    if (!this.hasAttribute(attributeName)) {
+                        this[propName] = propValue;
+                    }
+                }
+                // Clear the pre-init values map
+                delete this[PRE_INIT_PROPERTY_VALUES];
+            }
             // Properties are now stateless and read from DOM attributes only
             // Initial values are not automatically reflected
-            // Create shadow root if it doesn't exist
-            if (!this.shadowRoot) {
-                this.attachShadow({ mode: 'open' });
-            }
-            // Build the shadow DOM content
-            let shadowContent = '';
-            // Add HTML first (maintaining original order)
-            if (this.html) {
-                try {
-                    const htmlResult = this.html();
-                    // Handle both async and sync html
-                    const htmlContent = htmlResult instanceof Promise ? await htmlResult : htmlResult;
-                    if (htmlContent !== undefined) {
-                        shadowContent += htmlContent;
+            // v3.0.0: Apply @styles decorator if present
+            // This creates the shadow root and applies styles
+            applyStyles(this);
+            // v3.0.0: Perform initial @render if present
+            // This uses differential rendering with template system
+            // Defer initial render to next microtask to allow property bindings
+            // from parent to be set first (avoids infinite loops in nested elements)
+            if (this[RENDER_METHOD]) {
+                queueMicrotask(() => {
+                    requestRender(this, true);
+                    // Setup observers after first render completes so shadow DOM content exists
+                    try {
+                        setupObservers(this, this);
                     }
-                }
-                catch (error) {
-                    console.error(`Error in html() method for ${this.tagName}:`, error);
-                }
+                    catch (error) {
+                        console.error(`Error setting up observers for ${this.tagName}:`, error);
+                    }
+                    // Mark element as ready after initial render completes
+                    if (this[READY_RESOLVE]) {
+                        this[READY_RESOLVE]();
+                        this[READY_RESOLVE] = null;
+                    }
+                });
             }
-            // Add CSS after HTML (maintaining original order)
-            if (this.css) {
+            else {
+                // No render method, setup observers immediately
                 try {
-                    const cssResult = this.css();
-                    // Handle both async and sync css
-                    const cssResolved = cssResult instanceof Promise ? await cssResult : cssResult;
-                    if (cssResolved) {
-                        // Handle both string and array of strings
-                        const cssContent = Array.isArray(cssResolved) ? cssResolved.join('\n') : cssResolved;
-                        // No need for scoping with Shadow DOM, but add data attribute for compatibility
-                        shadowContent += `<style data-component-css>${cssContent}</style>`;
-                    }
+                    setupObservers(this, this);
                 }
                 catch (error) {
-                    console.error(`Error in css() method for ${this.tagName}:`, error);
+                    console.error(`Error setting up observers for ${this.tagName}:`, error);
                 }
-            }
-            // Set shadow DOM content
-            if (shadowContent) {
-                this.shadowRoot.innerHTML = shadowContent;
-            }
-            // Render all @part methods into their corresponding elements
-            const parts = constructor[PARTS];
-            if (parts && this.shadowRoot) {
-                for (const [partName, partHandler] of parts) {
-                    try {
-                        const partElement = this.shadowRoot.querySelector(`[part="${partName}"]`);
-                        if (partElement) {
-                            // For initial render, call original method directly to avoid timing restrictions
-                            const partResult = partHandler.method.call(this);
-                            const partContent = partResult instanceof Promise ? await partResult : partResult;
-                            if (partContent !== undefined) {
-                                partElement.innerHTML = partContent;
-                            }
-                        }
-                    }
-                    catch (error) {
-                        console.error(`Error rendering @part('${partName}') in ${this.tagName}:`, error);
-                    }
+                // Mark element as ready immediately if no render method
+                if (this[READY_RESOLVE]) {
+                    this[READY_RESOLVE]();
+                    this[READY_RESOLVE] = null;
                 }
             }
-            // Setup @on event handlers - use element for host events, shadow root for delegated events
+            // Setup @on event handlers (v2.5.4 compatibility restored!)
             setupEventHandlers(this, this);
             // Setup @respond handlers for elements
             setupResponseHandlers(this, this);
-            // Setup @observe observers
-            try {
-                setupObservers(this, this);
-            }
-            catch (error) {
-                console.error(`Error setting up observers for ${this.tagName}:`, error);
-            }
+            // Setup @context handler for elements
+            setupContextHandler(this);
             // Mark as initialized
             this[INITIALIZED] = true;
             // NOW call the original user-defined connectedCallback after shadow DOM is set up
@@ -1608,11 +3027,8 @@ function applyElementFunctionality(constructor) {
             }
         }
         finally {
-            // Always mark element as ready, even if there were errors
-            if (this[READY_RESOLVE]) {
-                this[READY_RESOLVE]();
-                this[READY_RESOLVE] = null; // Clear the resolver
-            }
+            // Ready is now resolved inside the render microtask (or immediately if no render)
+            // This ensures ready waits for initial render to complete
         }
         // Call @ready handlers after everything is set up and ready promise is resolved
         const readyHandlers = constructor[READY_HANDLERS];
@@ -1649,10 +3065,12 @@ function applyElementFunctionality(constructor) {
                 console.error(`Failed to detach controller:`, error);
             });
         }
-        // Cleanup @on event handlers
+        // Cleanup @on event handlers (v2.5.4 compatibility restored!)
         cleanupEventHandlers(this);
         // Cleanup @respond handlers
         cleanupResponseHandlers(this);
+        // Cleanup @context handler
+        cleanupContextHandler(this);
         // Cleanup @observe observers
         cleanupObservers(this);
     };
@@ -1715,6 +3133,10 @@ function applyElementFunctionality(constructor) {
                                         }
                                     }
                                 }
+                                // Trigger auto-render on attribute change (same as property setter)
+                                if (this[RENDER_METHOD] && this[INITIALIZED]) {
+                                    requestRender(this);
+                                }
                             }
                         }
                         break;
@@ -1754,7 +3176,7 @@ function applyElementFunctionality(constructor) {
         }
     };
 }
-function element(tagName) {
+function element(tagName, options) {
     return function (constructor, context) {
         // Transfer metadata from context to constructor
         if (context.metadata && context.metadata[PROPERTIES]) {
@@ -1765,6 +3187,11 @@ function element(tagName) {
                 constructor[PROPERTIES].set(key, value);
             }
         }
+        // Set up form association if requested via options
+        // MUST be done BEFORE applyElementFunctionality and customElements.define
+        if (options?.formAssociated === true) {
+            constructor.formAssociated = true;
+        }
         applyElementFunctionality(constructor);
         customElements.define(tagName, constructor);
         return constructor;
@@ -1820,29 +3247,43 @@ function property(options) {
                         if (attrValue !== null) {
                             return parseAttributeValue(attrValue, finalOptions || {}, undefined, initialValue);
                         }
-                        // For Boolean properties that have been explicitly set via attribute,
+                        // For Boolean properties that have been explicitly set via attribute (and then removed),
                         // follow HTML boolean attribute semantics (absence = false)
                         const inferredType = finalOptions?.type || detectType(initialValue);
                         if (inferredType === Boolean && this[EXPLICITLY_SET_PROPERTIES]?.has(propertyKey)) {
                             return false;
                         }
-                        // Otherwise return initial value
+                        // Check for pre-init property values (set before element was connected)
+                        if (this[PRE_INIT_PROPERTY_VALUES]?.has(propertyKey)) {
+                            return this[PRE_INIT_PROPERTY_VALUES].get(propertyKey);
+                        }
+                        // Otherwise return initial value (respects default values like showRememberMe = true)
                         return initialValue;
                     },
                     set(newValue) {
-                        // Get old value from stored state for change detection
-                        if (!this[PROPERTY_VALUES]) {
-                            this[PROPERTY_VALUES] = {};
-                        }
-                        const oldValue = this[PROPERTY_VALUES][propertyKey];
+                        // Get old value by calling the getter (which reads from attribute)
+                        const oldValue = this[propertyKey];
                         // Check if value actually changed
                         if (oldValue === newValue)
                             return;
-                        // Update stored value
-                        this[PROPERTY_VALUES][propertyKey] = newValue;
-                        // Always reflect to DOM - properties are always backed by attributes
+                        // Don't reflect to DOM until connectedCallback has started
+                        // This prevents field initializers from overwriting HTML attributes
+                        if (!this[PROPERTIES_INITIALIZED]) {
+                            // Store value for later application when element is connected
+                            if (!this[PRE_INIT_PROPERTY_VALUES]) {
+                                this[PRE_INIT_PROPERTY_VALUES] = new Map();
+                            }
+                            this[PRE_INIT_PROPERTY_VALUES].set(propertyKey, newValue);
+                            return;
+                        }
+                        // Reflect to DOM - properties are backed by attributes
                         const attributeName = typeof finalOptions.attribute === 'string' ? finalOptions.attribute : propertyKey.toLowerCase();
                         const attributeValue = valueToAttribute(newValue, finalOptions, initialValue);
+                        // Mark as explicitly set for boolean handling
+                        if (!this[EXPLICITLY_SET_PROPERTIES]) {
+                            this[EXPLICITLY_SET_PROPERTIES] = new Set();
+                        }
+                        this[EXPLICITLY_SET_PROPERTIES].add(propertyKey);
                         // Flag to prevent attributeChangedCallback from triggering watchers for this change
                         if (!this._settingFromProperty)
                             this._settingFromProperty = new Set();
@@ -1884,8 +3325,12 @@ function property(options) {
                                 }
                             }
                         }
-                        if (this.requestUpdate) {
-                            this.requestUpdate(propertyKey, oldValue);
+                        // v3.0.0: Trigger auto-render on property change
+                        // This respects @render options (debounce, throttle, once, sync)
+                        // Only trigger renders after element is fully initialized to avoid
+                        // infinite loops during initial setup
+                        if (this[RENDER_METHOD] && this[INITIALIZED]) {
+                            requestRender(this);
                         }
                     },
                     configurable: true,
@@ -1980,12 +3425,15 @@ function queryAll(selector, options = {}) {
 function watch(...propertyNames) {
     return function (target, context) {
         const methodName = context.name;
+        const initKey = `__watch_init_${methodName}`;
         context.addInitializer(function () {
             const constructor = this.constructor;
+            if (constructor[initKey])
+                return;
+            constructor[initKey] = true;
             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, []);
@@ -2064,8 +3512,12 @@ function context() {
 function ready() {
     return function (target, context) {
         const methodName = context.name;
+        const initKey = `__ready_init_${methodName}`;
         context.addInitializer(function () {
             const constructor = this.constructor;
+            if (constructor[initKey])
+                return;
+            constructor[initKey] = true;
             if (!constructor[READY_HANDLERS]) {
                 constructor[READY_HANDLERS] = [];
             }
@@ -2083,8 +3535,12 @@ function ready() {
 function dispose() {
     return function (target, context) {
         const methodName = context.name;
+        const initKey = `__dispose_init_${methodName}`;
         context.addInitializer(function () {
             const constructor = this.constructor;
+            if (constructor[initKey])
+                return;
+            constructor[initKey] = true;
             if (!constructor[DISPOSE_HANDLERS]) {
                 constructor[DISPOSE_HANDLERS] = [];
             }
@@ -2102,8 +3558,12 @@ function dispose() {
 function moved(options = {}) {
     return function (originalMethod, context) {
         const methodName = context.name;
+        const initKey = `__moved_init_${methodName}`;
         context.addInitializer(function () {
             const constructor = this.constructor;
+            if (constructor[initKey])
+                return;
+            constructor[initKey] = true;
             if (!constructor[MOVED_HANDLERS]) {
                 constructor[MOVED_HANDLERS] = [];
             }
@@ -2188,102 +3648,20 @@ function adopted(options = {}) {
         return function (...args) {
             // Initialize timers storage if not present
             if (!this[ADOPTED_TIMERS]) {
-                this[ADOPTED_TIMERS] = new Map();
-            }
-            // Get or create timers for this specific method
-            if (!this[ADOPTED_TIMERS].has(methodName)) {
-                this[ADOPTED_TIMERS].set(methodName, {
-                    throttleTimer: null,
-                    debounceTimer: null,
-                    lastThrottleCall: 0
-                });
-            }
-            const timers = this[ADOPTED_TIMERS].get(methodName);
-            // Helper function to execute method
-            const executeMethod = (...methodArgs) => {
-                return originalMethod.apply(this, methodArgs);
-            };
-            const hasDebounce = options.debounce !== undefined && options.debounce > 0;
-            const hasThrottle = options.throttle !== undefined && options.throttle > 0;
-            // Handle timing based on priority: debounce > throttle > immediate
-            switch (true) {
-                case hasDebounce: {
-                    clearTimeout(timers.debounceTimer);
-                    timers.debounceTimer = setTimeout(() => executeMethod(...args), options.debounce);
-                    return undefined;
-                }
-                case hasThrottle: {
-                    const throttleMs = options.throttle;
-                    const now = Date.now();
-                    const canExecuteImmediately = timers.lastThrottleCall === 0 || now - timers.lastThrottleCall >= throttleMs;
-                    if (canExecuteImmediately) {
-                        timers.lastThrottleCall = now;
-                        return executeMethod(...args);
-                    }
-                    const hasScheduledTimer = !!timers.throttleTimer;
-                    if (!hasScheduledTimer) {
-                        const remainingTime = throttleMs - (now - timers.lastThrottleCall);
-                        timers.throttleTimer = setTimeout(() => {
-                            timers.throttleTimer = null;
-                            timers.lastThrottleCall = Date.now();
-                            executeMethod(...args);
-                        }, remainingTime);
-                    }
-                    return undefined;
-                }
-                default:
-                    return executeMethod(...args);
-            }
-        };
-    };
-}
-/**
- * Decorator for methods that render specific parts of the template
- * Parts are identified by the 'part' attribute in the HTML template
- * When the decorated method is called, it automatically re-renders its part
- */
-function part(partName, options = {}) {
-    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
-            });
-        });
-        // 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();
+                this[ADOPTED_TIMERS] = new Map();
             }
-            // Get or create timers for this specific part
-            if (!this[PART_TIMERS].has(partName)) {
-                this[PART_TIMERS].set(partName, {
+            // Get or create timers for this specific method
+            if (!this[ADOPTED_TIMERS].has(methodName)) {
+                this[ADOPTED_TIMERS].set(methodName, {
                     throttleTimer: null,
                     debounceTimer: null,
                     lastThrottleCall: 0
                 });
             }
-            const timers = this[PART_TIMERS].get(partName);
-            // Helper function to execute method and update DOM
-            const executeAndUpdate = (...methodArgs) => {
-                const result = originalMethod.apply(this, methodArgs);
-                const updateDOM = (content) => {
-                    const hasContent = content !== undefined;
-                    const hasElement = this.shadowRoot?.querySelector(`[part="${partName}"]`);
-                    if (hasContent && hasElement) {
-                        hasElement.innerHTML = content;
-                    }
-                };
-                const isPromise = result instanceof Promise;
-                return isPromise
-                    ? result.then(content => { updateDOM(content); return content; })
-                    : (updateDOM(result), result);
+            const timers = this[ADOPTED_TIMERS].get(methodName);
+            // Helper function to execute method
+            const executeMethod = (...methodArgs) => {
+                return originalMethod.apply(this, methodArgs);
             };
             const hasDebounce = options.debounce !== undefined && options.debounce > 0;
             const hasThrottle = options.throttle !== undefined && options.throttle > 0;
@@ -2291,7 +3669,7 @@ function part(partName, options = {}) {
             switch (true) {
                 case hasDebounce: {
                     clearTimeout(timers.debounceTimer);
-                    timers.debounceTimer = setTimeout(() => executeAndUpdate(...args), options.debounce);
+                    timers.debounceTimer = setTimeout(() => executeMethod(...args), options.debounce);
                     return undefined;
                 }
                 case hasThrottle: {
@@ -2300,7 +3678,7 @@ function part(partName, options = {}) {
                     const canExecuteImmediately = timers.lastThrottleCall === 0 || now - timers.lastThrottleCall >= throttleMs;
                     if (canExecuteImmediately) {
                         timers.lastThrottleCall = now;
-                        return executeAndUpdate(...args);
+                        return executeMethod(...args);
                     }
                     const hasScheduledTimer = !!timers.throttleTimer;
                     if (!hasScheduledTimer) {
@@ -2308,17 +3686,19 @@ function part(partName, options = {}) {
                         timers.throttleTimer = setTimeout(() => {
                             timers.throttleTimer = null;
                             timers.lastThrottleCall = Date.now();
-                            executeAndUpdate(...args);
+                            executeMethod(...args);
                         }, remainingTime);
                     }
                     return undefined;
                 }
                 default:
-                    return executeAndUpdate(...args);
+                    return executeMethod(...args);
             }
         };
     };
 }
+// @part decorator removed in v3.0.0
+// Use @render with differential rendering instead
 
 /*!
  * pica-route v1.1.2
@@ -3069,6 +4449,8 @@ function Router(options) {
     let currentLayoutName = null; // Track current layout name
     let currentLayoutTimestamp = null; // Track current layout timestamp
     const context = options.context || {}; // Store context for guards
+    // Create Context instance for managing router state
+    const navigationContext = new Context(context, [], '', {});
     function getCurrentLayoutElement(target) {
         const noCurrentLayout = !currentLayoutName || !currentLayoutTimestamp;
         if (noCurrentLayout) {
@@ -3106,33 +4488,19 @@ function Router(options) {
             // Extend the connectedCallback to add router-specific functionality
             const elementConnectedCallback = constructor.prototype.connectedCallback;
             constructor.prototype.connectedCallback = function () {
+                // Store the Context instance for @context decorated methods to access
+                this[CONTEXT_HANDLER] = navigationContext;
                 // Call the element's connectedCallback first
                 elementConnectedCallback?.call(this);
-                // Setup context request handler for nested elements
-                const contextRequestHandler = (event) => {
-                    // Only respond if this element has context
-                    if (this[ROUTER_CONTEXT] !== undefined) {
-                        event.detail.context = this[ROUTER_CONTEXT];
-                        event.stopPropagation(); // Stop bubbling once context is provided
-                    }
-                };
-                this.addEventListener('@context/request', contextRequestHandler);
-                // Store handler for cleanup
-                this[CONTEXT_REQUEST_HANDLER] = contextRequestHandler;
             };
             // Extend the disconnectedCallback to clean up router-specific stuff
             const elementDisconnectedCallback = constructor.prototype.disconnectedCallback;
             constructor.prototype.disconnectedCallback = function () {
                 // Call element's disconnectedCallback first
                 elementDisconnectedCallback?.call(this);
-                // Clean up context request handler
-                const handler = this[CONTEXT_REQUEST_HANDLER];
-                if (handler) {
-                    this.removeEventListener('@context/request', handler);
-                    delete this[CONTEXT_REQUEST_HANDLER];
-                }
-                // Clean up context reference
+                // Clean up context references
                 delete this[ROUTER_CONTEXT];
+                delete this[CONTEXT_HANDLER];
             };
             // Define the custom element
             customElements.define(pageOptions.tag, constructor);
@@ -3191,8 +4559,8 @@ function Router(options) {
      * initialize();
      */
     function initialize() {
-        const targetExists = !!document.querySelector(options.target);
-        if (!targetExists) {
+        const target = document.querySelector(options.target);
+        if (!target) {
             throw new Error(`Target element not found: ${options.target}`);
         }
         const needsSorting = !is_sorted;
@@ -3216,6 +4584,10 @@ function Router(options) {
                 : placard;
         });
     }
+    function emitContextUpdate(target, currentPath, routeParams) {
+        // Update the navigation context and notify all registered elements
+        navigationContext.update(context, placards, currentPath, routeParams);
+    }
     function updateLayout(layoutElement, currentPath, routeParams) {
         // Check if layout implements the update method
         if (typeof layoutElement.update === 'function') {
@@ -3298,6 +4670,7 @@ function Router(options) {
             }
             const newPageElement = document.createElement(route.tag);
             newPageElement[ROUTER_CONTEXT] = context;
+            newPageElement[CONTEXT_HANDLER] = navigationContext;
             const routeParams = params;
             Object.keys(routeParams).forEach(key => newPageElement.setAttribute(key, routeParams[key]));
             return { result: RouteResult.SUCCESS, element: newPageElement, transition: route.transition, layout: route.layout, routeParams };
@@ -3388,7 +4761,7 @@ function Router(options) {
         // Collect fresh placards before navigation
         collectPlacards();
         window.scrollTo(0, 0);
-        const isHomePath = (path.trim() === '' || path === '/') && !!home;
+        const isHomePath = (path?.trim() === '' || path === '/') && !!home;
         if (isHomePath) {
             const homeRoute = routes.find(r => r.route.match('/'));
             const guardsAllowed = checkGuards(homeRoute?.guards, {}, target);
@@ -3402,11 +4775,15 @@ function Router(options) {
             const hasLayout = layoutElement !== null || getCurrentLayoutElement(target) !== null;
             if (hasLayout) {
                 await renderWithLayout(target, element, finalTransition, layoutElement, needsNewLayout, path, {});
+                emitContextUpdate(target, path, {});
                 return;
             }
             await renderDirect(target, element, finalTransition);
+            emitContextUpdate(target, path, {});
             return;
         }
+        if (!path)
+            return;
         const routeResult = resolveRoute(path, target);
         const isGuardsFailed = routeResult.result === RouteResult.GUARDS_FAILED;
         if (isGuardsFailed) {
@@ -3421,9 +4798,11 @@ function Router(options) {
             const hasLayout = layoutElement !== null || getCurrentLayoutElement(target) !== null;
             if (hasLayout) {
                 await renderWithLayout(target, element, finalTransition, layoutElement, needsNewLayout, path, routeParams);
+                emitContextUpdate(target, path, routeParams);
                 return;
             }
             await renderDirect(target, element, finalTransition);
+            emitContextUpdate(target, path, routeParams);
             return;
         }
         const { element, transition, layout } = create404Element();
@@ -3433,9 +4812,11 @@ function Router(options) {
         const hasLayout = layoutElement !== null || getCurrentLayoutElement(target) !== null;
         if (hasLayout) {
             await renderWithLayout(target, element, finalTransition, layoutElement, needsNewLayout, path, {});
+            emitContextUpdate(target, path, {});
             return;
         }
         await renderDirect(target, element, finalTransition);
+        emitContextUpdate(target, path, {});
     }
     async function performTransition$1(container, oldElement, newElement, transition) {
         return performTransition(container, oldElement, newElement, transition);
@@ -3448,5 +4829,555 @@ function Router(options) {
     };
 }
 
-export { IS_CONTROLLER_INSTANCE, Router, SimpleArray, adopted, applyElementFunctionality, context, controller, dispatch, dispose, element, getSymbol, layout, moved, observe, on, part, property, query, queryAll, ready, request, respond, useNativeElementControllers, watch };
+// @on decorator removed in v3.0.0 - use template event syntax instead: @click=${handler}
+/**
+ * Decorator that automatically dispatches a custom event after a method is called.
+ * The return value of the method becomes the event detail.
+ *
+ * @param eventName The name of the event to dispatch
+ * @param options Optional configuration extending EventInit
+ */
+function dispatch(eventName, options) {
+    return function (originalMethod, _context) {
+        return function (...args) {
+            // Create timing wrappers for dispatch (per-instance)
+            if (!this[DISPATCH_TIMERS]) {
+                this[DISPATCH_TIMERS] = new Map();
+            }
+            const timerKey = `${eventName}_${_context.name}`;
+            if (!this[DISPATCH_TIMERS].has(timerKey)) {
+                this[DISPATCH_TIMERS].set(timerKey, {
+                    debounceTimeout: null,
+                    throttleLastCall: 0,
+                    throttleTimeout: null
+                });
+            }
+            const timers = this[DISPATCH_TIMERS].get(timerKey);
+            // Call the original method with preserved this context
+            const result = originalMethod.apply(this, args);
+            // Helper to dispatch the event
+            const doDispatch = (detail) => {
+                // Skip dispatch if result is undefined and dispatchOnUndefined is false
+                if (detail === undefined && options?.dispatchOnUndefined === false) {
+                    return;
+                }
+                // Create event with spread operator for options
+                const event = new CustomEvent(eventName, {
+                    bubbles: true, // Default to true for component events
+                    composed: true, // Allow crossing shadow DOM boundaries
+                    ...options, // Spread all EventInit options
+                    detail
+                });
+                this.dispatchEvent(event);
+            };
+            // Helper to handle timed dispatch
+            const timedDispatch = (detail) => {
+                if (options?.debounce) {
+                    clearTimeout(timers.debounceTimeout);
+                    timers.debounceTimeout = setTimeout(() => doDispatch(detail), options.debounce);
+                }
+                else if (options?.throttle) {
+                    const now = Date.now();
+                    const remaining = options.throttle - (now - timers.throttleLastCall);
+                    if (remaining <= 0) {
+                        clearTimeout(timers.throttleTimeout);
+                        timers.throttleLastCall = now;
+                        doDispatch(detail);
+                    }
+                    else if (!timers.throttleTimeout) {
+                        timers.throttleTimeout = setTimeout(() => {
+                            timers.throttleLastCall = Date.now();
+                            timers.throttleTimeout = null;
+                            doDispatch(detail);
+                        }, remaining);
+                    }
+                }
+                else {
+                    doDispatch(detail);
+                }
+            };
+            // Handle async methods
+            if (result instanceof Promise) {
+                return result.then((resolvedResult) => {
+                    timedDispatch(resolvedResult);
+                    return resolvedResult;
+                });
+            }
+            // Sync method
+            timedDispatch(result);
+            return result;
+        };
+    };
+}
+
+/**
+ * Custom element readiness utilities
+ * Handles waiting for custom elements to be defined with timeout warnings
+ */
+/**
+ * Global flag to disable custom element readiness timeout warnings
+ * Set this to true in environments where slow element registration is expected
+ */
+let DISABLE_ELEMENT_READY_WARNINGS = false;
+/**
+ * Set whether to disable custom element readiness timeout warnings
+ */
+function setDisableElementReadyWarnings(value) {
+    DISABLE_ELEMENT_READY_WARNINGS = value;
+}
+/**
+ * Default timeout for custom element registration warning (500ms)
+ */
+const DEFAULT_WARNING_TIMEOUT = 500;
+/**
+ * Wait for a custom element to be defined
+ * Logs a warning if it takes longer than the warning timeout
+ *
+ * @param tagName - The custom element tag name
+ * @param warningTimeout - Time in ms before warning (default 500ms)
+ * @returns Promise that resolves when element is defined
+ */
+async function waitForElementDefined(tagName, warningTimeout = DEFAULT_WARNING_TIMEOUT) {
+    // If already defined, return immediately
+    if (customElements.get(tagName)) {
+        return;
+    }
+    // Set up warning timer if not disabled
+    let warningTimer = null;
+    if (!DISABLE_ELEMENT_READY_WARNINGS) {
+        warningTimer = setTimeout(() => {
+            console.warn(`Custom element <${tagName}> is taking longer than ${warningTimeout}ms to register. ` +
+                `This may indicate a missing import or circular dependency. ` +
+                `Set DISABLE_ELEMENT_READY_WARNINGS=true to disable this warning.`);
+        }, warningTimeout);
+    }
+    try {
+        // Wait for element to be defined
+        await customElements.whenDefined(tagName);
+    }
+    finally {
+        // Clear warning timer
+        if (warningTimer) {
+            clearTimeout(warningTimer);
+        }
+    }
+}
+/**
+ * Wait for a custom element to be defined and ready
+ * First waits for the element to be registered, then waits for its ready promise
+ *
+ * @param element - The custom element instance
+ * @param warningTimeout - Time in ms before warning about registration (default 500ms)
+ * @returns Promise that resolves when element is defined and ready
+ */
+async function waitForElementReady(element, warningTimeout = DEFAULT_WARNING_TIMEOUT) {
+    const tagName = element.tagName.toLowerCase();
+    // Wait for element to be defined
+    await waitForElementDefined(tagName, warningTimeout);
+    // Wait for element's ready promise if it exists
+    if ('ready' in element && typeof element.ready?.then === 'function') {
+        await element.ready;
+    }
+}
+/**
+ * Process all custom elements in a node tree and wait for them to be ready
+ * This is useful after inserting a template with custom elements
+ *
+ * @param node - The root node to scan for custom elements
+ * @param warningTimeout - Time in ms before warning about registration (default 500ms)
+ * @returns Promise that resolves when all custom elements are ready
+ */
+async function waitForAllCustomElements(node, warningTimeout = DEFAULT_WARNING_TIMEOUT) {
+    const customElements = [];
+    // Find all custom elements (tag names with hyphens)
+    if (node instanceof Element) {
+        if (node.tagName.includes('-')) {
+            customElements.push(node);
+        }
+        // Also check in shadow DOM
+        if (node.shadowRoot) {
+            const shadowCustomElements = node.shadowRoot.querySelectorAll('*');
+            shadowCustomElements.forEach(el => {
+                if (el.tagName.includes('-')) {
+                    customElements.push(el);
+                }
+            });
+        }
+    }
+    // If it's a DocumentFragment, check all children
+    if (node instanceof DocumentFragment) {
+        const elements = node.querySelectorAll('*');
+        elements.forEach(el => {
+            if (el.tagName.includes('-')) {
+                customElements.push(el);
+            }
+        });
+    }
+    // Wait for all custom elements to be ready
+    await Promise.all(customElements.map(el => waitForElementReady(el, warningTimeout)));
+}
+
+/**
+ * Render debugging utilities for Snice v3.0.0
+ * For testing and debugging only - not recommended for production use
+ */
+/**
+ * Track renders of an element using an async generator
+ * Each call to tracker.next() waits for the next render to complete
+ *
+ * @example
+ * ```typescript
+ * const tracker = trackRenders(element);
+ *
+ * element.someProp = 'new value';
+ * await tracker.next(); // Waits for render
+ * // DOM is now updated
+ *
+ * element.someProp = 'another value';
+ * await tracker.next(); // Waits for next render
+ * // DOM is updated again
+ * ```
+ *
+ * WARNING: For testing/debugging only!
+ * - Do not use in production code
+ * - The generator yields indefinitely - use it only in controlled test environments
+ * - Each yield waits for the next render event
+ */
+async function* trackRenders(element) {
+    while (true) {
+        await new Promise(resolve => {
+            if (!element[RENDER_CALLBACKS]) {
+                element[RENDER_CALLBACKS] = [];
+            }
+            element[RENDER_CALLBACKS].push(resolve);
+        });
+        yield;
+    }
+}
+
+/**
+ * Method decorators for common patterns
+ * @debounce, @throttle, @once, @memoize
+ */
+const DEBOUNCE_TIMERS = getSymbol('debounce-timers');
+const THROTTLE_TIMERS = getSymbol('throttle-timers');
+const ONCE_CALLED = getSymbol('once-called');
+const MEMOIZE_CACHE = getSymbol('memoize-cache');
+/**
+ * @debounce decorator - delays function execution until after wait time has elapsed
+ * since the last invocation
+ *
+ * @param wait - Time to wait in milliseconds (default: 300)
+ * @param options - Debounce options
+ * @param options.leading - Invoke on the leading edge (default: false)
+ * @param options.trailing - Invoke on the trailing edge (default: true)
+ * @param options.maxWait - Maximum time to wait before invoking (default: undefined)
+ *
+ * @example
+ * ```typescript
+ * @element('search-input')
+ * class SearchInput extends HTMLElement {
+ *   @debounce(500)
+ *   handleSearch(query: string) {
+ *     // Only called 500ms after last keystroke
+ *     fetch(`/api/search?q=${query}`);
+ *   }
+ * }
+ * ```
+ */
+function debounce(wait = 300, options = {}) {
+    const { leading = false, trailing = true, maxWait } = options;
+    return function (originalMethod, context) {
+        const methodName = context.name;
+        return function (...args) {
+            if (!this[DEBOUNCE_TIMERS]) {
+                this[DEBOUNCE_TIMERS] = {};
+            }
+            const timers = this[DEBOUNCE_TIMERS];
+            const timerKey = methodName;
+            // Clear existing timer
+            if (timers[timerKey]) {
+                clearTimeout(timers[timerKey].timeout);
+            }
+            // Track when debounce started for maxWait
+            const now = Date.now();
+            const isFirstCall = !timers[timerKey];
+            const startTime = isFirstCall ? now : timers[timerKey].startTime;
+            // Check if maxWait exceeded
+            const shouldInvokeFromMaxWait = maxWait !== undefined && now - startTime >= maxWait;
+            // Leading edge invocation
+            if (leading && isFirstCall) {
+                const result = originalMethod.apply(this, args);
+                timers[timerKey] = {
+                    timeout: null,
+                    startTime,
+                    lastArgs: args,
+                };
+                return result;
+            }
+            // Set new timer for trailing edge
+            const timeout = setTimeout(() => {
+                if (trailing || shouldInvokeFromMaxWait) {
+                    originalMethod.apply(this, timers[timerKey].lastArgs);
+                }
+                delete timers[timerKey];
+            }, shouldInvokeFromMaxWait ? 0 : wait);
+            timers[timerKey] = {
+                timeout,
+                startTime,
+                lastArgs: args,
+            };
+        };
+    };
+}
+/**
+ * @throttle decorator - ensures function is called at most once per specified time period
+ *
+ * @param wait - Time to wait in milliseconds (default: 300)
+ * @param options - Throttle options
+ * @param options.leading - Invoke on the leading edge (default: true)
+ * @param options.trailing - Invoke on the trailing edge (default: true)
+ *
+ * @example
+ * ```typescript
+ * @element('scroll-tracker')
+ * class ScrollTracker extends HTMLElement {
+ *   @throttle(100)
+ *   handleScroll(e: Event) {
+ *     // Called at most once every 100ms
+ *     this.updateScrollPosition();
+ *   }
+ * }
+ * ```
+ */
+function throttle(wait = 300, options = {}) {
+    const { leading = true, trailing = true } = options;
+    return function (originalMethod, context) {
+        const methodName = context.name;
+        return function (...args) {
+            if (!this[THROTTLE_TIMERS]) {
+                this[THROTTLE_TIMERS] = {};
+            }
+            const timers = this[THROTTLE_TIMERS];
+            const timerKey = methodName;
+            const now = Date.now();
+            if (!timers[timerKey]) {
+                // First call
+                if (leading) {
+                    originalMethod.apply(this, args);
+                }
+                timers[timerKey] = {
+                    lastInvoke: now,
+                    timeout: null,
+                    lastArgs: args,
+                };
+                if (trailing && !leading) {
+                    // If no leading edge, set up trailing
+                    timers[timerKey].timeout = setTimeout(() => {
+                        originalMethod.apply(this, timers[timerKey].lastArgs);
+                        delete timers[timerKey];
+                    }, wait);
+                }
+            }
+            else {
+                // Subsequent calls
+                const timeSinceLastInvoke = now - timers[timerKey].lastInvoke;
+                // Update last args
+                timers[timerKey].lastArgs = args;
+                // Clear any pending trailing call
+                if (timers[timerKey].timeout) {
+                    clearTimeout(timers[timerKey].timeout);
+                }
+                if (timeSinceLastInvoke >= wait) {
+                    // Enough time has passed, invoke immediately
+                    originalMethod.apply(this, args);
+                    timers[timerKey].lastInvoke = now;
+                }
+                else if (trailing) {
+                    // Set up trailing call
+                    const remaining = wait - timeSinceLastInvoke;
+                    timers[timerKey].timeout = setTimeout(() => {
+                        originalMethod.apply(this, timers[timerKey].lastArgs);
+                        timers[timerKey].lastInvoke = Date.now();
+                        timers[timerKey].timeout = null;
+                    }, remaining);
+                }
+            }
+        };
+    };
+}
+/**
+ * @once decorator - ensures function is only called once
+ * Subsequent calls return the result of the first call
+ *
+ * @param perInstance - If true, function can be called once per instance (default: true)
+ *                      If false, function can only be called once globally across all instances
+ *
+ * @example
+ * ```typescript
+ * @element('data-loader')
+ * class DataLoader extends HTMLElement {
+ *   @once()
+ *   async loadData() {
+ *     // Only loads data once, even if called multiple times
+ *     const data = await fetch('/api/data');
+ *     return data.json();
+ *   }
+ * }
+ * ```
+ */
+function once(perInstance = true) {
+    let globalCalled = false;
+    let globalResult;
+    return function (originalMethod, context) {
+        const methodName = context.name;
+        return function (...args) {
+            if (perInstance) {
+                // Per-instance tracking
+                if (!this[ONCE_CALLED]) {
+                    this[ONCE_CALLED] = {};
+                }
+                if (!this[ONCE_CALLED][methodName]) {
+                    this[ONCE_CALLED][methodName] = {
+                        called: true,
+                        result: originalMethod.apply(this, args),
+                    };
+                }
+                return this[ONCE_CALLED][methodName].result;
+            }
+            else {
+                // Global tracking
+                if (!globalCalled) {
+                    globalCalled = true;
+                    globalResult = originalMethod.apply(this, args);
+                }
+                return globalResult;
+            }
+        };
+    };
+}
+/**
+ * @memoize decorator - caches function results based on arguments
+ * Uses JSON.stringify for argument comparison by default
+ *
+ * @param options - Memoization options
+ * @param options.keyGenerator - Custom function to generate cache key from arguments
+ * @param options.maxSize - Maximum cache size (default: 100)
+ * @param options.ttl - Time to live in milliseconds (default: undefined - no expiration)
+ *
+ * @example
+ * ```typescript
+ * @element('calculator')
+ * class Calculator extends HTMLElement {
+ *   @memoize({ maxSize: 50 })
+ *   fibonacci(n: number): number {
+ *     // Results are cached, subsequent calls with same n are instant
+ *     if (n <= 1) return n;
+ *     return this.fibonacci(n - 1) + this.fibonacci(n - 2);
+ *   }
+ * }
+ * ```
+ */
+function memoize(options = {}) {
+    const { keyGenerator = (...args) => JSON.stringify(args), maxSize = 100, ttl } = options;
+    return function (originalMethod, context) {
+        const methodName = context.name;
+        return function (...args) {
+            if (!this[MEMOIZE_CACHE]) {
+                this[MEMOIZE_CACHE] = {};
+            }
+            if (!this[MEMOIZE_CACHE][methodName]) {
+                this[MEMOIZE_CACHE][methodName] = new Map();
+            }
+            const cache = this[MEMOIZE_CACHE][methodName];
+            const key = keyGenerator(...args);
+            // Check if cached
+            if (cache.has(key)) {
+                const cached = cache.get(key);
+                // Check TTL
+                if (ttl !== undefined) {
+                    const age = Date.now() - cached.timestamp;
+                    if (age > ttl) {
+                        cache.delete(key);
+                    }
+                    else {
+                        return cached.value;
+                    }
+                }
+                else {
+                    return cached.value;
+                }
+            }
+            // Compute result
+            const result = originalMethod.apply(this, args);
+            // Store in cache
+            cache.set(key, {
+                value: result,
+                timestamp: Date.now(),
+            });
+            // Enforce max size (LRU - delete oldest)
+            if (cache.size > maxSize) {
+                const firstKey = cache.keys().next().value;
+                cache.delete(firstKey);
+            }
+            return result;
+        };
+    };
+}
+/**
+ * Clear all debounce timers for an instance
+ * Useful in cleanup/disconnectedCallback
+ */
+function clearDebounceTimers(instance) {
+    if (instance[DEBOUNCE_TIMERS]) {
+        for (const timerKey in instance[DEBOUNCE_TIMERS]) {
+            if (instance[DEBOUNCE_TIMERS][timerKey]?.timeout) {
+                clearTimeout(instance[DEBOUNCE_TIMERS][timerKey].timeout);
+            }
+        }
+        instance[DEBOUNCE_TIMERS] = {};
+    }
+}
+/**
+ * Clear all throttle timers for an instance
+ * Useful in cleanup/disconnectedCallback
+ */
+function clearThrottleTimers(instance) {
+    if (instance[THROTTLE_TIMERS]) {
+        for (const timerKey in instance[THROTTLE_TIMERS]) {
+            if (instance[THROTTLE_TIMERS][timerKey]?.timeout) {
+                clearTimeout(instance[THROTTLE_TIMERS][timerKey].timeout);
+            }
+        }
+        instance[THROTTLE_TIMERS] = {};
+    }
+}
+/**
+ * Clear memoize cache for an instance
+ */
+function clearMemoizeCache(instance, methodName) {
+    if (instance[MEMOIZE_CACHE]) {
+        if (methodName) {
+            delete instance[MEMOIZE_CACHE][methodName];
+        }
+        else {
+            instance[MEMOIZE_CACHE] = {};
+        }
+    }
+}
+/**
+ * Reset once-called state for an instance
+ */
+function resetOnce(instance, methodName) {
+    if (instance[ONCE_CALLED]) {
+        if (methodName) {
+            delete instance[ONCE_CALLED][methodName];
+        }
+        else {
+            instance[ONCE_CALLED] = {};
+        }
+    }
+}
+
+export { Context, IS_CONTROLLER_INSTANCE, Router, SimpleArray, adopted, applyElementFunctionality, clearDebounceTimers, clearMemoizeCache, clearThrottleTimers, context$1 as context, context as contextProperty, controller, css, debounce, dispatch, dispose, element, getSymbol, html, layout, memoize, moved, nothing, observe, on, once, property, query, queryAll, ready, render, request, resetOnce, respond, setDisableElementReadyWarnings, styles, throttle, trackRenders, unsafeHTML, useNativeElementControllers, waitForAllCustomElements, waitForElementDefined, waitForElementReady, watch };
 //# sourceMappingURL=index.esm.js.map