snice 7.2.0 → 7.4.0

package/dist/index.esm.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.
@@ -230,7 +230,7 @@ let contextIdCounter = 0;
  */
 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();
@@ -254,7 +254,7 @@ class Context {
         }
     }
     /**
-     * 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) {
@@ -268,10 +268,10 @@ class Context {
         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) {
@@ -312,7 +312,7 @@ class Context {
             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];
@@ -334,7 +334,7 @@ class Context {
         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) {
@@ -343,7 +343,12 @@ class Context {
             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);
+                }
             }
         }
     }
@@ -675,11 +680,17 @@ function invokeImmediateWatchers(instance, constructor) {
  */
 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)
@@ -1136,7 +1147,7 @@ function contextTarget(source) {
  * 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.');
     }
@@ -1148,9 +1159,26 @@ function installContextProvider(root, context) {
     }
     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();
     };
@@ -1180,7 +1208,7 @@ function getContext(source) {
     }
     const target = contextTarget(source);
     if (target) {
-        const detail = {};
+        const detail = { kind: 'application' };
         target.dispatchEvent(new CustomEvent(CONTEXT_REQUEST_EVENT, {
             bubbles: true,
             composed: true,
@@ -1199,6 +1227,39 @@ function getContext(source) {
     }
     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
@@ -1862,12 +1923,13 @@ function setupEventHandlers(instance, targetElement) {
     }
     // 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);
     }
@@ -1897,7 +1959,9 @@ function setupEventHandlers(instance, targetElement) {
             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);
@@ -2070,12 +2134,190 @@ function setupEventHandlers(instance, targetElement) {
 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() {
@@ -2409,6 +2651,10 @@ async function attachController(element, controller) {
     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
@@ -2474,6 +2720,8 @@ async function detachController(element) {
     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();
@@ -2607,158 +2855,6 @@ function useNativeElementControllers() {
     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
@@ -2994,14 +3090,32 @@ const NOT_COMMITTED = Symbol('not-committed');
 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');
@@ -4638,15 +4752,13 @@ class SpreadPart extends Part {
     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) {
@@ -4773,8 +4885,7 @@ class PropertyPart extends Part {
                 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
@@ -6806,7 +6917,7 @@ function applyElementFunctionality(constructor) {
             // 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);
@@ -6931,7 +7042,7 @@ function applyElementFunctionality(constructor) {
         }
         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.
@@ -8636,10 +8747,11 @@ function bindContextDaemons(context) {
  *
  * 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);
@@ -8657,6 +8769,15 @@ function provideContext(root, context) {
         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
@@ -8680,6 +8801,7 @@ function Router(options) {
     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
@@ -8699,7 +8821,7 @@ function Router(options) {
             return;
         releaseContextProvider?.();
         routerContextProviders.get(target)?.();
-        const releaseProvidedContext = provideContext(target, context);
+        const releaseProvidedContext = provideRouterContext(target, navigationContext);
         let released = false;
         const release = () => {
             if (released)
@@ -8770,7 +8892,11 @@ function Router(options) {
                 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;
         };
     }
@@ -8778,11 +8904,24 @@ function Router(options) {
      * 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':
@@ -8843,7 +8982,9 @@ function Router(options) {
         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
@@ -9566,5 +9707,5 @@ if (typeof document !== 'undefined') {
 // Supports event delegation, keyboard modifiers, debounce/throttle - see docs/events.md
 // Template event syntax (@click=${handler}) is also available as an alternative.
 
-export { Context, ContextAwareFetcher, IS_CONTROLLER_INSTANCE, Router, SimpleArray, SniceElement, TransitionMode, adopted, applyElementFunctionality, attachController, classMap, clearDebounceTimers, clearMemoizeCache, clearThrottleTimers, context$1 as context, context as contextProperty, controller, createRequestHandler, css, daemon, debounce, detachController, dispatch, dispose, element, escapeAttr, escapeHtml, getBodyScrollLockCount, getContext, getController, getSymbol, html, isSafeUrl, layout, live, lockBodyScroll, memoize, moved, noChange, nothing, observe, on, once, parseDuration, property, provideContext, query, queryAll, ready, reconnect, render, repeat, request, resetOnce, respond, setDisableElementReadyWarnings, setStrictRenderErrors, state, styleMap, styles, svg, throttle, trackRenders, unlockBodyScroll, unsafeHTML, useNativeElementControllers, waitForAllCustomElements, waitForElementDefined, waitForElementReady, watch };
+export { Context, ContextAwareFetcher, IS_CONTROLLER_INSTANCE, Router, SimpleArray, SniceElement, TransitionMode, adopted, applyElementFunctionality, attachController, classMap, clearDebounceTimers, clearMemoizeCache, clearThrottleTimers, context$1 as context, context as contextProperty, controller, createRequestHandler, css, daemon, debounce, detachController, dispatch, dispose, element, escapeAttr, escapeHtml, getBodyScrollLockCount, getContext, getContextFetch, getController, getSymbol, html, isSafeUrl, layout, live, lockBodyScroll, memoize, moved, noChange, nothing, observe, on, once, parseDuration, property, provideContext, query, queryAll, ready, reconnect, render, repeat, request, resetOnce, respond, setDisableElementReadyWarnings, setStrictRenderErrors, state, styleMap, styles, svg, throttle, trackRenders, unlockBodyScroll, unsafeHTML, useNativeElementControllers, waitForAllCustomElements, waitForElementDefined, waitForElementReady, watch };
 //# sourceMappingURL=index.esm.js.map