snice 7.2.0 → 7.4.0

package/dist/index.iife.js

@@ -1,5 +1,5 @@
 /*!
- * snice v7.1.1
+ * snice v7.3.0
  * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.
@@ -233,7 +233,7 @@ var Snice = (function (exports) {
      */
     class Context {
         constructor(context = {}, placards = [], currentRoute = '', routeParams = {}, fetcher) {
-            // Stores the SET of wrapped-method names per element so that classes with
+            // Stores the SET of wrapped-method names per subscriber so that classes with
             // multiple @context() handlers register every method, not just the last one.
             this[_a] = new WeakMap();
             this[_b] = new Set();
@@ -257,7 +257,7 @@ var Snice = (function (exports) {
             }
         }
         /**
-         * Register an element to receive context updates
+         * Register an element or controller to receive context updates
          * @internal Used by @context decorator
          */
         [(_a = REGISTERED_ELEMENTS, _b = REGISTERED_ELEMENTS_SET, _c = IS_UPDATING, CONTEXT_REGISTER)](element, methodName) {
@@ -271,10 +271,10 @@ var Snice = (function (exports) {
             this[REGISTERED_ELEMENTS_SET].add(element);
         }
         /**
-         * Unregister an element from receiving context updates. With a methodName,
+         * Unregister a subscriber from 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).
+         * the subscriber entirely (used on disconnect/detach).
          * @internal Used by @context decorator cleanup
          */
         [CONTEXT_UNREGISTER](element, methodName) {
@@ -315,7 +315,7 @@ var Snice = (function (exports) {
                 return;
             }
             this[IS_UPDATING] = true;
-            // Notify all registered elements by calling EVERY registered method
+            // Notify all registered subscribers by calling EVERY registered method
             // name on each. Classes with multiple @context() methods get all fired.
             const elementsSet = this[REGISTERED_ELEMENTS_SET];
             const elementsMap = this[REGISTERED_ELEMENTS];
@@ -337,7 +337,7 @@ var Snice = (function (exports) {
             this[IS_UPDATING] = false;
         }
         /**
-         * Notify a specific element of the current context state
+         * Notify a specific subscriber of the current context state
          * @internal Used by @context decorator
          */
         [CONTEXT_NOTIFY_ELEMENT](element) {
@@ -346,7 +346,12 @@ var Snice = (function (exports) {
                 return;
             for (const methodName of names) {
                 if (typeof element[methodName] === 'function') {
-                    element[methodName](this);
+                    try {
+                        element[methodName](this);
+                    }
+                    catch (error) {
+                        console.error(`Error calling @context method ${methodName}:`, error);
+                    }
                 }
             }
         }
@@ -678,11 +683,17 @@ var Snice = (function (exports) {
      */
     function createDebounced(fn, delay) {
         let timer = null;
-        return function (...args) {
+        const debounced = function (...args) {
             if (timer !== null)
                 clearTimeout(timer);
             timer = setTimeout(() => { fn.apply(this, args); timer = null; }, delay);
         };
+        debounced.cancel = () => {
+            if (timer !== null)
+                clearTimeout(timer);
+            timer = null;
+        };
+        return debounced;
     }
     /**
      * Create a throttled version of a function (leading + trailing edge)
@@ -1139,7 +1150,7 @@ var Snice = (function (exports) {
      * boundary. Public callers use provideContext(), which also activates the
      * daemon instances declared by the context.
      */
-    function installContextProvider(root, context) {
+    function installContextProvider(root, context, fetch, navigation) {
         if (!root || typeof root.addEventListener !== 'function' || typeof root.removeEventListener !== 'function') {
             throw new TypeError('provideContext() requires an EventTarget root.');
         }
@@ -1151,9 +1162,26 @@ var Snice = (function (exports) {
         }
         const listener = (event) => {
             const request = event;
-            if (!request.detail || request.detail.context !== undefined)
+            if (!request.detail)
+                return;
+            if (request.detail.kind === 'application') {
+                if (request.detail.context !== undefined)
+                    return;
+                request.detail.context = context;
+            }
+            else if (request.detail.kind === 'fetch') {
+                if (!fetch || request.detail.fetch !== undefined)
+                    return;
+                request.detail.fetch = fetch;
+            }
+            else if (request.detail.kind === 'navigation') {
+                if (!navigation || request.detail.navigation !== undefined)
+                    return;
+                request.detail.navigation = navigation;
+            }
+            else {
                 return;
-            request.detail.context = context;
+            }
             request.preventDefault();
             request.stopPropagation();
         };
@@ -1183,7 +1211,7 @@ var Snice = (function (exports) {
         }
         const target = contextTarget(source);
         if (target) {
-            const detail = {};
+            const detail = { kind: 'application' };
             target.dispatchEvent(new CustomEvent(CONTEXT_REQUEST_EVENT, {
                 bubbles: true,
                 composed: true,
@@ -1202,6 +1230,39 @@ var Snice = (function (exports) {
         }
         return undefined;
     }
+    /**
+     * Resolve the fetch function supplied by the nearest context provider.
+     * Router providers expose their ContextAwareFetcher-bound function here;
+     * explicit providers may supply the same dependency for non-router apps and
+     * tests without adding a reserved property to AppContext.
+     */
+    function getContextFetch(source) {
+        const target = contextTarget(source);
+        if (!target)
+            return undefined;
+        const detail = { kind: 'fetch' };
+        target.dispatchEvent(new CustomEvent(CONTEXT_REQUEST_EVENT, {
+            bubbles: true,
+            composed: true,
+            cancelable: true,
+            detail,
+        }));
+        return detail.fetch;
+    }
+    /** @internal Resolve the router Context visible to an element or controller. */
+    function getNavigationContext(source) {
+        const target = contextTarget(source);
+        if (!target)
+            return undefined;
+        const detail = { kind: 'navigation' };
+        target.dispatchEvent(new CustomEvent(CONTEXT_REQUEST_EVENT, {
+            bubbles: true,
+            composed: true,
+            cancelable: true,
+            detail,
+        }));
+        return detail.navigation;
+    }
 
     function isDaemonInstance(value) {
         return !!value
@@ -1865,12 +1926,13 @@ var Snice = (function (exports) {
         }
         // Initialize cleanup object if needed
         if (!instance[CLEANUP]) {
-            instance[CLEANUP] = { events: [], channels: [], observers: [] };
+            instance[CLEANUP] = { events: [], eventCancels: [], channels: [], observers: [] };
         }
-        else if (!instance[CLEANUP].events) {
+        if (!instance[CLEANUP].events)
             instance[CLEANUP].events = [];
-        }
-        else if (instance[CLEANUP].events.length > 0) {
+        if (!instance[CLEANUP].eventCancels)
+            instance[CLEANUP].eventCancels = [];
+        if (instance[CLEANUP].events.length > 0 || instance[CLEANUP].eventCancels.length > 0) {
             // Events already set up - clean them up first to avoid duplicates
             cleanupEventHandlers(instance);
         }
@@ -1900,7 +1962,9 @@ var Snice = (function (exports) {
                 warnIfModifierMisuse(handler.eventName);
             // Apply debounce (takes precedence over throttle)
             if (handlerOptions.debounce && handlerOptions.debounce > 0) {
-                boundMethod = createDebounced(boundMethod, handlerOptions.debounce);
+                const debounced = createDebounced(boundMethod, handlerOptions.debounce);
+                instance[CLEANUP].eventCancels.push(() => debounced.cancel());
+                boundMethod = debounced;
             }
             else if (handlerOptions.throttle && handlerOptions.throttle > 0) {
                 boundMethod = throttle$1(boundMethod, handlerOptions.throttle);
@@ -2073,12 +2137,190 @@ var Snice = (function (exports) {
     function cleanupEventHandlers(instance) {
         if (!instance[CLEANUP]?.events)
             return;
+        for (const cancel of instance[CLEANUP].eventCancels ?? [])
+            cancel();
+        instance[CLEANUP].eventCancels = [];
         for (const { target, eventName, handler, options } of instance[CLEANUP].events) {
             target.removeEventListener(eventName, handler, options);
         }
         instance[CLEANUP].events = [];
     }
 
+    /**
+     * @context decorator for receiving router context updates
+     */
+    const CONTEXT_HANDLERS = getSymbol('context-handlers');
+    /**
+     * @context decorator for receiving router context updates
+     *
+     * @example
+     * ```typescript
+     * @element('my-layout')
+     * class MyLayout extends HTMLElement {
+     *   @context
+     *   handleContext(ctx: Context) {
+     *     this.renderNav(ctx.placards, ctx.currentRoute);
+     *   }
+     *
+     *   @context({ debounce: 300 })
+     *   handleContextDebounced(ctx: Context) {
+     *     // Called after 300ms of no updates
+     *   }
+     * }
+     * ```
+     */
+    function context$1(options = {}) {
+        return function (originalMethod, context) {
+            const methodName = context.name;
+            context.addInitializer(function () {
+                const constructor = this.constructor;
+                // hasOwnProperty guards so subclasses don't mutate parent state via
+                // the prototype chain.
+                if (!Object.prototype.hasOwnProperty.call(constructor, CONTEXT_METHODS)) {
+                    constructor[CONTEXT_METHODS] = new Set();
+                }
+                if (constructor[CONTEXT_METHODS].has(originalMethod))
+                    return;
+                constructor[CONTEXT_METHODS].add(originalMethod);
+                if (!Object.prototype.hasOwnProperty.call(constructor, CONTEXT_HANDLERS)) {
+                    const inherited = constructor[CONTEXT_HANDLERS];
+                    constructor[CONTEXT_HANDLERS] = inherited ? [...inherited] : [];
+                }
+                constructor[CONTEXT_HANDLERS].push({
+                    methodName,
+                    method: originalMethod,
+                    options,
+                });
+            });
+            return originalMethod;
+        };
+    }
+    /**
+     * Set up context handlers for an element or attached controller.
+     * Called automatically by the corresponding managed lifecycle.
+     */
+    function setupContextHandler(element, catchUp = false) {
+        const handlers = element.constructor[CONTEXT_HANDLERS];
+        if (!handlers || !Array.isArray(handlers) || handlers.length === 0) {
+            return;
+        }
+        // Get the Context instance from the router
+        const ctx = element[CONTEXT_HANDLER] ?? getNavigationContext(element);
+        if (!ctx) {
+            return;
+        }
+        // Store the Context instance for cleanup
+        element[NAVIGATION_CONTEXT_INSTANCE] = ctx;
+        // A controller can finish attaching after the Router has already announced
+        // the current navigation. Track whether an update arrives during this turn;
+        // if none does, catch it up once from the Context's current state.
+        let receivedContextUpdate = false;
+        // Register each handler with the Context
+        for (const handler of handlers) {
+            const { methodName, method, options } = handler;
+            const wrappedMethodName = `__wrapped_${methodName}`;
+            // Create wrapped method with timing controls
+            element[wrappedMethodName] = function (context) {
+                receivedContextUpdate = true;
+                // `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) {
+                        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, wrappedMethodName);
+                        }
+                    }
+                };
+                // Per-handler timer slot to avoid debounce/throttle handlers on the same
+                // element overwriting each other's state.
+                const timerSlot = element[CONTEXT_TIMER] ||
+                    (element[CONTEXT_TIMER] = {});
+                const timerKey = methodName;
+                if (options.debounce) {
+                    clearTimeout(timerSlot[timerKey]?.timeout);
+                    timerSlot[timerKey] = {
+                        timeout: setTimeout(callMethod, options.debounce),
+                    };
+                    return;
+                }
+                if (options.throttle) {
+                    const now = Date.now();
+                    const lastCall = timerSlot[timerKey]?.lastCall || 0;
+                    if (now - lastCall >= options.throttle) {
+                        timerSlot[timerKey] = { lastCall: now };
+                        callMethod();
+                    }
+                    return;
+                }
+                callMethod();
+            };
+            // Register with the Context using the wrapped method name
+            if (typeof ctx[CONTEXT_REGISTER] === 'function') {
+                ctx[CONTEXT_REGISTER](element, wrappedMethodName);
+            }
+        }
+        if (catchUp && typeof ctx[CONTEXT_NOTIFY_ELEMENT] === 'function') {
+            return new Promise((resolve) => {
+                const notifyIfNeeded = () => {
+                    try {
+                        if (!receivedContextUpdate
+                            && element[NAVIGATION_CONTEXT_INSTANCE] === ctx) {
+                            ctx[CONTEXT_NOTIFY_ELEMENT](element);
+                        }
+                    }
+                    finally {
+                        resolve();
+                    }
+                };
+                if (catchUp === 'task')
+                    setTimeout(notifyIfNeeded, 0);
+                else
+                    queueMicrotask(notifyIfNeeded);
+            });
+        }
+    }
+    /**
+     * Clean up context handlers for an element or attached controller.
+     */
+    function cleanupContextHandler(element) {
+        const handlers = element.constructor[CONTEXT_HANDLERS];
+        if (!handlers || !Array.isArray(handlers) || handlers.length === 0) {
+            return;
+        }
+        // Clear any pending debounce timers (per-handler slots)
+        const timerSlot = element[CONTEXT_TIMER];
+        if (timerSlot && typeof timerSlot === 'object') {
+            for (const key of Object.keys(timerSlot)) {
+                if (timerSlot[key]?.timeout)
+                    clearTimeout(timerSlot[key].timeout);
+            }
+            delete element[CONTEXT_TIMER];
+        }
+        for (const handler of handlers) {
+            // Clean up wrapped method
+            const wrappedMethodName = `__wrapped_${handler.methodName}`;
+            delete element[wrappedMethodName];
+        }
+        // Unregister from Context if available
+        const ctx = element[NAVIGATION_CONTEXT_INSTANCE];
+        if (ctx && typeof ctx[CONTEXT_UNREGISTER] === 'function') {
+            ctx[CONTEXT_UNREGISTER](element);
+        }
+        delete element[NAVIGATION_CONTEXT_INSTANCE];
+        delete element[CONTEXT_CALLED];
+    }
+
     // Controller-scoped cleanup registry
     class ControllerScope {
         constructor() {
@@ -2412,6 +2654,10 @@ var Snice = (function (exports) {
         await scope.runOperation(async () => {
             await controllerInstance.attach(element);
         });
+        // @context has the same managed lifecycle on controllers as @on,
+        // @observe and @respond. Catch up controllers whose async attach completed
+        // after the Router announced the current navigation.
+        await setupContextHandler(controllerInstance, 'microtask');
         // Setup @observe observers for controller
         setupObservers(controllerInstance, element);
         // Setup @channel handlers for controller
@@ -2477,6 +2723,8 @@ var Snice = (function (exports) {
         cleanupResponseHandlers(controllerInstance);
         // Cleanup @on event handlers for controller
         cleanupEventHandlers(controllerInstance);
+        // Cleanup @context handlers for controller
+        cleanupContextHandler(controllerInstance);
         // Cleanup the controller scope
         if (scope) {
             await scope.cleanup();
@@ -2610,158 +2858,6 @@ var Snice = (function (exports) {
         globalThis.sniceNativeControllerObserver = observer;
     }
 
-    /**
-     * @context decorator for receiving router context updates
-     */
-    const CONTEXT_HANDLERS = getSymbol('context-handlers');
-    /**
-     * @context decorator for receiving router context updates
-     *
-     * @example
-     * ```typescript
-     * @element('my-layout')
-     * class MyLayout extends HTMLElement {
-     *   @context
-     *   handleContext(ctx: Context) {
-     *     this.renderNav(ctx.placards, ctx.currentRoute);
-     *   }
-     *
-     *   @context({ debounce: 300 })
-     *   handleContextDebounced(ctx: Context) {
-     *     // Called after 300ms of no updates
-     *   }
-     * }
-     * ```
-     */
-    function context$1(options = {}) {
-        return function (originalMethod, context) {
-            const methodName = context.name;
-            context.addInitializer(function () {
-                const constructor = this.constructor;
-                // hasOwnProperty guards so subclasses don't mutate parent state via
-                // the prototype chain.
-                if (!Object.prototype.hasOwnProperty.call(constructor, CONTEXT_METHODS)) {
-                    constructor[CONTEXT_METHODS] = new Set();
-                }
-                if (constructor[CONTEXT_METHODS].has(originalMethod))
-                    return;
-                constructor[CONTEXT_METHODS].add(originalMethod);
-                if (!Object.prototype.hasOwnProperty.call(constructor, CONTEXT_HANDLERS)) {
-                    const inherited = constructor[CONTEXT_HANDLERS];
-                    constructor[CONTEXT_HANDLERS] = inherited ? [...inherited] : [];
-                }
-                constructor[CONTEXT_HANDLERS].push({
-                    methodName,
-                    method: originalMethod,
-                    options,
-                });
-            });
-            return originalMethod;
-        };
-    }
-    /**
-     * Setup context handler for an element instance
-     * Called automatically during element connection
-     */
-    function setupContextHandler(element) {
-        const handlers = element.constructor[CONTEXT_HANDLERS];
-        if (!handlers || !Array.isArray(handlers) || handlers.length === 0) {
-            return;
-        }
-        // Get the Context instance from the router
-        const ctx = element[CONTEXT_HANDLER];
-        if (!ctx) {
-            return;
-        }
-        // Store the Context instance for cleanup
-        element[NAVIGATION_CONTEXT_INSTANCE] = ctx;
-        // Register each handler with the Context
-        for (const handler of handlers) {
-            const { methodName, method, options } = handler;
-            const wrappedMethodName = `__wrapped_${methodName}`;
-            // Create wrapped method with timing controls
-            element[wrappedMethodName] = function (context) {
-                // `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) {
-                        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, wrappedMethodName);
-                        }
-                    }
-                };
-                // Per-handler timer slot to avoid debounce/throttle handlers on the same
-                // element overwriting each other's state.
-                const timerSlot = element[CONTEXT_TIMER] ||
-                    (element[CONTEXT_TIMER] = {});
-                const timerKey = methodName;
-                if (options.debounce) {
-                    clearTimeout(timerSlot[timerKey]?.timeout);
-                    timerSlot[timerKey] = {
-                        timeout: setTimeout(callMethod, options.debounce),
-                    };
-                    return;
-                }
-                if (options.throttle) {
-                    const now = Date.now();
-                    const lastCall = timerSlot[timerKey]?.lastCall || 0;
-                    if (now - lastCall >= options.throttle) {
-                        timerSlot[timerKey] = { lastCall: now };
-                        callMethod();
-                    }
-                    return;
-                }
-                callMethod();
-            };
-            // Register with the Context using the wrapped method name
-            if (typeof ctx[CONTEXT_REGISTER] === 'function') {
-                ctx[CONTEXT_REGISTER](element, wrappedMethodName);
-            }
-        }
-    }
-    /**
-     * Cleanup context handler for an element instance
-     * Called automatically during element disconnection
-     */
-    function cleanupContextHandler(element) {
-        const handlers = element.constructor[CONTEXT_HANDLERS];
-        if (!handlers || !Array.isArray(handlers) || handlers.length === 0) {
-            return;
-        }
-        // Clear any pending debounce timers (per-handler slots)
-        const timerSlot = element[CONTEXT_TIMER];
-        if (timerSlot && typeof timerSlot === 'object') {
-            for (const key of Object.keys(timerSlot)) {
-                if (timerSlot[key]?.timeout)
-                    clearTimeout(timerSlot[key].timeout);
-            }
-            delete element[CONTEXT_TIMER];
-        }
-        for (const handler of handlers) {
-            // Clean up wrapped method
-            const wrappedMethodName = `__wrapped_${handler.methodName}`;
-            delete element[wrappedMethodName];
-        }
-        // Unregister from Context if available
-        const ctx = element[NAVIGATION_CONTEXT_INSTANCE];
-        if (ctx && typeof ctx[CONTEXT_UNREGISTER] === 'function') {
-            ctx[CONTEXT_UNREGISTER](element);
-        }
-        delete element[NAVIGATION_CONTEXT_INSTANCE];
-        delete element[CONTEXT_CALLED];
-    }
-
     /**
      * Template system for Snice v3.0.0
      * Provides html`` and css`` tagged template processors with differential rendering
@@ -2997,14 +3093,32 @@ var Snice = (function (exports) {
     function markPreUpgradePropertyBinding(element, propertyName) {
         const tagName = element.localName;
         if (!tagName?.includes('-'))
-            return;
+            return false;
         const registry = element.ownerDocument?.defaultView?.customElements ?? globalThis.customElements;
         if (registry?.get(tagName))
-            return;
+            return false;
         const target = element;
         if (!target[PRE_UPGRADE_PROPERTY_BINDINGS])
             target[PRE_UPGRADE_PROPERTY_BINDINGS] = new Set();
         target[PRE_UPGRADE_PROPERTY_BINDINGS].add(propertyName);
+        return true;
+    }
+    function commitPropertyValue(element, propertyName, value) {
+        if (!markPreUpgradePropertyBinding(element, propertyName)) {
+            element[propertyName] = value;
+            return;
+        }
+        // An undefined custom element can inherit a native IDL setter with the same
+        // name. Assignment would invoke that setter (for example HTMLElement.role),
+        // stringify structured data into an attribute, and leave no own value for
+        // @property's upgrade adoption. Park every pre-upgrade binding as the own,
+        // configurable value that the initializer already knows how to replay.
+        Object.defineProperty(element, propertyName, {
+            configurable: true,
+            enumerable: true,
+            writable: true,
+            value,
+        });
     }
     // noChange sentinel - preserves the currently committed value
     const noChange = Symbol.for('snice:no-change');
@@ -4641,15 +4755,13 @@ var Snice = (function (exports) {
         commitProperties(next) {
             for (const key of Object.keys(this.committed)) {
                 if (!Object.prototype.hasOwnProperty.call(next, key)) {
-                    markPreUpgradePropertyBinding(this.element, key);
-                    this.element[key] = undefined;
+                    commitPropertyValue(this.element, key, undefined);
                 }
             }
             for (const [key, value] of Object.entries(next)) {
                 if (Object.is(this.committed[key], value))
                     continue;
-                markPreUpgradePropertyBinding(this.element, key);
-                this.element[key] = value === nothing ? undefined : value;
+                commitPropertyValue(this.element, key, value === nothing ? undefined : value);
             }
         }
         commitAttributes(next) {
@@ -4776,8 +4888,7 @@ var Snice = (function (exports) {
                     return;
             }
             this._committedValue = value;
-            markPreUpgradePropertyBinding(this.element, this.name);
-            this.element[this.name] = value === nothing ? undefined : value;
+            commitPropertyValue(this.element, this.name, value === nothing ? undefined : value);
         }
         clear() {
             // This part is being destroyed with its owning template. The element is
@@ -6809,7 +6920,7 @@ var Snice = (function (exports) {
                 // Re-establish handlers that get cleaned up on disconnect
                 setupEventHandlers(this, this);
                 setupResponseHandlers(this, this);
-                setupContextHandler(this);
+                void setupContextHandler(this, 'task');
                 // Re-establish observers that get cleaned up on disconnect
                 try {
                     setupObservers(this, this);
@@ -6934,7 +7045,7 @@ var Snice = (function (exports) {
             }
             setupEventHandlers(this, this);
             setupResponseHandlers(this, this);
-            setupContextHandler(this);
+            void setupContextHandler(this, 'task');
             this[INITIALIZED] = true;
             // One-time (per class) sanity check: a @watch name with no matching
             // @property never fires — surface the typo instead of staying silent.
@@ -8639,10 +8750,11 @@ var Snice = (function (exports) {
      *
      * Daemon instances must already exist in context.daemons. The returned cleanup
      * removes the provider and deactivates framework communication for daemons no
-     * longer provided by any context.
+     * longer provided by any context. An optional fetch function is exposed on the
+     * same boundary through getContextFetch() without modifying the context object.
      */
-    function provideContext(root, context) {
-        const releaseProvider = installContextProvider(root, context);
+    function provideContextBoundary(root, context, options, navigation) {
+        const releaseProvider = installContextProvider(root, context, options.fetch, navigation);
         let releaseDaemons;
         try {
             releaseDaemons = bindContextDaemons(context);
@@ -8660,6 +8772,15 @@ var Snice = (function (exports) {
             releaseDaemons?.();
         };
     }
+    function provideContext(root, context, options = {}) {
+        return provideContextBoundary(root, context, options);
+    }
+    /** @internal Router-owned provider including live navigation state. */
+    function provideRouterContext(root, navigation) {
+        return provideContextBoundary(root, navigation.application, {
+            fetch: navigation.fetch,
+        }, navigation);
+    }
 
     // Router historically allows a later Router instance to take over the same
     // target. Track only Router-owned provider releases so that handoff remains
@@ -8683,6 +8804,7 @@ var Snice = (function (exports) {
         const win = options.window ?? window;
         const doc = options.document ?? document;
         const routes = [];
+        let nextRegistrationOrder = 0;
         let is_sorted = false;
         let placards = []; // Store collected placards
         let _404; // the 404 page
@@ -8702,7 +8824,7 @@ var Snice = (function (exports) {
                 return;
             releaseContextProvider?.();
             routerContextProviders.get(target)?.();
-            const releaseProvidedContext = provideContext(target, context);
+            const releaseProvidedContext = provideRouterContext(target, navigationContext);
             let released = false;
             const release = () => {
                 if (released)
@@ -8773,7 +8895,11 @@ var Snice = (function (exports) {
                     win.customElements.define(pageOptions.tag, constructor);
                 }
                 // Register the routes with guards, layout, and placard
-                pageOptions.routes.forEach(route => register(route, pageOptions.tag, pageOptions.transition, pageOptions.guards, pageOptions.layout, pageOptions.placard));
+                pageOptions.routes.forEach(route => {
+                    const path = typeof route === 'string' ? route : route.path;
+                    const order = typeof route === 'string' ? undefined : route.order;
+                    register(path, pageOptions.tag, pageOptions.transition, pageOptions.guards, pageOptions.layout, pageOptions.placard, order);
+                });
                 return constructor;
             };
         }
@@ -8781,11 +8907,24 @@ var Snice = (function (exports) {
          * Registers a new route with the router.
          * @param {string} route - The route path.
          * @param {string} tag - The custom element tag associated with the route.
+         * @param {number} order - Optional lower-first tie-break after specificity.
          * @example
          * register('/custom-route', 'custom-element');
          */
-        function register(route, tag, transition, guards, layout, placard) {
-            routes.push({ route: new Route(route), tag, transition, guards, layout, placard });
+        function register(route, tag, transition, guards, layout, placard, order = 0) {
+            if (!Number.isFinite(order)) {
+                throw new TypeError(`Route order for "${route}" must be a finite number.`);
+            }
+            routes.push({
+                route: new Route(route),
+                tag,
+                transition,
+                guards,
+                layout,
+                placard,
+                order,
+                registrationOrder: nextRegistrationOrder++
+            });
             is_sorted = false;
             switch (route) {
                 case '/404':
@@ -8846,7 +8985,9 @@ var Snice = (function (exports) {
             ensureContextProvider(target);
             const needsSorting = !is_sorted;
             if (needsSorting) {
-                routes.sort((a, b) => routeSpecificity(b.route.spec) - routeSpecificity(a.route.spec));
+                routes.sort((a, b) => routeSpecificity(b.route.spec) - routeSpecificity(a.route.spec)
+                    || a.order - b.order
+                    || a.registrationOrder - b.registrationOrder);
                 is_sorted = true;
             }
             // Collect placards from registered routes
@@ -9597,6 +9738,7 @@ var Snice = (function (exports) {
     exports.escapeHtml = escapeHtml;
     exports.getBodyScrollLockCount = getBodyScrollLockCount;
     exports.getContext = getContext;
+    exports.getContextFetch = getContextFetch;
     exports.getController = getController;
     exports.getSymbol = getSymbol;
     exports.html = html;