snice 5.2.3 → 6.0.0

package/dist/index.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v5.2.2
+ * 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.
@@ -35,6 +35,12 @@ const CHANNEL_HANDLERS = getSymbol('channel-handlers');
 // 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
@@ -106,6 +112,10 @@ const ADOPTED_METHODS = getSymbol('adopted-methods');
 // 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');
 
 /**
@@ -226,11 +236,23 @@ class Context {
         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);
     }
     /**
@@ -395,11 +417,23 @@ function parseAttributeValue(attributeValue, propertyOptions, currentValue, init
  * @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
@@ -546,6 +580,42 @@ function invokeWatchers(instance, constructor, propName, oldValue, newValue) {
         }
     }
 }
+/**
+ * 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
  */
@@ -579,6 +649,41 @@ function createThrottled(fn, delay) {
         }
     };
 }
+/**
+ * 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 ||
@@ -996,13 +1101,11 @@ function request(requestName, options) {
                     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
@@ -1026,9 +1129,21 @@ function request(requestName, options) {
             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) {
@@ -1129,10 +1244,20 @@ function setupResponseHandlers(instance, element) {
                 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
@@ -1239,7 +1364,10 @@ 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];
+        // 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,
@@ -1390,6 +1518,20 @@ class Template {
                             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({
@@ -1398,7 +1540,7 @@ class Template {
                                     name: originalName.slice(1), // Keep the @ in the event name
                                     element
                                 });
-                                partIndex += 1;
+                                partIndex += expressionCount;
                             }
                             else if (originalName.startsWith('@')) {
                                 // Event binding (single value only)
@@ -1408,7 +1550,7 @@ class Template {
                                     name: originalName.slice(1),
                                     element
                                 });
-                                partIndex += 1;
+                                partIndex += expressionCount;
                             }
                             else if (originalName.startsWith('.')) {
                                 // Property binding (single value only)
@@ -1418,7 +1560,7 @@ class Template {
                                     name: originalName.slice(1),
                                     element
                                 });
-                                partIndex += 1;
+                                partIndex += expressionCount;
                             }
                             else if (originalName.startsWith('?')) {
                                 // Boolean attribute (single value only)
@@ -1428,7 +1570,7 @@ class Template {
                                     name: originalName.slice(1),
                                     element
                                 });
-                                partIndex += 1;
+                                partIndex += expressionCount;
                             }
                             else {
                                 // Regular attribute - supports multiple interpolations
@@ -1903,7 +2045,13 @@ class NodePart extends Part {
      * 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;
@@ -2088,7 +2236,9 @@ class EventPart extends Part {
         // 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
@@ -2102,6 +2252,7 @@ class EventPart extends Part {
         }
         else {
             this.eventName = eventName;
+            warnIfModifierMisuse(eventName);
         }
     }
     commit(value) {
@@ -2127,17 +2278,19 @@ class EventPart extends Part {
         }
         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);
     }
@@ -2156,6 +2309,25 @@ class EventPart extends Part {
  *   "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('~');
@@ -2258,9 +2430,14 @@ class ConditionalIfPart extends Part {
         // 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);
@@ -2341,16 +2518,24 @@ class ConditionalCasePart extends Part {
         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);
         }
@@ -2528,7 +2713,9 @@ function setupEventHandlers(instance, targetElement) {
         // 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)
@@ -2539,6 +2726,8 @@ function setupEventHandlers(instance, targetElement) {
         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);
@@ -2565,10 +2754,27 @@ function setupEventHandlers(instance, targetElement) {
         };
         // 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) ||
@@ -2608,10 +2814,11 @@ function setupEventHandlers(instance, targetElement) {
             });
         }
         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
@@ -2639,6 +2846,16 @@ function setupEventHandlers(instance, targetElement) {
                 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);
@@ -2801,11 +3018,25 @@ async function attachController(element, controllerName) {
             }),
         ]);
     }
+    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);
@@ -2836,6 +3067,19 @@ async function detachController(element) {
     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 () => {
@@ -2858,9 +3102,6 @@ async function detachController(element) {
     }
     // 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 }
     }));
@@ -3023,19 +3264,23 @@ function setupContextHandler(element) {
         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);
                     }
                 }
             };
@@ -3138,9 +3383,14 @@ class RenderScheduler {
         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);
         }
@@ -3159,6 +3409,19 @@ function flushRenderCallbacks(element) {
     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
  */
