snice 5.2.2 → 6.0.0

package/dist/index.iife.js

@@ -1,5 +1,5 @@
 /*!
- * snice v5.2.1
+ * snice v5.2.3
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.
@@ -36,6 +36,12 @@ var Snice = (function (exports) {
     // Internal element state symbols
     const READY_PROMISE = getSymbol('ready-promise');
     const READY_RESOLVE = getSymbol('ready-resolve');
+    // Set when a render is requested but dropped because the element was
+    // disconnected; consumed on reconnect to replay exactly the missed render.
+    const PENDING_RECONNECT_RENDER = getSymbol('pending-reconnect-render');
+    // Per-element synchronous render-nesting depth, used to cap runaway re-entry
+    // without a shared global counter that one element could exhaust for others.
+    const RENDER_DEPTH = getSymbol('render-depth');
     const CONTROLLER = getSymbol('controller');
     const INITIALIZED = getSymbol('initialized');
     // Controller symbols
@@ -107,6 +113,10 @@ var Snice = (function (exports) {
     // Controller attach-abort — set to an AbortController while attachController
     // is awaiting element.ready, so detachController can short-circuit the wait.
     const CONTROLLER_ABORT = getSymbol('controller-abort');
+    // Set on a controller instance once it has gotten past element.ready and is
+    // being attached, so detachController knows not to run detach() on a controller
+    // whose attach() was aborted before it ever ran.
+    const CONTROLLER_ATTACHED = getSymbol('controller-attached');
     const PROPERTY_DEFINERS = getSymbol('property-definers');
 
     /**
@@ -227,11 +237,23 @@ var Snice = (function (exports) {
             this[REGISTERED_ELEMENTS_SET].add(element);
         }
         /**
-         * Unregister an element from receiving context updates
+         * Unregister an element from receiving context updates. With a methodName,
+         * removes only that one handler (so a `once` handler tearing itself down
+         * doesn't kill the element's other @context handlers); without one, removes
+         * the element entirely (used on disconnect).
          * @internal Used by @context decorator cleanup
          */
-        [CONTEXT_UNREGISTER](element) {
-            this[REGISTERED_ELEMENTS].delete(element);
+        [CONTEXT_UNREGISTER](element, methodName) {
+            const map = this[REGISTERED_ELEMENTS];
+            if (methodName !== undefined) {
+                const names = map.get(element);
+                if (!names)
+                    return;
+                names.delete(methodName);
+                if (names.size > 0)
+                    return; // other handlers remain — keep the element
+            }
+            map.delete(element);
             this[REGISTERED_ELEMENTS_SET].delete(element);
         }
         /**
@@ -396,11 +418,23 @@ var Snice = (function (exports) {
      * @param initialValue - The default value assigned to the property field (used for type detection)
      * @returns The string representation for the HTML attribute, or null if value should remove attribute
      */
+    /**
+     * Default property dirty-check: has the value changed? Like `!==`, but treats
+     * NaN → NaN as unchanged (NaN !== NaN would otherwise re-fire forever).
+     */
+    function notEqual(value, old) {
+        // Changed unless strictly equal, or both are NaN (each self-unequal).
+        return value !== old && (value === value || old === old);
+    }
     /**
      * Extract attribute name from property options
      */
     function getAttrName(opts, propName) {
-        return typeof opts.attribute === 'string' ? opts.attribute : propName.toLowerCase();
+        // Lowercase always: the DOM stores attribute names lowercase, so an explicit
+        // camelCase `attribute:` would otherwise never match observedAttributes and
+        // attributeChangedCallback would never fire. get/setAttribute are already
+        // case-insensitive, so this is safe for every caller.
+        return (typeof opts.attribute === 'string' ? opts.attribute : propName).toLowerCase();
     }
     /**
      * Escape HTML text-node content. Use for text that will be interpolated
@@ -547,6 +581,42 @@ var Snice = (function (exports) {
             }
         }
     }
+    /**
+     * Fire the one-time initialization call for `@watch(..., { immediate: true })`
+     * handlers. Runs once per declared property after the element is initialized,
+     * passing the effective initial value with `oldValue` undefined. Non-immediate
+     * watchers are untouched — they only react to later changes.
+     */
+    function invokeImmediateWatchers(instance, constructor) {
+        const watchers = constructor[PROPERTY_WATCHERS];
+        const properties = constructor[PROPERTIES];
+        if (!watchers || !properties)
+            return;
+        for (const [propName, propOptions] of properties) {
+            // A watcher may be registered under the JS name, the explicit `attribute:`
+            // name, or the `*` wildcard; fire each immediate one exactly once, keyed to
+            // this property's current value.
+            const keys = [propName];
+            const attrName = propOptions && typeof propOptions.attribute === 'string' ? propOptions.attribute : null;
+            if (attrName && attrName !== propName)
+                keys.push(attrName);
+            keys.push('*');
+            for (const key of keys) {
+                if (!watchers.has(key))
+                    continue;
+                for (const w of watchers.get(key)) {
+                    if (!w.immediate)
+                        continue;
+                    try {
+                        w.method.call(instance, undefined, instance[propName], propName);
+                    }
+                    catch (e) {
+                        console.error(`Error in @watch('${key}') method ${w.methodName}:`, e);
+                    }
+                }
+            }
+        }
+    }
     /**
      * Create a debounced version of a function
      */
@@ -580,6 +650,41 @@ var Snice = (function (exports) {
             }
         };
     }
