sibujs 4.8.0 → 4.10.0

package/dist/plugins.cjs

@@ -2008,6 +2008,24 @@ function untracked(fn) {
     resumeTracking();
   }
 }
+var currentOwnerScope = null;
+function getOwnerScope() {
+  return currentOwnerScope;
+}
+function runWithOwnerScope(scope, fn) {
+  const prev = currentOwnerScope;
+  currentOwnerScope = scope;
+  try {
+    return fn();
+  } finally {
+    currentOwnerScope = prev;
+  }
+}
+function bindOwnerScope(fn) {
+  const scope = currentOwnerScope;
+  if (scope === null) return fn;
+  return (...args) => runWithOwnerScope(scope, () => fn(...args));
+}
 var subscriberEpochCounter = 0;
 function retrack(effectFn, subscriber) {
   const prev = currentSubscriber;
@@ -2023,6 +2041,10 @@ function retrack(effectFn, subscriber) {
   currentSubscriber = subscriber;
   const sub2 = subscriber;
   if (sub2._cap === void 0) sub2._cap = currentDisposerCapture();
+  const prevScope = currentOwnerScope;
+  if (prevScope !== null && !sub2._epoch && sub2._scope === void 0) sub2._scope = prevScope;
+  const scope = sub2._scope === void 0 ? null : sub2._scope;
+  if (scope !== prevScope) currentOwnerScope = scope;
   const epoch = ++subscriberEpochCounter;
   sub2._epoch = epoch;
   sub2._structDirty = false;
@@ -2035,6 +2057,7 @@ function retrack(effectFn, subscriber) {
     effectFn();
   } finally {
     currentSubscriber = prev;
+    currentOwnerScope = prevScope;
     if (savedDepth !== 0) {
       suspendDepth = savedDepth;
       suspendSavedSub = savedSuspendSub;
@@ -2069,23 +2092,26 @@ function track(effectFn, subscriber) {
     trackingSuspended = false;
   }
   currentSubscriber = subscriber;
+  const sub2 = subscriber;
+  if (sub2._scope === void 0) sub2._scope = currentOwnerScope;
+  const prevScope = currentOwnerScope;
+  currentOwnerScope = sub2._scope;
   try {
     effectFn();
   } finally {
     currentSubscriber = prev;
+    currentOwnerScope = prevScope;
     if (savedDepth !== 0) {
       suspendDepth = savedDepth;
       suspendSavedSub = savedSuspendSub;
       trackingSuspended = true;
     }
-    const sub3 = subscriber;
-    for (let n = sub3.depsHead ?? null; n !== null; n = n.subNext) {
+    for (let n = sub2.depsHead ?? null; n !== null; n = n.subNext) {
       const sig = n.sig;
       sig.__activeNode = n.prevActive;
       n.prevActive = null;
     }
   }
-  const sub2 = subscriber;
   return sub2._dispose ?? (sub2._dispose = () => cleanup(subscriber));
 }
 function reactiveBinding(commit, ownerNode) {
@@ -2355,7 +2381,7 @@ function forEachSubscriber(signal2, visit) {
 }
 
 // src/reactivity/track.ts
-var _runtimeVersion = true ? "4.8.0" : "dev";
+var _runtimeVersion = true ? "4.10.0" : "dev";
 var REGISTRY_KEY = /* @__PURE__ */ Symbol.for("sibujs.reactive.v1");
 function resolveReactiveApi() {
   const g2 = globalThis;
@@ -2387,6 +2413,9 @@ function resolveReactiveApi() {
     getSubscriberCount,
     getSubscriberDeps,
     forEachSubscriber,
+    getOwnerScope,
+    runWithOwnerScope,
+    bindOwnerScope,
     version: _runtimeVersion
   };
   g2[REGISTRY_KEY] = local;
@@ -2410,6 +2439,9 @@ var notifySubscribers2 = API.notifySubscribers;
 var getSubscriberCount2 = API.getSubscriberCount;
 var getSubscriberDeps2 = API.getSubscriberDeps;
 var forEachSubscriber2 = API.forEachSubscriber;
+var getOwnerScope2 = API.getOwnerScope ?? getOwnerScope;
+var runWithOwnerScope2 = API.runWithOwnerScope ?? runWithOwnerScope;
+var bindOwnerScope2 = API.bindOwnerScope ?? bindOwnerScope;
 
 // src/reactivity/bindAttribute.ts
 function bindAttribute(el, attr, getter) {
@@ -3269,6 +3301,11 @@ function flushUserCleanups(ctx) {
   const list = ctx.userCleanups;
   if (list.length === 0) return;
   ctx.userCleanups = [];
+  const scope = ctx.subscriber._scope ?? null;
+  if (scope === getOwnerScope2()) runCleanups(list);
+  else runWithOwnerScope2(scope, () => runCleanups(list));
+}
+function runCleanups(list) {
   for (let i2 = list.length - 1; i2 >= 0; i2--) {
     try {
       list[i2]();
@@ -3418,9 +3455,14 @@ function normalizePathname(path2) {
   const trimmed = path2.length > 1 ? path2.replace(/\/+$/, "") : path2;
   return trimmed || "/";
 }
-function normalizeQuery(query) {
-  const params = new URLSearchParams(query);
-  return [...params.entries()].sort(([a2], [b2]) => a2 < b2 ? -1 : a2 > b2 ? 1 : 0).map(([k, v]) => `${k}=${v}`).join("&");
+function parseQuery(query) {
+  return Object.fromEntries(new URLSearchParams(query));
+}
+function paramsIdentity(params) {
+  return JSON.stringify(Object.entries(params).sort(([a2], [b2]) => a2 < b2 ? -1 : a2 > b2 ? 1 : 0));
+}
+function queryIdentity(query) {
+  return paramsIdentity(typeof query === "string" ? parseQuery(query) : query);
 }
 function isPathnameAncestor(target, current) {
   if (target === current) return true;
@@ -3885,12 +3927,12 @@ var _ComponentLoader = class _ComponentLoader {
    * resolved, so the import happens once and later mounts call the module's
    * factory directly.
    */
-  async instantiate(plan, route2, routePath) {
+  async instantiate(plan, route2, routePath, scope) {
     if (plan.kind === "factory") {
-      return this.instantiateFactory(plan.component, route2, routePath);
+      return this.instantiateFactory(plan.component, route2, routePath, scope);
     }
     const factory = await this.resolveModuleFactory(plan, route2, routePath);
-    return this.instantiateFactory(factory, route2, routePath);
+    return this.instantiateFactory(factory, route2, routePath, scope);
   }
   /**
    * Resolve a deferred plan's module and cache the factory it exports —
@@ -3935,14 +3977,14 @@ var _ComponentLoader = class _ComponentLoader {
    * `depth` bounds that unwrapping; a module whose default is itself a module
    * is a configuration error, not something to chase.
    */
-  async instantiateFactory(component, route2, routePath, depth = 0) {
-    const result = component();
+  async instantiateFactory(component, route2, routePath, scope, depth = 0) {
+    const result = scope ? runWithOwnerScope2(scope, component) : component();
     const value = this.isThenable(result) ? await result : result;
     if (this.isElement(value)) return value;
     if (depth === 0 && this.isFactoryLike(value)) {
       const factory = this.extractFactory(value, routePath);
       this.planCache.set(this.keyFor(route2), { kind: "factory", component: factory });
-      return this.instantiateFactory(factory, route2, routePath, depth + 1);
+      return this.instantiateFactory(factory, route2, routePath, scope, depth + 1);
     }
     throw new Error(`Component for route "${routePath}" must return Element, got ${typeof value}`);
   }
@@ -4121,7 +4163,7 @@ var _SibuRouter = class _SibuRouter {
   }
   createRouteContext(fullPath) {
     const { path: path2, query: queryString, hash } = splitRouteUrl(fullPath);
-    const query = Object.fromEntries(new URLSearchParams(queryString));
+    const query = parseQuery(queryString);
     const match = this.matcher.match(path2 || "/");
     const params = match?.params || {};
     const meta2 = match?.route.meta || {};
@@ -4285,7 +4327,7 @@ var _SibuRouter = class _SibuRouter {
   }
   isSameRoute(from, to) {
     if (from.matched.length === 0 && to.matched.length > 0) return false;
-    return from.path === to.path && JSON.stringify(from.params) === JSON.stringify(to.params) && JSON.stringify(from.query) === JSON.stringify(to.query) && from.hash === to.hash;
+    return from.path === to.path && paramsIdentity(from.params) === paramsIdentity(to.params) && queryIdentity(from.query) === queryIdentity(to.query) && from.hash === to.hash;
   }
   updateHistory(to, options) {
     const fullPath = this.options.base + to.path + (Object.keys(to.query).length ? `?${new URLSearchParams(to.query).toString()}` : "") + (to.hash ? `#${to.hash}` : "");
@@ -4347,9 +4389,12 @@ var _SibuRouter = class _SibuRouter {
   async loadPlan(route2, routePath) {
     return this.loader.loadPlan(route2, routePath);
   }
-  /** Create exactly one real instance from an already-resolved plan. */
-  async instantiateComponent(plan, route2, routePath) {
-    return this.loader.instantiate(plan, route2, routePath);
+  /**
+   * Create exactly one real instance from an already-resolved plan. With a
+   * `scope`, the factory runs in it (see `RouteScope`).
+   */
+  async instantiateComponent(plan, route2, routePath, scope) {
+    return this.loader.instantiate(plan, route2, routePath, scope);
   }
   /** Resolve a route's module/factory without creating any component instance. */
   async preloadPlan(route2, routePath) {
@@ -4505,14 +4550,72 @@ function setRoutes(routes) {
   if (!_routerRef.current) throw new Error("Router not initialized. Call createRouter() first.");
   _routerRef.current.updateRoutes(normalizeRoutes(routes));
 }
+var RouteScope = class {
+  constructor(route2) {
+    this.released = false;
+    const [get, set] = signal(route2);
+    this.get = get;
+    this.set = set;
+  }
+  /** The instance's route, or `null` once released. Reactive. */
+  read() {
+    return this.get();
+  }
+  /** Hand a kept instance the route of the navigation that kept it. */
+  update(route2) {
+    if (!this.released) this.set(route2);
+  }
+  /**
+   * Called when the instance is disposed. The switch to "no scope" is
+   * published a microtask later, once the whole dispose has finished: a
+   * teardown the instance registered after this one (an `onMount` effect, say)
+   * may still be alive at this point, and must not re-run against the
+   * router-global route on its way out.
+   */
+  release() {
+    if (this.released) return;
+    this.released = true;
+    queueMicrotask(() => this.set(null));
+  }
+};
+function activeRouteScope() {
+  const scope = getOwnerScope2();
+  return scope instanceof RouteScope ? scope : null;
+}
+function scopedRoute(router2) {
+  const scope = activeRouteScope();
+  if (scope) {
+    const committed = scope.read();
+    if (committed !== null) return committed;
+  }
+  return router2.currentRoute;
+}
+var instanceScopes = /* @__PURE__ */ new WeakMap();
+async function instantiateScoped(router2, plan, routeDef, routePath, route2) {
+  const scope = new RouteScope(route2);
+  const node = await router2.instantiateComponent(plan, routeDef, routePath, scope);
+  if (node) {
+    instanceScopes.set(node, scope);
+    registerDisposer(node, () => scope.release());
+  }
+  return node;
+}
+function updateInstanceRoute(node, route2) {
+  if (node) instanceScopes.get(node)?.update(route2);
+}
+function disposeOwned(node) {
+  const scope = instanceScopes.get(node);
+  if (scope) runWithOwnerScope2(scope, () => dispose(node));
+  else dispose(node);
+}
 function route() {
   if (!_routerRef.current) throw new Error("Router not initialized. Call createRouter() first.");
-  return _routerRef.current.currentRoute;
+  return scopedRoute(_routerRef.current);
 }
 function router() {
   if (!_routerRef.current) throw new Error("Router not initialized. Call createRouter() first.");
   return {
-    currentRoute: _routerRef.current.currentRoute,
+    currentRoute: scopedRoute(_routerRef.current),
     isReady: _routerRef.current.isReady,
     isNavigating: _routerRef.current.isNavigating,
     push: (to) => _routerRef.current?.push(to),
@@ -4598,13 +4701,13 @@ function Route() {
   const commitTarget = (seq) => routeTorn || seq !== navSeq ? null : anchor.parentNode;
   const release = (node) => {
     if (!node) return;
-    dispose(node);
+    disposeOwned(node);
     node.parentNode?.removeChild(node);
   };
   const cleanupNodes = () => {
     [currentNode, loadingNode, errorNode].forEach((node) => {
       if (!node) return;
-      dispose(node);
+      disposeOwned(node);
       if (node.parentNode) {
         node.parentNode.removeChild(node);
       }
@@ -4680,7 +4783,7 @@ function Route() {
   const update = async () => {
     if (routeTorn || !_routerRef.current) return;
     const seq = ++navSeq;
-    const route2 = _routerRef.current.currentRoute;
+    const route2 = scopedRoute(_routerRef.current);
     try {
       const match = _routerRef.current["matcher"].match(route2.path);
       if (!match) {
@@ -4692,6 +4795,7 @@ function Route() {
       const routeDef = match.matched[0] || match.route;
       const key = instanceKey(routeDef, [routeDef], route2);
       if (routeDef === currentTopRoute && key === currentKey && currentNode) {
+        updateInstanceRoute(currentNode, route2);
         return;
       }
       if ("redirect" in routeDef) {
@@ -4711,7 +4815,7 @@ function Route() {
           }
           const plan = await _routerRef.current.loadPlan(routeDef, route2.path);
           if (!commitTarget(seq)) return;
-          const node = await _routerRef.current.instantiateComponent(plan, routeDef, route2.path);
+          const node = await instantiateScoped(_routerRef.current, plan, routeDef, route2.path, route2);
           const parent = commitTarget(seq);
           if (!parent) {
             release(node);
@@ -4746,9 +4850,11 @@ function Route() {
   };
   const routeTeardown = track2(wrappedUpdate);
   if (!routeInitialized) {
-    queueMicrotask(() => {
-      if (!routeInitialized && anchor.parentNode) wrappedUpdate();
-    });
+    queueMicrotask(
+      bindOwnerScope2(() => {
+        if (!routeInitialized && anchor.parentNode) wrappedUpdate();
+      })
+    );
   }
   const routeCleanup = () => {
     if (routeTorn) return;
@@ -4781,7 +4887,7 @@ function KeepAliveRoute(options) {
     if (kaTorn || !_routerRef.current) return;
     const seq = ++updateSeq;
     const router2 = _routerRef.current;
-    const route2 = router2.currentRoute;
+    const route2 = scopedRoute(router2);
     const match = router2["matcher"].match(route2.path);
     if (!match) return;
     const { route: routeDef } = match;
@@ -4795,10 +4901,12 @@ function KeepAliveRoute(options) {
       return;
     }
     if (!("component" in routeDef)) return;
-    const queryStr = Object.keys(route2.query).length > 0 ? `?${new URLSearchParams(route2.query).toString()}` : "";
-    const cacheKey = `${route2.path}${queryStr}${route2.hash ? `#${route2.hash}` : ""}`;
+    const cacheKey = JSON.stringify([route2.path, queryIdentity(route2.query), route2.hash]);
     const shouldCache = !includeNames || routeDef.name != null && includeNames.includes(routeDef.name);
-    if (cacheKey === currentKey && currentNode) return;
+    if (cacheKey === currentKey && currentNode) {
+      updateInstanceRoute(currentNode, route2);
+      return;
+    }
     if (!anchor.parentNode) return;
     let node = null;
     let fromCache = false;
@@ -4809,7 +4917,7 @@ function KeepAliveRoute(options) {
       try {
         const plan = await router2.loadPlan(routeDef, route2.path);
         if (kaTorn || seq !== updateSeq) return;
-        node = await router2.instantiateComponent(plan, routeDef, route2.path);
+        node = await instantiateScoped(router2, plan, routeDef, route2.path, route2);
       } catch (error) {
         if (kaTorn || seq !== updateSeq) return;
         console.error("[KeepAliveRoute] Component error:", error);
@@ -4817,20 +4925,21 @@ function KeepAliveRoute(options) {
       }
       if (!node) return;
       if (kaTorn || seq !== updateSeq) {
-        dispose(node);
+        disposeOwned(node);
         return;
       }
     }
     const parent = anchor.parentNode;
     if (!parent) {
-      if (!fromCache) dispose(node);
+      if (!fromCache) disposeOwned(node);
       return;
     }
     if (currentNode && currentNode !== node) {
       if (currentNode.parentNode) currentNode.parentNode.removeChild(currentNode);
-      if (!currentCached) dispose(currentNode);
+      if (!currentCached) disposeOwned(currentNode);
     }
     if (fromCache) {
+      updateInstanceRoute(node, route2);
       const idx = lruOrder.indexOf(cacheKey);
       if (idx !== -1) lruOrder.splice(idx, 1);
       lruOrder.push(cacheKey);
@@ -4845,7 +4954,7 @@ function KeepAliveRoute(options) {
         }
         const evictNode = cache.get(evictKey);
         if (evictNode) {
-          dispose(evictNode);
+          disposeOwned(evictNode);
           if (evictNode.parentNode) evictNode.parentNode.removeChild(evictNode);
           cache.delete(evictKey);
         }
@@ -4863,9 +4972,11 @@ function KeepAliveRoute(options) {
   };
   const kaTeardown = track2(wrappedUpdate);
   if (!initialized) {
-    queueMicrotask(() => {
-      if (!initialized && anchor.parentNode) wrappedUpdate();
-    });
+    queueMicrotask(
+      bindOwnerScope2(() => {
+        if (!initialized && anchor.parentNode) wrappedUpdate();
+      })
+    );
   }
   const kaCleanup = () => {
     if (kaTorn) return;
@@ -4873,13 +4984,13 @@ function KeepAliveRoute(options) {
     updateSeq++;
     kaTeardown();
     for (const node of cache.values()) {
-      dispose(node);
+      disposeOwned(node);
       if (node.parentNode) node.parentNode.removeChild(node);
     }
     cache.clear();
     lruOrder.length = 0;
     if (currentNode?.parentNode) currentNode.parentNode.removeChild(currentNode);
-    if (currentNode && !currentCached) dispose(currentNode);
+    if (currentNode && !currentCached) disposeOwned(currentNode);
     currentNode = null;
     currentKey = "";
     currentCached = false;
@@ -4898,7 +5009,7 @@ function RouterLink(props, children) {
   const href = kind === "unsafe" ? "#" : rawHref;
   const { path: hrefPathRaw, query: hrefQueryRaw, hash: hrefHash } = splitRouteUrl(href);
   const targetPath = normalizePathname(hrefPathRaw);
-  const targetQuery = normalizeQuery(hrefQueryRaw);
+  const targetQuery = queryIdentity(hrefQueryRaw);
   const link2 = document.createElement("a");
   link2.href = href;
   if (target) {
@@ -4916,7 +5027,7 @@ function RouterLink(props, children) {
     const route2 = routeGetter();
     const currentPath = normalizePathname(route2.path);
     const isActive = kind === "internal" && isPathnameAncestor(targetPath, currentPath);
-    const isExactActive = kind === "internal" && currentPath === targetPath && normalizeQuery(route2.query) === targetQuery && route2.hash === hrefHash;
+    const isExactActive = kind === "internal" && currentPath === targetPath && queryIdentity(route2.query) === targetQuery && route2.hash === hrefHash;
     const classes = [];
     if (isActive) {
       if (activeClass) classes.push(activeClass);
@@ -5035,7 +5146,7 @@ function Suspense(props) {
     generation++;
     cleanupNodes();
   });
-  queueMicrotask(render);
+  queueMicrotask(bindOwnerScope2(render));
   return anchor;
 }
 var LAZY_MARKER = /* @__PURE__ */ Symbol.for("sibujs:lazy");
@@ -5103,7 +5214,7 @@ function Outlet() {
   let outletTorn = false;
   const clearCurrent = () => {
     if (currentNode) {
-      dispose(currentNode);
+      disposeOwned(currentNode);
       if (currentNode.parentNode) currentNode.parentNode.removeChild(currentNode);
       currentNode = null;
     }
@@ -5113,13 +5224,13 @@ function Outlet() {
   const commitTarget = (seq) => outletTorn || seq !== navSeq ? null : anchor.parentNode;
   const release = (node) => {
     if (!node) return;
-    dispose(node);
+    disposeOwned(node);
     node.parentNode?.removeChild(node);
   };
   const update = async () => {
     if (outletTorn || !_routerRef.current) return;
     const seq = ++navSeq;
-    const route2 = _routerRef.current.currentRoute;
+    const route2 = scopedRoute(_routerRef.current);
     if (route2.matched.length < 2) {
       clearCurrent();
       return;
@@ -5130,12 +5241,15 @@ function Outlet() {
       return;
     }
     const key = instanceKey(childRoute, route2.matched.slice(1), route2);
-    if (childRoute === currentChild && key === currentKey && currentNode) return;
+    if (childRoute === currentChild && key === currentKey && currentNode) {
+      updateInstanceRoute(currentNode, route2);
+      return;
+    }
     try {
       const cacheKey = `${route2.path}\0${childRoute.path}`;
       const plan = await _routerRef.current.loadPlan(childRoute, cacheKey);
       if (!commitTarget(seq)) return;
-      const node = await _routerRef.current.instantiateComponent(plan, childRoute, cacheKey);
+      const node = await instantiateScoped(_routerRef.current, plan, childRoute, cacheKey, route2);
       const parent = commitTarget(seq);
       if (!parent) {
         release(node);
@@ -5154,9 +5268,11 @@ function Outlet() {
   };
   const outletTeardown = track2(update);
   if (!anchor.parentNode) {
-    queueMicrotask(() => {
-      if (anchor.parentNode) update();
-    });
+    queueMicrotask(
+      bindOwnerScope2(() => {
+        if (anchor.parentNode) update();
+      })
+    );
   }
   const outletCleanup = () => {
     if (outletTorn) return;
@@ -5164,7 +5280,7 @@ function Outlet() {
     navSeq++;
     outletTeardown();
     if (currentNode) {
-      dispose(currentNode);
+      disposeOwned(currentNode);
       if (currentNode.parentNode) currentNode.parentNode.removeChild(currentNode);
       currentNode = null;
     }
@@ -5187,11 +5303,11 @@ function routerState() {
   if (!_routerRef.current) throw new Error("Router not initialized. Call createRouter() first.");
   const router2 = _routerRef.current;
   return {
-    currentPath: () => router2.currentRoute.path,
-    params: () => router2.currentRoute.params,
-    query: () => router2.currentRoute.query,
-    hash: () => router2.currentRoute.hash,
-    meta: () => router2.currentRoute.meta,
+    currentPath: () => scopedRoute(router2).path,
+    params: () => scopedRoute(router2).params,
+    query: () => scopedRoute(router2).query,
+    hash: () => scopedRoute(router2).hash,
+    meta: () => scopedRoute(router2).meta,
     isNavigating: () => router2.isNavigating,
     isReady: () => router2.isReady
   };
@@ -5905,7 +6021,7 @@ var CDN_ENTRY_POINTS = {
 };
 var packageInfo = {
   name: "sibujs",
-  version: true ? "4.8.0" : "dev",
+  version: true ? "4.10.0" : "dev",
   entryPoints: MODULE_ENTRY_POINTS,
   /**
    * Generate the package.json `exports` map. Module entries resolve to the
@@ -6050,7 +6166,7 @@ var env = {
 };
 
 // src/plugins/versioning.ts
-var VERSION = true ? "4.8.0" : "dev";
+var VERSION = true ? "4.10.0" : "dev";
 var NUM = "(?:0|[1-9]\\d*)";
 var PRE_ID = `(?:${NUM}|\\d*[a-zA-Z-][0-9a-zA-Z-]*)`;
 var BUILD_ID = "[0-9a-zA-Z-]+";

package/dist/plugins.d.cts

@@ -180,6 +180,12 @@ type Params = Record<string, string>;
 interface RouteContext {
     readonly path: string;
     readonly params: Params;
+    /**
+     * The decoded query (`+` is a space, `%XX` is decoded). A repeated key keeps
+     * its last value: `?tag=a&tag=b` is `{ tag: "b" }`. Two locations are the
+     * same route — for duplicate detection and `RouterLink` exact-active — when
+     * their queries have the same entries in any order.
+     */
     readonly query: Params;
     readonly hash: string;
     readonly meta: RouteMeta;
@@ -421,8 +427,11 @@ declare class SibuRouter {
      * anything. Pair with {@link instantiateComponent} at the commit boundary.
      */
     loadPlan(route: RouteDef, routePath: string): Promise<RoutePlan>;
-    /** Create exactly one real instance from an already-resolved plan. */
-    instantiateComponent(plan: RoutePlan, route: RouteDef, routePath: string): Promise<Element>;
+    /**
+     * Create exactly one real instance from an already-resolved plan. With a
+     * `scope`, the factory runs in it (see `RouteScope`).
+     */
+    instantiateComponent(plan: RoutePlan, route: RouteDef, routePath: string, scope?: RouteScope): Promise<Element>;
     /** Resolve a route's module/factory without creating any component instance. */
     preloadPlan(route: RouteDef, routePath: string): Promise<void>;
     beforeEach(guard: NavigationGuard): () => void;
@@ -469,6 +478,50 @@ declare function createRouter(routesOrOptions: RouteDef[] | RouterOptions, optio
  * Set routes on the global router (replaces existing routes).
  */
 declare function setRoutes(routes: RouteDef[]): void;
+/**
+ * The route one mounted route instance was committed with.
+ *
+ * A navigation commits the router's route first; the outlet swaps the
+ * component afterwards — a microtask later for a synchronous page, a whole
+ * chunk download later for a lazy one. If route instances read the
+ * router-global route, the outgoing page re-runs its effects against the
+ * INCOMING route's params in that window, and its teardown sees them too.
+ *
+ * So each instance reads its own scope instead. Outlets create one per
+ * instance, run the component factory in it (an owner scope, see
+ * reactivity/track-core.ts, so every computation the page creates — now or
+ * later, through its directives — inherits it), and then:
+ *
+ * - an instance the outlet KEEPS across a navigation (same record and instance
+ *   key: a query/hash-only change, or a layout whose child changed) is handed
+ *   the new route — it follows the navigation, as before;
+ * - an instance being REPLACED is never updated: it keeps observing its own
+ *   route until it is disposed, and its teardown runs in its scope;
+ * - a KeepAlive view keeps its route while cached and gets the new route when
+ *   it is shown again.
+ *
+ * Once the instance is disposed the scope is released: a computation that
+ * outlived it (an app-lifetime derived that happened to be created while the
+ * page rendered) is not the page's, and falls back to the router-global route.
+ */
+declare class RouteScope {
+    private readonly get;
+    private readonly set;
+    private released;
+    constructor(route: RouteContext);
+    /** The instance's route, or `null` once released. Reactive. */
+    read(): RouteContext | null;
+    /** Hand a kept instance the route of the navigation that kept it. */
+    update(route: RouteContext): void;
+    /**
+     * Called when the instance is disposed. The switch to "no scope" is
+     * published a microtask later, once the whole dispose has finished: a
+     * teardown the instance registered after this one (an `onMount` effect, say)
+     * may still be alive at this point, and must not re-run against the
+     * router-global route on its way out.
+     */
+    release(): void;
+}
 /**
  * Read the current route as a plain snapshot.
  *
@@ -477,6 +530,13 @@ declare function setRoutes(routes: RouteDef[]): void;
  * `RouteBase.key`). Inside a getter — `() => route().params.id` — the read is
  * reactive, which is what a long-lived layout or a constant-`key` route needs.
  *
+ * Inside a route instance (anything its component creates, and any effect,
+ * derived or binding created from there) this is the route THAT INSTANCE was
+ * committed with. An instance the outlet keeps across a navigation follows it;
+ * an instance being replaced keeps its own route until it is disposed, so its
+ * effects and teardown never observe the next page's params. Everywhere else
+ * it is the router's current route.
+ *
  * @returns The active {@link RouteContext} (path, params, query, hash).
  * @throws If no router has been created yet.
  */