@@ -3170,6 +3433,14 @@ function performRender(element, options, precomputedResult) {
     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)
@@ -3195,14 +3466,18 @@ function performRender(element, options, precomputedResult) {
             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);
             }
@@ -3218,6 +3493,9 @@ function performRender(element, options, precomputedResult) {
     catch (error) {
         console.error('Error rendering element:', error);
     }
+    finally {
+        element[RENDER_DEPTH] = depth;
+    }
 }
 /**
  * Request a render for an element
@@ -3271,6 +3549,33 @@ function requestRender(element, immediate = false) {
     // 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
  *
@@ -3393,9 +3698,12 @@ function applyStyles(element) {
             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);
         }
@@ -3405,6 +3713,125 @@ function applyStyles(element) {
     }
 }
 
+// @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
@@ -3831,6 +4258,14 @@ function applyElementFunctionality(constructor) {
                     }
                 }
             }
+            // 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
@@ -3878,6 +4313,9 @@ function applyElementFunctionality(constructor) {
         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);
         }
@@ -3972,6 +4410,17 @@ function applyElementFunctionality(constructor) {
         // 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);
@@ -3987,13 +4436,27 @@ function applyElementFunctionality(constructor) {
             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);
                 }
@@ -4003,12 +4466,14 @@ function applyElementFunctionality(constructor) {
     };
     // 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);
@@ -4018,12 +4483,13 @@ function applyElementFunctionality(constructor) {
     };
     // 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);
@@ -4188,7 +4654,12 @@ function property(options) {
                     },
                     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]) {
@@ -4205,18 +4676,27 @@ function property(options) {
                             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);
                         }
@@ -4286,7 +4766,12 @@ function queryAll(selector, options = {}) {
         };
     };
 }
-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 () {
@@ -4326,7 +4811,8 @@ function watch(...propertyNames) {
                 }
                 constructor[PROPERTY_WATCHERS].get(propertyName).push({
                     methodName,
-                    method: target
+                    method: target,
+                    immediate
                 });
             }
         });
@@ -4435,6 +4921,24 @@ function reconnect() {
         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) {
@@ -4448,9 +4952,23 @@ function createLifecycleDecorator(handlersSymbol, timersSymbol, methodsSymbol) {
                 }
                 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) {
@@ -4464,7 +4982,7 @@ function createLifecycleDecorator(handlersSymbol, timersSymbol, methodsSymbol) {
                         timers.throttleTimer = setTimeout(() => {
                             timers.throttleTimer = null;
                             timers.lastThrottleCall = Date.now();
-                            exec(...args);
+                            execDeferred(...args);
                         }, remaining);
                     }
                     return undefined;
@@ -5096,6 +5614,40 @@ class Route {
     }
 }
 
+/**
+ * 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
  */
@@ -5363,7 +5915,7 @@ function Router(options) {
         }
         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
@@ -5434,7 +5986,7 @@ function Router(options) {
       </div>`;
         return container;
     }
-    async function checkGuards(guards, params, target) {
+    async function checkGuards(guards, params, target, stale) {
         const hasGuards = !!guards;
         if (!hasGuards) {
             return true;
@@ -5442,8 +5994,11 @@ function Router(options) {
         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);
@@ -5451,7 +6006,11 @@ function Router(options) {
             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;
                 }
             }
@@ -5487,14 +6046,14 @@ function Router(options) {
         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 };
             }
@@ -5622,7 +6181,7 @@ function Router(options) {
         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;
@@ -5634,7 +6193,7 @@ function Router(options) {
         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)
@@ -5648,7 +6207,7 @@ function Router(options) {
         }
         // 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.
@@ -5665,93 +6224,6 @@ function Router(options) {
     };
 }
 
-// @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.