+    /**
+     * Resolve a scope option to a concrete EventTarget.
+     *
+     * - undefined → host element (default behavior)
+     * - 'global' → `document`
+     * - string → `host.closest(selector)` (nearest matching ancestor)
+     * - EventTarget instance → that target directly
+     * - resolver function → called with host as `this`, returns target or null
+     *
+     * Returns null when the scope cannot be resolved (e.g. selector matches no
+     * ancestor, resolver returns null). Caller decides how to handle null —
+     * typically warn in dev and skip listener attachment.
+     */
+    function resolveScope(host, scope) {
+        if (scope === undefined || scope === null)
+            return host;
+        if (scope === 'global')
+            return typeof document !== 'undefined' ? document : null;
+        if (typeof scope === 'function') {
+            try {
+                return scope.call(host) || null;
+            }
+            catch {
+                return null;
+            }
+        }
+        if (typeof scope === 'string') {
+            return host.closest?.(scope) || null;
+        }
+        // Direct EventTarget instance.
+        if (scope && typeof scope.addEventListener === 'function') {
+            return scope;
+        }
+        return null;
+    }
     function valueToAttribute(value, propertyOptions, initialValue) {
         // Handle null/undefined/false values and empty arrays
         if (value === null || value === undefined || value === false ||
@@ -997,13 +1102,11 @@ var Snice = (function (exports) {
                         return finalValue;
                     }
                     catch (error) {
-                        // Send error to generator
-                        try {
-                            await generator.throw(error);
-                        }
-                        catch (generatorError) {
-                            throw generatorError;
-                        }
+                        // Drive the generator's own catch block and return whatever it recovers
+                        // with (e.g. a cached fallback). If the generator re-throws instead,
+                        // generator.throw rejects and the error propagates to the caller.
+                        const { value: recovered } = await generator.throw(error);
+                        return recovered;
                     }
                 }; // Close actualRequest function
                 // Debounce
@@ -1027,9 +1130,21 @@ var Snice = (function (exports) {
                 const now = Date.now();
                 const remaining = options.throttle - (now - throttleLastCall);
                 if (remaining <= 0) {
+                    // Cancelling the scheduled trailing call must not orphan the promises
+                    // queued for it — settle them with this fresh result. Also reset
+                    // throttleTimeout so later within-window calls don't attach to a dead
+                    // timer and hang.
                     clearTimeout(throttleTimeout);
+                    throttleTimeout = null;
                     throttleLastCall = now;
-                    return actualRequest();
+                    const orphaned = throttleTrailingResolvers.splice(0);
+                    const p = actualRequest();
+                    if (orphaned.length) {
+                        p.then((r) => { for (const x of orphaned)
+                            x.resolve(r); }, (e) => { for (const x of orphaned)
+                            x.reject(e); });
+                    }
+                    return p;
                 }
                 // Throttle: already has pending trailing call — attach to it
                 if (throttleTimeout) {
@@ -1130,10 +1245,20 @@ var Snice = (function (exports) {
                     const now = Date.now();
                     const remaining = handler.options.throttle - (now - throttleLastCall);
                     if (remaining <= 0) {
+                        // Same as the @request side: settle any queued trailing callers with
+                        // this fresh result rather than orphaning their promises.
                         clearTimeout(throttleTimeout);
                         throttleTimeout = null;
                         throttleLastCall = now;
-                        return originalMethod(...args);
+                        const orphaned = throttleTrailingResolvers.splice(0);
+                        throttleLatestArgs = null;
+                        const result = originalMethod(...args);
+                        if (orphaned.length) {
+                            Promise.resolve(result).then((r) => { for (const x of orphaned)
+                                x.resolve(r); }, (e) => { for (const x of orphaned)
+                                x.reject(e); });
+                        }
+                        return result;
                     }
                     // Remember the LATEST args so the trailing call uses fresh input,
                     // and queue every suppressed caller's resolver so they all receive
@@ -1240,7 +1365,10 @@ var Snice = (function (exports) {
         // 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];
+            // Inline a nested css`` result by its text so style fragments compose;
+            // String() on a CSSResult object would yield "[object Object]".
+            const value = values[i];
+            cssText += (isCSSResult(value) ? value.cssText : String(value)) + strings[i + 1];
         }
         const result = {
             _$litType$: CSS_RESULT,
@@ -1391,6 +1519,20 @@ var Snice = (function (exports) {
                                 const attrStrings = value.split(marker);
                                 // Number of expressions = number of markers = attrStrings.length - 1
                                 const expressionCount = attrStrings.length - 1;
+                                // Property/boolean/event bindings take a SINGLE expression — they
+                                // can't concatenate static text (a `.prop` is an object, not a
+                                // string). They consume the first expression; any static text or
+                                // extra expressions are ignored. But the value index must still
+                                // advance by the true marker count, or every later binding shifts.
+                                const isSingleExpressionBinding = /^@@?|^[.?]/.test(originalName);
+                                if (isSingleExpressionBinding) {
+                                    const hasStaticText = attrStrings.some((s) => s !== '');
+                                    if (expressionCount > 1 || hasStaticText) {
+                                        console.warn(`snice: binding "${originalName}" takes a single expression; ` +
+                                            `static text and extra interpolations are ignored. ` +
+                                            `Use a plain attribute for string interpolation.`);
+                                    }
+                                }
                                 if (originalName.startsWith('@@')) {
                                     // Escaped event binding for events with @ in the name (e.g., @@snice/event -> @snice/event)
                                     this.parts.push({
@@ -1399,7 +1541,7 @@ var Snice = (function (exports) {
                                         name: originalName.slice(1), // Keep the @ in the event name
                                         element
                                     });
-                                    partIndex += 1;
+                                    partIndex += expressionCount;
                                 }
                                 else if (originalName.startsWith('@')) {
                                     // Event binding (single value only)
@@ -1409,7 +1551,7 @@ var Snice = (function (exports) {
                                         name: originalName.slice(1),
                                         element
                                     });
-                                    partIndex += 1;
+                                    partIndex += expressionCount;
                                 }
                                 else if (originalName.startsWith('.')) {
                                     // Property binding (single value only)
@@ -1419,7 +1561,7 @@ var Snice = (function (exports) {
                                         name: originalName.slice(1),
                                         element
                                     });
-                                    partIndex += 1;
+                                    partIndex += expressionCount;
                                 }
                                 else if (originalName.startsWith('?')) {
                                     // Boolean attribute (single value only)
@@ -1429,7 +1571,7 @@ var Snice = (function (exports) {
                                         name: originalName.slice(1),
                                         element
                                     });
-                                    partIndex += 1;
+                                    partIndex += expressionCount;
                                 }
                                 else {
                                     // Regular attribute - supports multiple interpolations
@@ -1904,7 +2046,13 @@ var Snice = (function (exports) {
          * Commit unsafe HTML string
          */
         _commitUnsafeHTML(value) {
-            // Always recreate for unsafe HTML (can't diff arbitrary HTML)
+            // Can't diff arbitrary HTML, but when the STRING is unchanged the DOM is
+            // already correct — skip the clear+reparse so live state (typed input
+            // values, focus, scroll) inside the block survives unrelated re-renders.
+            const prev = this._committedValue;
+            if (isUnsafeHTML(prev) && prev.html === value.html) {
+                return;
+            }
             this._clear();
             const temp = document.createElement('template');
             temp.innerHTML = value.html;
@@ -2089,7 +2237,9 @@ var Snice = (function (exports) {
             // Supports both dot notation (@keydown.enter) and colon notation (@keydown:Enter) to match @on decorator
             // Only parse colons for keyboard events, not custom events
             const isKeyboardEvent = ['keydown', 'keyup', 'keypress'].includes(eventName.split('.')[0].split(':')[0]);
-            const dotIndex = eventName.indexOf('.');
+            // Only keyboard events split on `.`/`:` into a key filter — a custom event
+            // name may legitimately contain a dot (e.g. `app.ready`) and must be kept whole.
+            const dotIndex = isKeyboardEvent ? eventName.indexOf('.') : -1;
             const colonIndex = isKeyboardEvent ? eventName.indexOf(':') : -1;
             // Use whichever delimiter comes first (dot or colon)
             const delimiterIndex = dotIndex > 0 && colonIndex > 0
@@ -2103,6 +2253,7 @@ var Snice = (function (exports) {
             }
             else {
                 this.eventName = eventName;
+                warnIfModifierMisuse(eventName);
             }
         }
         commit(value) {
@@ -2128,17 +2279,19 @@ var Snice = (function (exports) {
             }
             if (typeof value !== 'function')
                 return;
-            // Auto-bind to host element (the custom element with shadow root)
-            if (!this.host) {
-                const rootNode = this.element.getRootNode();
-                this.host = rootNode.host || null;
-            }
-            const context = this.host || null;
             const keyFilter = this.keyFilter;
             this.listener = ((event) => {
                 if (keyFilter && !matchesKeyboardFilter(event, keyFilter))
                     return;
-                value.call(context, event);
+                // Resolve the host (the custom element owning the shadow root) at dispatch
+                // time, not bind time: a binding inside an initially-hidden <if>/<case>
+                // branch commits while off-DOM, where getRootNode() has no host — caching
+                // that null permanently would call the handler with `this = null` once the
+                // branch is shown. By the time an event fires, the element is in the DOM.
+                if (!this.host) {
+                    this.host = this.element.getRootNode().host || null;
+                }
+                value.call(this.host || null, event);
             });
             this.element.addEventListener(this.eventName, this.listener);
         }
@@ -2157,6 +2310,25 @@ var Snice = (function (exports) {
      *   "ctrl+shift+s" -> { key: "s", ctrl: true, shift: true }
      *   "~enter" -> { key: "Enter", anyModifiers: true }
      */
+    // once/preventDefault/stopPropagation/capture/passive are @on() OPTIONS, not
+    // template modifiers. A dotted non-keyboard event whose suffix is one of these
+    // is almost certainly a mistake (e.g. `@click.once`) — it binds a listener for
+    // an event type the DOM never dispatches. Warn instead of failing silently. A
+    // legitimate custom event name like `app.ready` won't match and stays quiet.
+    const MODIFIER_WORDS = new Set([
+        'once', 'prevent', 'preventdefault', 'stop', 'stoppropagation', 'capture', 'passive',
+    ]);
+    function warnIfModifierMisuse(eventName) {
+        const dot = eventName.lastIndexOf('.');
+        if (dot < 0)
+            return;
+        const suffix = eventName.slice(dot + 1).toLowerCase();
+        if (!MODIFIER_WORDS.has(suffix))
+            return;
+        console.warn(`snice: "@${eventName}" is not a valid modifier — once/preventDefault/` +
+            `stopPropagation/capture are @on() options, not template modifiers. ` +
+            `This registers a listener for event "${eventName}", which never fires.`);
+    }
     function parseKeyboardFilter(spec) {
         // Handle ~ prefix for matching regardless of modifiers
         const anyModifiers = spec.startsWith('~');
@@ -2259,9 +2431,14 @@ var Snice = (function (exports) {
             // Insert markers where <if> is
             parent.insertBefore(this.startNode, ifElement);
             parent.insertBefore(this.endNode, ifElement.nextSibling);
-            // Move <if>'s children between the markers
+            // Park <if>'s children in an off-DOM fragment immediately, rather than
+            // leaving them in the live template fragment. Otherwise a branch that is
+            // hidden on first render would still connect its children (when the
+            // template mounts) and then disconnect them (on the first commit) — firing
+            // mount side effects spuriously. commit(true) inserts them when shown.
+            this.childFragment = document.createDocumentFragment();
             while (ifElement.firstChild) {
-                parent.insertBefore(ifElement.firstChild, this.endNode);
+                this.childFragment.appendChild(ifElement.firstChild);
             }
             // Remove the <if> element from DOM
             parent.removeChild(ifElement);
@@ -2342,16 +2519,24 @@ var Snice = (function (exports) {
             parent.removeChild(caseElement);
         }
         commit(value) {
-            if (this.value === value)
+            // Dirty-check on the SELECTED BRANCH, not the raw value. A value whose type
+            // changed but stringifies the same (number 1 vs string '1' — e.g. a numeric
+            // default replaced by a router param, which is always a string) selects the
+            // same branch, so tearing it down and re-inserting it would needlessly
+            // restart media/animations and lose focus inside it.
+            const valueStr = String(value);
+            const hasBranch = this.branches.has(valueStr);
+            const nextKey = hasBranch ? valueStr : (this.defaultBranch ? '__default__' : null);
+            if (this.currentKey === nextKey) {
+                this.value = value;
                 return;
+            }
             this.value = value;
-            const valueStr = String(value);
             // Move current content back to its fragment
             this._collectCurrent();
             // Insert matching branch
-            const hasBranch = this.branches.has(valueStr);
             const matchingFragment = hasBranch ? this.branches.get(valueStr) : this.defaultBranch;
-            this.currentKey = hasBranch ? valueStr : (this.defaultBranch ? '__default__' : null);
+            this.currentKey = nextKey;
             if (matchingFragment && matchingFragment.hasChildNodes()) {
                 this.startNode.parentNode.insertBefore(matchingFragment, this.endNode);
             }
@@ -2529,7 +2714,9 @@ var Snice = (function (exports) {
             // Supports both dot notation (@keydown.enter) and colon notation (@keydown:Enter)
             // Only parse colons for keyboard events, not custom events
             const isKeyboardEvent = ['keydown', 'keyup', 'keypress'].includes(handler.eventName.split('.')[0].split(':')[0]);
-            const dotIndex = handler.eventName.indexOf('.');
+            // Only keyboard events split on `.`/`:` into a key filter — a custom event
+            // name may legitimately contain a dot (e.g. `app.ready`) and must be kept whole.
+            const dotIndex = isKeyboardEvent ? handler.eventName.indexOf('.') : -1;
             const colonIndex = isKeyboardEvent ? handler.eventName.indexOf(':') : -1;
             const delimiterIndex = dotIndex > 0 && colonIndex > 0
                 ? Math.min(dotIndex, colonIndex)
@@ -2540,6 +2727,8 @@ var Snice = (function (exports) {
             const keyModifier = delimiterIndex > 0
                 ? handler.eventName.substring(delimiterIndex + 1)
                 : null;
+            if (delimiterIndex <= 0)
+                warnIfModifierMisuse(handler.eventName);
             // Apply debounce (takes precedence over throttle)
             if (handlerOptions.debounce && handlerOptions.debounce > 0) {
                 boundMethod = createDebounced(boundMethod, handlerOptions.debounce);
@@ -2566,10 +2755,27 @@ var Snice = (function (exports) {
             };
             // Apply key modifier wrapper
             const keyModifierMethod = createKeyModifierHandler(boundMethod);
+            // Resolve scope: explicit `scope` option redirects the listener target
+            // to document / ancestor / arbitrary EventTarget. Default = host element.
+            const hasExplicitScope = handlerOptions.scope !== undefined;
+            let scopedTarget = null;
+            if (hasExplicitScope) {
+                scopedTarget = resolveScope(targetElement, handlerOptions.scope);
+                if (!scopedTarget) {
+                    // Dev warning — listener silently dropped when scope cannot resolve.
+                    // Skip attachment so we don't bind to the wrong target.
+                    console.warn(`[snice/@on] scope did not resolve for "${handler.eventName}" on ${handler.methodName} — listener skipped.`);
+                    continue;
+                }
+            }
             // 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;
+                // Delegated event handling.
+                // - Default eventRoot: shadow root if present, else host element.
+                // - With explicit scope: attach to the scoped target instead.
+                const eventRoot = hasExplicitScope
+                    ? scopedTarget
+                    : (targetElement.shadowRoot || targetElement);
                 const delegatedHandler = (event) => {
                     const target = event.target;
                     const matchingElement = (target.matches && target.matches(handler.selector) && target) ||
@@ -2609,10 +2815,11 @@ var Snice = (function (exports) {
                 });
             }
             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;
+                // Direct event handling.
+                // - Default: shadow root + host element (so events inside shadow and on
+                //   the host itself both fire). A per-handler Symbol dedupes.
+                // - With explicit scope: attach to the scoped target ONLY (no duplication).
+                const shadowRoot = hasExplicitScope ? null : targetElement.shadowRoot;
                 // Per-handler private Symbol so dedup is scoped to THIS handler's two
                 // listeners (shadowRoot + host). Using Symbol.for() with the method name
                 // would collide across components that share a method name (e.g. a parent
@@ -2640,6 +2847,16 @@ var Snice = (function (exports) {
                     once: handlerOptions.once || false,
                     passive: handlerOptions.passive || false,
                 };
+                if (hasExplicitScope) {
+                    scopedTarget.addEventListener(baseEventName, wrappedMethod, listenerOptions);
+                    instance[CLEANUP].events.push({
+                        target: scopedTarget,
+                        eventName: baseEventName,
+                        handler: wrappedMethod,
+                        options: listenerOptions,
+                    });
+                    continue;
+                }
                 if (shadowRoot) {
                     // Listen on shadow root for events inside shadow DOM
                     shadowRoot.addEventListener(baseEventName, wrappedMethod, listenerOptions);
@@ -2802,11 +3019,25 @@ var Snice = (function (exports) {
                 }),
             ]);
         }
+        catch (error) {
+            // Attach never got past `ready` (aborted or deadline). Roll back the stored
+            // references so nothing is left pointing at a controller that never
+            // attached — otherwise a later attach short-circuits as "already attached"
+            // and a detach would run detach() on it.
+            if (element[CONTROLLER_KEY] === controllerInstance) {
+                delete element[CONTROLLER_KEY];
+                delete element[CONTROLLER_NAME_KEY];
+                delete element[CONTROLLER_OPERATIONS];
+            }
+            throw error;
+        }
         finally {
             if (element[CONTROLLER_ABORT] === abort) {
                 delete element[CONTROLLER_ABORT];
             }
         }
+        // Past `ready` — mark the controller so detach knows attach was actually run.
+        controllerInstance[CONTROLLER_ATTACHED] = true;
         // Run attach in the controller's scope
         await scope.runOperation(async () => {
             await controllerInstance.attach(element);
@@ -2837,6 +3068,19 @@ var Snice = (function (exports) {
         if (!controllerInstance) {
             return;
         }
+        // Claim the controller immediately — before any await — so a second detach
+        // that overlaps this one (e.g. disconnect's fire-and-forget detach racing a
+        // controller reassignment) finds no instance and returns, instead of running
+        // detach() a second time on the same controller. The rest of this function
+        // works off the locals captured above.
+        delete element[CONTROLLER_KEY];
+        delete element[CONTROLLER_NAME_KEY];
+        delete element[CONTROLLER_OPERATIONS];
+        // A controller whose attach() was aborted before it ever ran must not have
+        // detach() (or the teardown/event) run on it.
+        if (!controllerInstance[CONTROLLER_ATTACHED]) {
+            return;
+        }
         // Run detach in the controller's scope
         if (scope) {
             await scope.runOperation(async () => {
@@ -2859,9 +3103,6 @@ var Snice = (function (exports) {
         }
         // Clean up router context reference
         delete controllerInstance[ROUTER_CONTEXT];
-        delete element[CONTROLLER_KEY];
-        delete element[CONTROLLER_NAME_KEY];
-        delete element[CONTROLLER_OPERATIONS];
         element.dispatchEvent(new CustomEvent('controller-detached', {
             detail: { name: controllerName, controller: controllerInstance }
         }));
@@ -3024,19 +3265,23 @@ var Snice = (function (exports) {
             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]) {
+                // `once` is tracked PER method (not a single element-level flag) so
+                // multiple once handlers on the same element each fire.
+                const called = element[CONTEXT_CALLED] ||
+                    (element[CONTEXT_CALLED] = new Set());
+                if (options.once && called.has(methodName)) {
                     return;
                 }
                 const callMethod = () => {
                     method.call(element, context);
                     // Handle once option
                     if (options.once) {
-                        element[CONTEXT_CALLED] = true;
-                        // Unregister after first call
+                        called.add(methodName);
+                        // Unregister ONLY this handler, not the whole element — otherwise the
+                        // element's other @context handlers would stop receiving updates.
                         const ctx = element[NAVIGATION_CONTEXT_INSTANCE];
                         if (ctx && typeof ctx[CONTEXT_UNREGISTER] === 'function') {
-                            ctx[CONTEXT_UNREGISTER](element);
+                            ctx[CONTEXT_UNREGISTER](element, wrappedMethodName);
                         }
                     }
                 };
@@ -3139,9 +3384,14 @@ var Snice = (function (exports) {
             this.pending.clear();
             this.scheduled = false;
             for (const element of elements) {
-                // Skip elements that were disconnected between scheduling and flush.
-                if (!element.isConnected)
+                // Skip elements that were disconnected between scheduling and flush, but
+                // remember the dropped render so reconnect can replay it — otherwise the
+                // shadow DOM stays stale for a property changed while detached. The flag
+                // lives on the element, so it's GC'd with it (no leak if never reattached).
+                if (!element.isConnected) {
+                    element[PENDING_RECONNECT_RENDER] = true;
                     continue;
+                }
                 const options = element[RENDER_OPTIONS] || {};
                 performRender(element, options);
             }
@@ -3160,6 +3410,19 @@ var Snice = (function (exports) {
         element[RENDER_CALLBACKS] = [];
         cbs.forEach(cb => cb());
     }
+    /**
+     * Backstop against a render() that mutates an observed property, which makes
+     * the property setter request another render from inside the current one. In
+     * `sync` mode that re-enters performRender synchronously and, unchecked,
+     * recurses to a stack overflow. The counter caps synchronous nesting and turns
+     * a silent crash into an actionable error. Normal renders never nest (child
+     * renders defer to a microtask), so this stays at depth 1 in the common case.
+     *
+     * The depth is tracked PER ELEMENT (on RENDER_DEPTH), not globally: a runaway
+     * component must not consume a shared budget and reject an unrelated component
+     * that happens to render inside its call stack.
+     */
+    const MAX_RENDER_DEPTH = 50;
     /**
      * Perform the actual render of an element
      */
@@ -3171,6 +3434,14 @@ var Snice = (function (exports) {
         if (options.once && element[RENDER_INSTANCE]) {
             return;
         }
+        const depth = (element[RENDER_DEPTH] ?? 0);
+        if (depth >= MAX_RENDER_DEPTH) {
+            const tag = element.tagName ? element.tagName.toLowerCase() : 'element';
+            console.error(`snice: maximum render depth (${MAX_RENDER_DEPTH}) exceeded for <${tag}>. ` +
+                `render() is mutating an observed property, causing an infinite render loop.`);
+            return;
+        }
+        element[RENDER_DEPTH] = depth + 1;
         try {
             const result = precomputedResult !== undefined ? precomputedResult : renderMethod.call(element);
             if (!element.shadowRoot)
@@ -3196,14 +3467,18 @@ var Snice = (function (exports) {
                 flushRenderCallbacks(element);
                 return;
             }
-            // Different template or first render. Remove only non-<style> children so
-            // the fallback @styles path (Safari <=16 / jsdom / SSR — no
-            // adoptedStyleSheets) doesn't lose its style tags on template switch.
+            // Different template or first render. Keep only the framework's own
+            // fallback <style> tags (marked data-snice-style) so the @styles path
+            // (Safari <=16 / jsdom / SSR — no adoptedStyleSheets) survives a template
+            // switch; template-emitted <style> tags are removed and re-created by the
+            // new instance, so they don't accumulate.
             if (instance) {
                 const root = element.shadowRoot;
                 const toRemove = [];
                 for (const child of Array.from(root.childNodes)) {
-                    if (child.nodeType === 1 && child.tagName === 'STYLE')
+                    if (child.nodeType === 1 &&
+                        child.tagName === 'STYLE' &&
+                        child.hasAttribute('data-snice-style'))
                         continue;
                     toRemove.push(child);
                 }
@@ -3219,6 +3494,9 @@ var Snice = (function (exports) {
         catch (error) {
             console.error('Error rendering element:', error);
         }
+        finally {
+            element[RENDER_DEPTH] = depth;
+        }
     }
     /**
      * Request a render for an element
@@ -3272,6 +3550,33 @@ var Snice = (function (exports) {
         // Normal rendering (with microtask batching unless sync)
         renderScheduler.schedule(element, options);
     }
+    /**
+     * Clear any pending debounce/throttle render timers on an element (e.g. on
+     * disconnect, so they don't fire on a dead element and retain it until they
+     * expire). Returns true if a render was actually pending, so the caller can
+     * arrange a replay on reconnect via PENDING_RECONNECT_RENDER.
+     */
+    function clearRenderTimers(element) {
+        const timers = element[RENDER_TIMERS];
+        if (!timers)
+            return false;
+        let hadPending = false;
+        if (timers.debounce) {
+            clearTimeout(timers.debounce);
+            timers.debounce = null;
+            hadPending = true;
+        }
+        if (timers.throttleTimer) {
+            clearTimeout(timers.throttleTimer);
+            timers.throttleTimer = null;
+            hadPending = true;
+        }
+        // Deliberately do NOT reset timers.lastThrottle: a plain DOM move is a
+        // disconnect+reconnect, and zeroing the cooldown would let the next render
+        // fire inside the throttle window. Preserving it keeps throttle honest
+        // across moves; on a true disconnect the element is discarded anyway.
+        return hadPending;
+    }
     /**
      * @render decorator for component rendering
      *
@@ -3394,9 +3699,12 @@ var Snice = (function (exports) {
                 element.shadowRoot.adoptedStyleSheets = allResults.map(r => r.styleSheet);
                 return;
             }
-            // Fallback — one <style> tag per stylesheet, preserving cascade order
+            // Fallback — one <style> tag per stylesheet, preserving cascade order.
+            // Marked so the template-switch cleanup keeps these (framework styles) but
+            // still removes template-emitted <style> tags (which would otherwise pile up).
             for (const r of allResults) {
                 const style = document.createElement('style');
+                style.setAttribute('data-snice-style', '');
                 style.textContent = r.cssText;
                 element.shadowRoot.appendChild(style);
             }
@@ -3406,6 +3714,125 @@ var Snice = (function (exports) {
         }
     }
 
+    // @dispatch decorator - auto-dispatches custom events from method return values
+    /**
+     * 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
+                    });
+                    // Resolve scope target. Default is `this` (host element).
+                    // Explicit scope dispatches the event on another target — useful for
+                    // 'global' bus events on document, or routing through an ancestor.
+                    if (options?.scope !== undefined) {
+                        const target = resolveScope(this, options.scope);
+                        if (!target) {
+                            console.warn(`[snice/@dispatch] scope did not resolve for "${eventName}" — event not dispatched.`);
+                            return;
+                        }
+                        target.dispatchEvent(event);
+                        return;
+                    }
+                    this.dispatchEvent(event);
+                };
+                // Helper to handle timed dispatch
+                const timedDispatch = (detail) => {
+                    if (options?.debounce) {
+                        clearTimeout(timers.debounceTimeout);
+                        timers.debounceTimeout = setTimeout(() => doDispatch(detail), options.debounce);
+                        return;
+                    }
+                    if (!options?.throttle) {
+                        doDispatch(detail);
+                        return;
+                    }
+                    const now = Date.now();
+                    const remaining = options.throttle - (now - timers.throttleLastCall);
+                    if (remaining <= 0) {
+                        clearTimeout(timers.throttleTimeout);
+                        timers.throttleLastCall = now;
+                        doDispatch(detail);
+                        return;
+                    }
+                    // Record the LATEST detail so the trailing dispatch carries fresh
+                    // data, not the first-suppressed-call detail captured by closure.
+                    timers.latestDetail = detail;
+                    if (!timers.throttleTimeout) {
+                        timers.throttleTimeout = setTimeout(() => {
+                            timers.throttleLastCall = Date.now();
+                            timers.throttleTimeout = null;
+                            const d = timers.latestDetail;
+                            timers.latestDetail = undefined;
+                            doDispatch(d);
+                        }, remaining);
+                    }
+                };
+                // Handle async methods
+                if (result instanceof Promise) {
+                    return result.then((resolvedResult) => {
+                        timedDispatch(resolvedResult);
+                        return resolvedResult;
+                    });
+                }
+                // Sync method
+                timedDispatch(result);
+                return result;
+            };
+        };
+    }
+    /**
+     * Clear any pending debounce/throttle dispatch timers on an instance (e.g. on
+     * disconnect, so a queued event doesn't fire into a detached node). A dispatch
+     * is a one-shot signal, so pending ones are dropped, not replayed.
+     */
+    function clearDispatchTimers(instance) {
+        const timers = instance[DISPATCH_TIMERS];
+        if (!timers)
+            return;
+        for (const t of timers.values()) {
+            if (t.debounceTimeout)
+                clearTimeout(t.debounceTimeout);
+            if (t.throttleTimeout)
+                clearTimeout(t.throttleTimeout);
+            t.debounceTimeout = null;
+            t.throttleTimeout = null;
+            t.throttleLastCall = 0;
+            t.latestDetail = undefined;
+        }
+    }
+
     /**
      * Method decorators for common patterns
      * @debounce, @throttle, @once, @memoize
@@ -3832,6 +4259,14 @@ var Snice = (function (exports) {
                         }
                     }
                 }
+                // Replay a render that was dropped while disconnected. The scheduler
+                // sets this flag when it skips a detached element, so a property changed
+                // while detached still reaches the DOM on reattach. A plain move (no
+                // pending render) leaves the flag unset, so we don't re-render needlessly.
+                if (this[RENDER_METHOD] && this[PENDING_RECONNECT_RENDER]) {
+                    this[PENDING_RECONNECT_RENDER] = false;
+                    requestRender(this);
+                }
                 return;
             }
             // Mark that properties are being initialized from attributes
@@ -3879,6 +4314,9 @@ var Snice = (function (exports) {
             setupResponseHandlers(this, this);
             setupContextHandler(this);
             this[INITIALIZED] = true;
+            // Now that the initial value is settled, give @watch immediate handlers
+            // their one init call (before the first render, so derived state is ready).
+            invokeImmediateWatchers(this, constructor);
             if (originalConnectedCallback) {
                 originalConnectedCallback.call(this);
             }
@@ -3973,6 +4411,17 @@ var Snice = (function (exports) {
             // Cleanup pending @debounce / @throttle timers so they don't fire on a dead element
             clearDebounceTimers(this);
             clearThrottleTimers(this);
+            // The render/dispatch debounce-throttle timers live in separate stores.
+            // A pending render is replayed on reconnect (same flag the scheduler
+            // uses); a pending dispatch is a one-shot signal, so it's dropped.
+            if (clearRenderTimers(this)) {
+                this[PENDING_RECONNECT_RENDER] = true;
+            }
+            clearDispatchTimers(this);
+            // @moved / @adopted debounce-throttle timers, likewise dropped so they
+            // don't fire on a dead element.
+            clearLifecycleTimers(this, MOVED_TIMERS);
+            clearLifecycleTimers(this, ADOPTED_TIMERS);
         };
         constructor.prototype.attributeChangedCallback = function (name, oldValue, newValue) {
             originalAttributeChangedCallback?.call(this, name, oldValue, newValue);
@@ -3988,13 +4437,27 @@ var Snice = (function (exports) {
                 if (attributeName.toLowerCase() !== name.toLowerCase())
                     continue;
                 const currentValue = this[PROPERTY_VALUES]?.[propName];
-                const parsedValue = parseAttributeValue(newValue, propOptions, currentValue, undefined);
-                if (currentValue === parsedValue)
+                // A removed attribute reverts the property to its field default. Read it
+                // back through the getter (attribute is already gone at this point) so the
+                // watcher's newValue and PROPERTY_VALUES match what this[propName] now
+                // returns — parseAttributeValue(null) would diverge to null for String/Number.
+                const parsedValue = newValue === null
+                    ? this[propName]
+                    : parseAttributeValue(newValue, propOptions, currentValue, undefined);
+                const changed = propOptions?.hasChanged
+                    ? propOptions.hasChanged(parsedValue, currentValue)
+                    : notEqual(parsedValue, currentValue);
+                if (!changed)
                     break;
                 ensureSet(this, EXPLICITLY_SET_PROPERTIES).add(propName);
                 ensureObj(this, PROPERTY_VALUES)[propName] = parsedValue;
                 if (!this[SETTING_FROM_PROPERTY]?.has(name.toLowerCase())) {
-                    invokeWatchers(this, constructor, propName, currentValue, parsedValue);
+                    // Watchers react to changes only. During upgrade the initial value
+                    // is not a change, so suppress until INITIALIZED; @watch immediate
+                    // handlers get their one init call from invokeImmediateWatchers.
+                    if (this[INITIALIZED]) {
+                        invokeWatchers(this, constructor, propName, currentValue, parsedValue);
+                    }
                     if (this[RENDER_METHOD] && this[INITIALIZED]) {
                         requestRender(this);
                     }
@@ -4004,12 +4467,14 @@ var Snice = (function (exports) {
         };
         // Add connectedMoveCallback for handling DOM moves
         constructor.prototype.connectedMoveCallback = async function () {
-            // Call @moved handlers
+            // Call @moved handlers via the prototype method (the debounce/throttle
+            // wrapper), not the raw handler — otherwise @moved({debounce}) options
+            // are ignored for real moves and only work when called directly.
             const movedHandlers = constructor[MOVED_HANDLERS];
             if (movedHandlers) {
                 for (const handler of movedHandlers) {
                     try {
-                        await handler.method.call(this);
+                        await this[handler.methodName]();
                     }
                     catch (error) {
                         console.error(`Error in @moved handler ${handler.methodName}:`, error);
@@ -4019,12 +4484,13 @@ var Snice = (function (exports) {
         };
         // Add adoptedCallback for handling document adoption
         constructor.prototype.adoptedCallback = async function () {
-            // Call @adopted handlers
+            // Call @adopted handlers via the prototype method (the debounce/throttle
+            // wrapper), not the raw handler — same reason as connectedMoveCallback.
             const adoptedHandlers = constructor[ADOPTED_HANDLERS];
             if (adoptedHandlers) {
                 for (const handler of adoptedHandlers) {
                     try {
-                        await handler.method.call(this);
+                        await this[handler.methodName]();
                     }
                     catch (error) {
                         console.error(`Error in @adopted handler ${handler.methodName}:`, error);
@@ -4189,7 +4655,12 @@ var Snice = (function (exports) {
                         },
                         set(newValue) {
                             const oldValue = this[propertyKey];
-                            if (oldValue === newValue)
+                            // A custom hasChanged comparator overrides the default === check
+                            // (e.g. deep-equal objects, or forcing an update on a mutated ref).
+                            const changed = finalOptions?.hasChanged
+                                ? finalOptions.hasChanged(newValue, oldValue)
+                                : notEqual(newValue, oldValue);
+                            if (!changed)
                                 return;
                             // Pre-init: store for later, don't reflect to DOM yet
                             if (!this[PROPERTIES_INITIALIZED]) {
@@ -4206,18 +4677,27 @@ var Snice = (function (exports) {
                                 const attributeName = getAttrName(finalOptions, propertyKey);
                                 const attributeValue = valueToAttribute(newValue, finalOptions, initialValue);
                                 ensureSet(this, EXPLICITLY_SET_PROPERTIES).add(propertyKey);
-                                ensureSet(this, SETTING_FROM_PROPERTY).add(attributeName.toLowerCase());
+                                const attrKey = attributeName.toLowerCase();
+                                ensureSet(this, SETTING_FROM_PROPERTY).add(attrKey);
+                                // attributeChangedCallback runs synchronously inside setAttribute /
+                                // removeAttribute (custom element reactions are synchronous), so the
+                                // guard only needs to bracket this one reflection. Clear it right
+                                // after — not on a microtask — otherwise an external attribute change
+                                // in the same tick is mistaken for our own echo and silently dropped.
                                 if (attributeValue === null) {
                                     this.removeAttribute?.(attributeName);
                                 }
                                 else {
                                     this.setAttribute?.(attributeName, attributeValue);
                                 }
-                                queueMicrotask(() => {
-                                    this[SETTING_FROM_PROPERTY]?.delete(attributeName.toLowerCase());
-                                });
+                                this[SETTING_FROM_PROPERTY].delete(attrKey);
+                            }
+                            // See attributeChangedCallback: the initial value is not a change,
+                            // so suppress watchers until INITIALIZED. @watch immediate handlers
+                            // get their one init call from invokeImmediateWatchers.
+                            if (this[INITIALIZED]) {
+                                invokeWatchers(this, this.constructor, propertyKey, oldValue, newValue);
                             }
-                            invokeWatchers(this, this.constructor, propertyKey, oldValue, newValue);
                             if (this[RENDER_METHOD] && this[INITIALIZED]) {
                                 requestRender(this);
                             }
@@ -4287,7 +4767,12 @@ var Snice = (function (exports) {
             };
         };
     }
-    function watch(...propertyNames) {
+    function watch(...args) {
+        // A trailing options object is separated from the watched property names.
+        const propertyNames = args.filter((a) => typeof a === 'string');
+        const options = args.find((a) => typeof a === 'object' && a !== null);
+        // Fire on init by default; opt out of the init call with { immediate: false }.
+        const immediate = options?.immediate !== false;
         return function (target, context) {
             const methodName = context.name;
             context.addInitializer(function () {
@@ -4327,7 +4812,8 @@ var Snice = (function (exports) {
                     }
                     constructor[PROPERTY_WATCHERS].get(propertyName).push({
                         methodName,
-                        method: target
+                        method: target,
+                        immediate
                     });
                 }
             });
@@ -4436,6 +4922,24 @@ var Snice = (function (exports) {
             registerHandler(RECONNECT_HANDLERS, RECONNECT_METHODS, target, context);
         };
     }
+    /**
+     * Clear any pending @moved / @adopted debounce/throttle timers on an instance
+     * (e.g. on disconnect), so they don't fire on a dead element.
+     */
+    function clearLifecycleTimers(instance, timersSymbol) {
+        const map = instance[timersSymbol];
+        if (!map)
+            return;
+        for (const t of map.values()) {
+            if (t.debounceTimer)
+                clearTimeout(t.debounceTimer);
+            if (t.throttleTimer)
+                clearTimeout(t.throttleTimer);
+            t.debounceTimer = null;
+            t.throttleTimer = null;
+            t.lastThrottleCall = 0;
+        }
+    }
     function createLifecycleDecorator(handlersSymbol, timersSymbol, methodsSymbol) {
         return function (options = {}) {
             return function (originalMethod, context) {
@@ -4449,9 +4953,23 @@ var Snice = (function (exports) {
                     }
                     const timers = this[timersSymbol].get(methodName);
                     const exec = (...a) => originalMethod.apply(this, a);
+                    // Deferred (debounce/throttle) calls run inside a setTimeout, outside
+                    // the caller's try/catch — so catch their sync throws and async
+                    // rejections here and log, rather than surface an uncaught error.
+                    const execDeferred = (...a) => {
+                        try {
+                            const result = originalMethod.apply(this, a);
+                            if (result && typeof result.then === 'function') {
+                                result.catch((error) => console.error(`Error in deferred lifecycle handler ${methodName}:`, error));
+                            }
+                        }
+                        catch (error) {
+                            console.error(`Error in deferred lifecycle handler ${methodName}:`, error);
+                        }
+                    };
                     if (options.debounce > 0) {
                         clearTimeout(timers.debounceTimer);
-                        timers.debounceTimer = setTimeout(() => exec(...args), options.debounce);
+                        timers.debounceTimer = setTimeout(() => execDeferred(...args), options.debounce);
                         return undefined;
                     }
                     if (options.throttle > 0) {
@@ -4465,7 +4983,7 @@ var Snice = (function (exports) {
                             timers.throttleTimer = setTimeout(() => {
                                 timers.throttleTimer = null;
                                 timers.lastThrottleCall = Date.now();
-                                exec(...args);
+                                execDeferred(...args);
                             }, remaining);
                         }
                         return undefined;
@@ -5097,6 +5615,40 @@ var Snice = (function (exports) {
         }
     }
 
+    /**
+     * Score a route pattern by specificity so that more specific routes are tried
+     * first. Scoring is per-segment by ROLE, not by string length: a static segment
+     * outweighs a dynamic (`:param`) segment, which outweighs a wildcard (`*` /
+     * `*name`). So `/post/new` beats `/post/:id`, and a splat always ranks last —
+     * regardless of how long the pattern string happens to be. This mirrors the
+     * segment-scoring model mainstream routers (React Router, Remix) use.
+     *
+     * Sort callers descending by this score (highest = most specific = first).
+     *
+     * NOTE: mirrored in `src/react/route-specificity.ts` for the isolated React
+     * bundle — keep the two in sync.
+     */
+    const STATIC_SEGMENT = 10;
+    const DYNAMIC_SEGMENT = 3;
+    const WILDCARD_SEGMENT = -2;
+    function routeSpecificity(spec) {
+        const segments = spec.split('/').filter(Boolean);
+        // Base on segment count so a deeper path outranks a shallower one on ties.
+        let score = segments.length;
+        for (const segment of segments) {
+            if (segment.startsWith('*')) {
+                score += WILDCARD_SEGMENT;
+            }
+            else if (segment.startsWith(':')) {
+                score += DYNAMIC_SEGMENT;
+            }
+            else {
+                score += STATIC_SEGMENT;
+            }
+        }
+        return score;
+    }
+
     /**
      * Generic transition system for animating between elements
      */
@@ -5364,7 +5916,7 @@ var Snice = (function (exports) {
             }
             const needsSorting = !is_sorted;
             if (needsSorting) {
-                routes.sort((a, b) => b.route.spec.length - a.route.spec.length);
+                routes.sort((a, b) => routeSpecificity(b.route.spec) - routeSpecificity(a.route.spec));
                 is_sorted = true;
             }
             // Collect placards from registered routes
@@ -5435,7 +5987,7 @@ var Snice = (function (exports) {
       </div>`;
             return container;
         }
-        async function checkGuards(guards, params, target) {
+        async function checkGuards(guards, params, target, stale) {
             const hasGuards = !!guards;
             if (!hasGuards) {
                 return true;
@@ -5443,8 +5995,11 @@ var Snice = (function (exports) {
             const guardsArray = Array.isArray(guards) ? guards : [guards];
             let spinner = null;
             let spinnerTimer = null;
-            // Show spinner after a short delay (avoids flash for fast sync guards)
+            // Show spinner after a short delay (avoids flash for fast sync guards).
+            // Skip if a newer navigation has already superseded this one.
             spinnerTimer = setTimeout(() => {
+                if (stale && stale())
+                    return;
                 spinner = createLoadingSpinner();
                 target.appendChild(spinner);
             }, 50);
@@ -5452,7 +6007,11 @@ var Snice = (function (exports) {
                 for (const guard of guardsArray) {
                     const allowed = await guard(context, params);
                     if (!allowed) {
-                        renderForbiddenPage(target);
+                        // Don't stomp the current page with a 403 if a newer navigation
+                        // already took over while this guard was resolving.
+                        if (!stale || !stale()) {
+                            renderForbiddenPage(target);
+                        }
                         return false;
                     }
                 }
@@ -5488,14 +6047,14 @@ var Snice = (function (exports) {
             div.innerHTML = /*html*/ `<h1>404</h1><p>Page not found</p>`;
             return { element: div, transition: undefined, layout: undefined };
         }
-        async function resolveRoute(path, target) {
+        async function resolveRoute(path, target, stale) {
             for (const route of routes) {
                 const params = route.route.match(path);
                 const isMatch = params !== false;
                 if (!isMatch) {
                     continue;
                 }
-                const guardsAllowed = await checkGuards(route.guards, params, target);
+                const guardsAllowed = await checkGuards(route.guards, params, target, stale);
                 if (!guardsAllowed) {
                     return { result: RouteResult.GUARDS_FAILED };
                 }
@@ -5623,7 +6182,7 @@ var Snice = (function (exports) {
             const isHomePath = (path?.trim() === '' || path === '/') && !!home;
             if (isHomePath) {
                 const homeRoute = routes.find(r => r.route.match('/'));
-                if (!(await checkGuards(homeRoute?.guards, {}, target)))
+                if (!(await checkGuards(homeRoute?.guards, {}, target, stale)))
                     return;
                 if (stale())
                     return;
@@ -5635,7 +6194,7 @@ var Snice = (function (exports) {
             if (!path)
                 return;
             // Resolve route
-            const routeResult = await resolveRoute(path, target);
+            const routeResult = await resolveRoute(path, target, stale);
             if (stale())
                 return;
             // Guards failed (403 already rendered by checkGuards)
@@ -5649,7 +6208,7 @@ var Snice = (function (exports) {
             }
             // 404 fallthrough
             const { element, transition, layout } = create404Element();
-            await renderPage(target, element, transition, layout, path, {});
+            await renderPage(target, element, transition, layout, path, {}, stale);
         }
         async function performTransition$1(container, oldElement, newElement, transition, atGen = navGeneration) {
             // `isStale` returns true when a newer navigate() has been kicked off.
@@ -5666,93 +6225,6 @@ var Snice = (function (exports) {
         };
     }
 
-    // @dispatch decorator - auto-dispatches custom events from method return values
-    /**
-     * 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);
-                        return;
-                    }
-                    if (!options?.throttle) {
-                        doDispatch(detail);
-                        return;
-                    }
-                    const now = Date.now();
-                    const remaining = options.throttle - (now - timers.throttleLastCall);
-                    if (remaining <= 0) {
-                        clearTimeout(timers.throttleTimeout);
-                        timers.throttleLastCall = now;
-                        doDispatch(detail);
-                        return;
-                    }
-                    // Record the LATEST detail so the trailing dispatch carries fresh
-                    // data, not the first-suppressed-call detail captured by closure.
-                    timers.latestDetail = detail;
-                    if (!timers.throttleTimeout) {
-                        timers.throttleTimeout = setTimeout(() => {
-                            timers.throttleLastCall = Date.now();
-                            timers.throttleTimeout = null;
-                            const d = timers.latestDetail;
-                            timers.latestDetail = undefined;
-                            doDispatch(d);
-                        }, remaining);
-                    }
-                };
-                // Handle async methods
-                if (result instanceof Promise) {
-                    return result.then((resolvedResult) => {
-                        timedDispatch(resolvedResult);
-                        return resolvedResult;
-                    });
-                }
-                // Sync method
-                timedDispatch(result);
-                return result;
-            };
-        };
-    }
-
     /**
      * createRequestHandler — vanilla JS utility for handling @request channels
      * outside of the Snice element/controller decorator system.