@sigmela/router 0.1.3 → 0.2.1

package/lib/module/Router.js

@@ -3,81 +3,111 @@
 import { nanoid } from 'nanoid/non-secure';
 import { Platform } from 'react-native';
 import qs from 'query-string';
-
-// Root transition option: allow string shorthand like 'fade'
-
-function isTabBarLike(obj) {
-  return obj != null && typeof obj === 'object' && 'onIndexChange' in obj && 'getState' in obj && 'subscribe' in obj && 'stacks' in obj;
+function canSwitchToRoute(node) {
+  return node !== undefined && typeof node.switchToRoute === 'function';
 }
-function isNavigationStackLike(obj) {
-  return obj != null && typeof obj === 'object' && 'getRoutes' in obj && 'getId' in obj;
+function canLookupRoutes(node) {
+  return node !== undefined && typeof node.hasRoute === 'function';
 }
 const EMPTY_ARRAY = [];
 export class Router {
-  tabBar = null;
   root = null;
-  global = null;
   listeners = new Set();
   registry = [];
   state = {
-    history: [],
-    activeTabIndex: undefined
+    history: []
   };
+  debugEnabled = false;
   sheetDismissers = new Map();
-
-  // per-stack slices and listeners
-  stackSlices = new Map();
   stackListeners = new Map();
-  activeTabListeners = new Set();
   stackById = new Map();
   routeById = new Map();
-  visibleRoute = null;
-  // Root structure listeners (TabBar ↔ NavigationStack changes)
+  stackActivators = new Map();
+  stackHistories = new Map();
+  activeRoute = null;
   rootListeners = new Set();
   rootTransition = undefined;
+  lastBrowserIndex = 0;
+  suppressHistorySyncCount = 0;
+
+  // Used to prevent stale controller-driven navigations (controller calls present later).
+  navigationToken = 0;
   constructor(config) {
+    this.debugEnabled = config.debug ?? false;
     this.routerScreenOptions = config.screenOptions;
-    if (isTabBarLike(config.root)) {
-      this.tabBar = config.root;
-    }
-    if (config.global) {
-      this.global = config.global;
-    }
+    this.log('ctor');
     this.root = config.root;
-    if (this.tabBar) {
-      this.state = {
-        history: [],
-        activeTabIndex: this.tabBar.getState().index
-      };
-    }
     this.buildRegistry();
     if (this.isWebEnv()) {
       this.setupBrowserHistory();
-      this.parse(this.getCurrentUrl());
+      const url = this.getCurrentUrl();
+      this.buildHistoryFromUrl(url);
     } else {
       this.seedInitialHistory();
     }
-    this.recomputeVisibleRoute();
+    this.recomputeActiveRoute();
+  }
+  log(message, data) {
+    if (this.debugEnabled) {
+      if (data !== undefined) {
+        console.log(`[Router] ${message}`, data);
+      } else {
+        console.log(`[Router] ${message}`);
+      }
+    }
   }
-
-  // Public API
   navigate = path => {
     if (this.isWebEnv()) {
-      this.pushUrl(path);
+      const syncWithUrl = this.shouldSyncPathWithUrl(path);
+      this.pushUrl(path, {
+        syncWithUrl
+      });
       return;
     }
     this.performNavigation(path, 'push');
   };
   replace = (path, dedupe) => {
     if (this.isWebEnv()) {
-      this.pendingReplaceDedupe = !!dedupe;
-      this.replaceUrl(path);
+      const syncWithUrl = this.shouldSyncPathWithUrl(path);
+      this.replaceUrl(path, {
+        syncWithUrl,
+        dedupe: !!dedupe
+      });
       return;
     }
     this.performNavigation(path, 'replace', {
       dedupe: !!dedupe
     });
   };
+
+  /**
+   * Web-only convenience: resets Router navigation state to what a fresh
+   * deep-link render would produce for the given URL.
+   *
+   * This intentionally clears preserved per-tab stacks (useful when tab stacks
+   * and browser URL can get out of sync).
+   */
+  reset = path => {
+    if (this.isWebEnv()) {
+      const prevHistory = this.state.history;
+      // Important: clear current history before matching routes for the new URL.
+      // Otherwise, matchBaseRoute() tie-breakers may pick a wrong stack for ambiguous
+      // paths like '/' based on previously visited stacks, breaking tab switches.
+      this.state = {
+        history: []
+      };
+      this.stackHistories.clear();
+      // Update browser URL without triggering onHistory navigation.
+      this.replaceUrlSilently(path);
+      // Rebuild history exactly like initial URL parsing (wipes other stacks).
+      this.buildHistoryFromUrl(path, prevHistory);
+      return;
+    }
+    // Native fallback: closest semantics is a replace navigation.
+    this.performNavigation(path, 'replace', {
+      dedupe: true
+    });
+  };
   registerSheetDismisser = (key, dismisser) => {
     this.sheetDismissers.set(key, dismisser);
   };
@@ -86,52 +116,16 @@ export class Router {
   };
   goBack = () => {
     if (this.isWebEnv()) {
-      const didPop = this.tryPopActiveStack();
-      if (didPop) {
-        const path = this.getVisibleRoute()?.path;
-        if (path) this.replaceUrl(path);
+      const prevHistoryRef = this.state.history;
+      const popped = this.popFromActiveStack();
+      // Sync URL only if Router state actually changed (avoid syncing URL when
+      // a UI-level dismisser is used and the history pop will happen later).
+      if (popped && this.state.history !== prevHistoryRef) {
+        this.syncUrlAfterInternalPop(popped);
       }
       return;
     }
-    this.popOnce();
-  };
-  onTabIndexChange = index => {
-    if (this.tabBar) {
-      this.tabBar.onIndexChange(index);
-      this.setState({
-        activeTabIndex: index
-      });
-      this.emit(this.activeTabListeners);
-      this.recomputeVisibleRoute();
-      this.emit(this.listeners);
-    }
-  };
-  setActiveTabIndex = index => {
-    this.onTabIndexChange(index);
-  };
-  ensureTabSeed = index => {
-    if (!this.tabBar) return;
-    const state = this.tabBar.getState();
-    const route = state.tabs[index];
-    if (!route) return;
-    const key = route.tabKey;
-    const stack = this.tabBar.stacks[key];
-    if (!stack) return;
-    const hasAny = this.getStackHistory(stack.getId()).length > 0;
-    if (hasAny) return;
-    const first = stack.getFirstRoute();
-    if (!first) return;
-    const newItem = {
-      key: this.generateKey(),
-      scope: 'tab',
-      routeId: first.routeId,
-      component: first.component,
-      options: this.mergeOptions(first.options, stack.getId()),
-      params: {},
-      tabIndex: index,
-      stackId: stack.getId()
-    };
-    this.applyHistoryChange('push', newItem);
+    this.popFromActiveStack();
   };
   getState = () => {
     return this.state;
@@ -142,10 +136,14 @@ export class Router {
       this.listeners.delete(listener);
     };
   }
-
-  // Per-stack subscriptions
   getStackHistory = stackId => {
-    return this.stackSlices.get(stackId) ?? EMPTY_ARRAY;
+    if (!stackId) return EMPTY_ARRAY;
+    if (!this.stackHistories.has(stackId)) {
+      const current = this.state.history.filter(item => item.stackId === stackId);
+      this.stackHistories.set(stackId, current);
+      return current;
+    }
+    return this.stackHistories.get(stackId) ?? EMPTY_ARRAY;
   };
   subscribeStack = (stackId, cb) => {
     if (!stackId) return () => {};
@@ -157,23 +155,16 @@ export class Router {
     set.add(cb);
     return () => {
       set.delete(cb);
+      if (set.size === 0) {
+        this.stackListeners.delete(stackId);
+      }
     };
   };
-  getActiveTabIndex = () => {
-    return this.state.activeTabIndex ?? 0;
-  };
-  subscribeActiveTab = cb => {
-    this.activeTabListeners.add(cb);
-    return () => this.activeTabListeners.delete(cb);
-  };
   getRootStackId() {
-    return isNavigationStackLike(this.root) ? this.root.getId() : undefined;
+    return this.root?.getId();
   }
   getGlobalStackId() {
-    return this.global?.getId();
-  }
-  hasTabBar() {
-    return !!this.tabBar;
+    return undefined;
   }
   subscribeRoot(listener) {
     this.rootListeners.add(listener);
@@ -186,116 +177,130 @@ export class Router {
     return this.rootTransition;
   }
   setRoot(nextRoot, options) {
-    // Update root/tabBar references
-    this.tabBar = isTabBarLike(nextRoot) ? nextRoot : null;
     this.root = nextRoot;
-
-    // Save requested transition (stackAnimation string)
     this.rootTransition = options?.transition ?? undefined;
-
-    // If switching to TabBar, reset selected tab to the first one to avoid
-    // leaking previously selected tab across auth flow changes.
-    if (this.tabBar) {
-      this.tabBar.onIndexChange(0);
-    }
-
-    // Reset core structures (keep global reference as-is)
     this.registry.length = 0;
-    this.stackSlices.clear();
     this.stackById.clear();
     this.routeById.clear();
-
-    // Reset state (activeTabIndex from tabBar if present)
+    this.stackActivators.clear();
     this.state = {
-      history: [],
-      activeTabIndex: this.tabBar ? this.tabBar.getState().index : undefined
+      history: []
     };
-
-    // Rebuild registry and seed new root
     this.buildRegistry();
     this.seedInitialHistory();
-    this.recomputeVisibleRoute();
+    this.recomputeActiveRoute();
     this.emitRootChange();
     this.emit(this.listeners);
   }
-
-  // Visible route (global top if present, else active tab/root top)
-  getVisibleRoute = () => {
-    return this.visibleRoute;
+  getActiveRoute = () => {
+    return this.activeRoute;
   };
-  recomputeVisibleRoute() {
-    // Global top
-    if (this.global) {
-      const gid = this.global.getId();
-      const gslice = this.getStackHistory(gid);
-      const gtop = gslice.length ? gslice[gslice.length - 1] : undefined;
-      if (gtop) {
-        const meta = this.routeById.get(gtop.routeId);
-        this.visibleRoute = meta ? {
-          ...meta,
-          routeId: gtop.routeId,
-          params: gtop.params,
-          query: gtop.query,
-          path: gtop.path
-        } : {
-          routeId: gtop.routeId,
-          stackId: gtop.stackId,
-          params: gtop.params,
-          query: gtop.query,
-          scope: 'global'
+  debugGetState() {
+    return {
+      history: this.state.history.map(h => ({
+        key: h.key,
+        routeId: h.routeId,
+        stackId: h.stackId,
+        path: h.path,
+        params: h.params,
+        query: h.query,
+        stackPresentation: h.options?.stackPresentation
+      })),
+      stackSlices: Array.from(new Set(this.state.history.map(h => h.stackId).filter(Boolean))).map(stackId => ({
+        stackId,
+        items: this.getStackHistory(stackId).map(i => ({
+          key: i.key,
+          routeId: i.routeId,
+          path: i.path,
+          params: i.params,
+          query: i.query,
+          stackPresentation: i.options?.stackPresentation
+        }))
+      })),
+      activeRoute: this.activeRoute,
+      registry: this.registry.map(r => ({
+        routeId: r.routeId,
+        path: r.path,
+        pathnamePattern: r.pathnamePattern,
+        stackId: r.stackId,
+        isWildcardPath: r.isWildcardPath,
+        baseSpecificity: r.baseSpecificity,
+        queryPattern: r.queryPattern,
+        options: r.options
+      }))
+    };
+  }
+  debugMatchRoute(path) {
+    const {
+      pathname,
+      query
+    } = this.parsePath(path);
+    const matches = [];
+    for (const r of this.registry) {
+      if (!r.stackId) continue;
+      let pathMatch;
+      if (r.isWildcardPath) {
+        pathMatch = {
+          params: {}
         };
-        return;
-      }
-    }
-
-    // TabBar
-    if (this.tabBar) {
-      const idx = this.getActiveTabIndex();
-      const state = this.tabBar.getState();
-      const route = state.tabs[idx];
-      if (route) {
-        const stack = this.tabBar.stacks[route.tabKey];
-        if (stack) {
-          const sid = stack.getId();
-          const slice = this.getStackHistory(sid);
-          const top = slice.length ? slice[slice.length - 1] : undefined;
-          if (top) {
-            const meta = this.routeById.get(top.routeId);
-            this.visibleRoute = meta ? {
-              ...meta,
-              routeId: top.routeId,
-              params: top.params,
-              query: top.query,
-              path: top.path
-            } : {
-              routeId: top.routeId,
-              stackId: sid,
-              tabIndex: idx,
-              params: top.params,
-              query: top.query,
-              scope: 'tab'
-            };
-            return;
-          }
-        } else {
-          this.visibleRoute = {
-            routeId: `tab-screen-${idx}`,
-            tabIndex: idx,
-            scope: 'tab'
-          };
-          return;
-        }
+      } else {
+        pathMatch = r.matchPath(pathname);
       }
+      const queryMatch = this.matchQueryPattern(r.queryPattern, query);
+      matches.push({
+        routeId: r.routeId,
+        path: r.path,
+        pathnamePattern: r.pathnamePattern,
+        stackId: r.stackId,
+        isWildcardPath: r.isWildcardPath,
+        baseSpecificity: r.baseSpecificity,
+        pathMatch: !!pathMatch,
+        queryMatch,
+        options: r.options
+      });
     }
-
-    // Root stack
-    if (this.root && isNavigationStackLike(this.root)) {
-      const sid = this.root.getId();
-      const slice = this.getStackHistory(sid);
-      const top = slice.length ? slice[slice.length - 1] : undefined;
+    const best = this.matchBaseRoute(pathname, query);
+    return {
+      input: {
+        path,
+        pathname,
+        query
+      },
+      matches,
+      best: best ? {
+        routeId: best.routeId,
+        path: best.path,
+        stackId: best.stackId,
+        options: best.options
+      } : null
+    };
+  }
+  debugGetStackInfo(stackId) {
+    const slice = this.getStackHistory(stackId);
+    return {
+      stackId,
+      historyLength: slice.length,
+      items: slice.map(i => ({
+        key: i.key,
+        routeId: i.routeId,
+        path: i.path,
+        params: i.params,
+        query: i.query,
+        stackPresentation: i.options?.stackPresentation
+      }))
+    };
+  }
+  debugGetAllStacks() {
+    const stackIds = Array.from(new Set(this.state.history.map(h => h.stackId).filter(Boolean)));
+    return stackIds.map(stackId => this.debugGetStackInfo(stackId));
+  }
+  recomputeActiveRoute() {
+    const history = this.state.history;
+    if (history.length > 0) {
+      const top = history[history.length - 1];
       if (top) {
         const meta = this.routeById.get(top.routeId);
-        this.visibleRoute = meta ? {
+        this.activeRoute = meta ? {
           ...meta,
           routeId: top.routeId,
           params: top.params,
@@ -303,283 +308,971 @@ export class Router {
           path: top.path
         } : {
           routeId: top.routeId,
-          stackId: sid,
+          stackId: top.stackId,
           params: top.params,
           query: top.query,
-          scope: 'root'
+          path: top.path
         };
         return;
       }
     }
-    this.visibleRoute = null;
+    this.activeRoute = null;
   }
-
-  // Internal navigation logic
   performNavigation(path, action, opts) {
     const {
       pathname,
       query
     } = this.parsePath(path);
-    const matched = this.matchRoute(pathname);
-    if (!matched) {
+    const navigationToken = ++this.navigationToken;
+    this.log('performNavigation', {
+      path,
+      pathname,
+      query,
+      action,
+      dedupe: opts?.dedupe
+    });
+    const base = this.matchBaseRoute(pathname, query);
+    this.log('resolveNavigation', {
+      base: base ? {
+        routeId: base.routeId,
+        path: base.path,
+        stackId: base.stackId
+      } : null
+    });
+    if (!base) {
       if (__DEV__) {
         throw new Error(`Route not found: "${pathname}"`);
       }
       return;
     }
-    if (matched.scope === 'tab' && this.tabBar && matched.tabIndex !== undefined) {
-      this.onTabIndexChange(matched.tabIndex);
+    const activator = base.stackId ? this.stackActivators.get(base.stackId) : undefined;
+    if (activator) {
+      activator();
     }
-    const matchResult = matched.match(pathname);
+    const matchResult = base.matchPath(pathname);
     const params = matchResult ? matchResult.params : undefined;
 
-    // Prevent duplicate push when navigating to the same screen already on top of its stack
+    // Smart navigate:
+    // If navigate(push) targets the currently active routeId within the same stack, treat it as
+    // "same screen, new data" and perform a replace (preserving the existing key) by default.
+    //
+    // Consumers can opt out per-route via ScreenOptions.allowMultipleInstances=true.
+    if (action === 'push' && base.stackId) {
+      const mergedOptions = this.mergeOptions(base.options, base.stackId);
+      const allowMultipleInstances = mergedOptions?.allowMultipleInstances === true;
+      const isActiveSameStack = this.activeRoute?.stackId === base.stackId;
+      const isActiveSameRoute = this.activeRoute?.routeId === base.routeId;
+
+      // Optional safety: only apply to push-presentation screens by default.
+      const presentation = mergedOptions?.stackPresentation ?? 'push';
+      const isPushPresentation = presentation === 'push';
+      if (!allowMultipleInstances && isPushPresentation && isActiveSameStack && isActiveSameRoute) {
+        const newItem = this.createHistoryItem(base, params, query, pathname);
+        this.applyHistoryChange('replace', newItem);
+        return;
+      }
+    }
     if (action === 'push') {
-      const top = this.getTopForTarget(matched.stackId);
-      if (top && top.routeId === matched.routeId) {
-        const prev = top.params ? JSON.stringify(top.params) : '';
-        const next = params ? JSON.stringify(params) : '';
-        if (prev === next) {
+      if (base.stackId) {
+        let existing = this.findExistingRoute(base.stackId, base.routeId, pathname, params ?? {});
+        if (!existing) {
+          existing = this.findExistingRouteByPathname(base.stackId, pathname, params ?? {});
+        }
+        if (existing) {
+          this.log('push: found existing item in stack history, using popTo', {
+            key: existing.key,
+            routeId: existing.routeId,
+            path: existing.path
+          });
+          const normalizedParams = params && Object.keys(params).length > 0 ? params : undefined;
+          const updatedExisting = {
+            ...existing,
+            routeId: base.routeId,
+            params: normalizedParams,
+            query: query,
+            path: pathname,
+            component: base.component,
+            options: this.mergeOptions(base.options, base.stackId),
+            pattern: base.path
+          };
+          this.applyHistoryChange('popTo', updatedExisting);
           return;
         }
       }
     }
-
-    // Optional dedupe for replace: no-op when nothing changes at the top
     if (action === 'replace' && opts?.dedupe) {
-      const top = this.getTopForTarget(matched.stackId);
-      if (top && top.routeId === matched.routeId) {
-        const sameParams = JSON.stringify(top.params ?? {}) === JSON.stringify(params ?? {});
-        const sameQuery = JSON.stringify(top.query ?? {}) === JSON.stringify(query ?? {});
+      const top = this.getTopOfStack(base.stackId);
+      this.log('dedupe: checking top of stack', {
+        top: top ? {
+          key: top.key,
+          routeId: top.routeId,
+          path: top.path
+        } : null,
+        matched: {
+          routeId: base.routeId,
+          pathname
+        }
+      });
+      if (top && top.routeId === base.routeId) {
+        const sameParams = this.areShallowEqual(top.params ?? {}, params ?? {});
         const samePath = (top.path ?? '') === pathname;
-        if (sameParams && sameQuery && samePath) {
+        const sameIdentity = sameParams && samePath;
+        const sameQuery = this.areShallowEqual(top.query ?? {}, query ?? {});
+        this.log('dedupe: top matches routeId, checking identity (params+path) and query', {
+          sameParams,
+          samePath,
+          sameIdentity,
+          sameQuery
+        });
+        if (sameIdentity && sameQuery) {
+          this.log('dedupe: already at target, syncing state');
+          this.syncStateForSameRoute(base, pathname, params, query);
+          return;
+        }
+        if (sameIdentity && !sameQuery) {
+          this.log('dedupe: same identity, updating query on top via replace');
+          const normalizedParams = params && Object.keys(params).length > 0 ? params : undefined;
+          const updatedTop = {
+            ...top,
+            params: normalizedParams,
+            query: query,
+            path: pathname
+          };
+          this.applyHistoryChange('replace', updatedTop);
+          return;
+        }
+      }
+      if (base.stackId) {
+        const existing = this.findExistingRoute(base.stackId, base.routeId, pathname, params ?? {});
+        if (existing) {
+          const normalizedParams = params && Object.keys(params).length > 0 ? params : undefined;
+          const updatedExisting = {
+            ...existing,
+            params: normalizedParams,
+            query: query,
+            path: pathname
+          };
+          this.log('dedupe: found existing item, calling popTo', {
+            key: updatedExisting.key
+          });
+          this.applyHistoryChange('popTo', updatedExisting);
           return;
         }
       }
     }
-
-    // If there's a controller, execute it first
-    if (matched.controller) {
+    if (base.controller) {
       const controllerInput = {
         params,
         query
       };
+      let didPresent = false;
       const present = passProps => {
-        const newItem = this.createHistoryItem(matched, params, query, pathname, passProps);
+        if (didPresent) return;
+        didPresent = true;
+        if (navigationToken !== this.navigationToken) {
+          this.log('controller: present ignored (stale navigation)', {
+            navigationToken,
+            current: this.navigationToken
+          });
+          return;
+        }
+        const newItem = this.createHistoryItem(base, params, query, pathname, passProps);
         this.applyHistoryChange(action, newItem);
       };
-      matched.controller(controllerInput, present);
+      base.controller(controllerInput, present);
       return;
     }
-    const newItem = this.createHistoryItem(matched, params, query, pathname);
+    const newItem = this.createHistoryItem(base, params, query, pathname);
     this.applyHistoryChange(action, newItem);
   }
   createHistoryItem(matched, params, query, pathname, passProps) {
+    const normalizedParams = params && Object.keys(params).length > 0 ? params : undefined;
     return {
       key: this.generateKey(),
-      scope: matched.scope,
       routeId: matched.routeId,
       component: matched.component,
       options: this.mergeOptions(matched.options, matched.stackId),
-      params,
+      params: normalizedParams,
       query: query,
       passProps,
-      tabIndex: matched.tabIndex,
       stackId: matched.stackId,
       pattern: matched.path,
       path: pathname
     };
   }
-
-  // Internal helpers
+  applyHistoryChange(action, item) {
+    const stackId = item.stackId;
+    if (!stackId) return;
+    const prevHist = this.state.history;
+    let nextHist = prevHist;
+    this.log('applyHistoryChange', {
+      action,
+      stackId,
+      item: {
+        key: item.key,
+        routeId: item.routeId,
+        path: item.path
+      }
+    });
+    if (action === 'push') {
+      nextHist = [...prevHist, item];
+    } else if (action === 'replace') {
+      let replaced = false;
+      const copy = [...prevHist];
+      for (let i = copy.length - 1; i >= 0; i--) {
+        const h = copy[i];
+        if (h) {
+          if (h.stackId === stackId) {
+            copy[i] = {
+              ...item,
+              key: h.key
+            };
+            replaced = true;
+            break;
+          }
+        }
+      }
+      if (!replaced) {
+        copy.push(item);
+      }
+      nextHist = copy;
+    } else if (action === 'pop') {
+      const copy = [...prevHist];
+      for (let i = copy.length - 1; i >= 0; i--) {
+        const h = copy[i];
+        if (h.stackId === stackId) {
+          copy.splice(i, 1);
+          break;
+        }
+      }
+      nextHist = copy;
+    } else if (action === 'popTo') {
+      const targetKey = item.key;
+      const keysToRemove = new Set();
+      let foundIndex = -1;
+      let foundItem = null;
+      for (let i = prevHist.length - 1; i >= 0; i--) {
+        const h = prevHist[i];
+        if (h.stackId !== stackId) {
+          continue;
+        }
+        if (h.key === targetKey) {
+          foundIndex = i;
+          foundItem = h;
+          break;
+        }
+        keysToRemove.add(h.key);
+      }
+      if (foundIndex === -1 || !foundItem) {
+        return;
+      }
+      const copy = prevHist.filter(h => !keysToRemove.has(h.key));
+      const updatedItem = {
+        ...foundItem,
+        ...item,
+        key: targetKey
+      };
+      const itemIndex = copy.findIndex(h => h.key === targetKey);
+      if (itemIndex >= 0) {
+        copy.splice(itemIndex, 1);
+      }
+      copy.push(updatedItem);
+      nextHist = copy;
+    }
+    this.setState({
+      history: nextHist
+    });
+    this.recomputeActiveRoute();
+    this.emit(this.listeners);
+  }
+  setState(next) {
+    const prev = this.state;
+    const nextState = {
+      history: next.history ?? prev.history
+    };
+    this.state = nextState;
+    if (nextState.history !== prev.history) {
+      this.updateStackHistories();
+    }
+    this.log('setState', nextState);
+  }
+  updateStackHistories() {
+    const stackIds = new Set();
+    this.state.history.forEach(item => {
+      if (item.stackId) stackIds.add(item.stackId);
+    });
+    const changedStackIds = new Set();
+    stackIds.forEach(stackId => {
+      const current = this.state.history.filter(item => item.stackId === stackId);
+      const previous = this.stackHistories.get(stackId);
+      if (previous && this.areArraysEqual(previous, current)) {
+        return;
+      }
+      this.stackHistories.set(stackId, current);
+      changedStackIds.add(stackId);
+    });
+    const currentStackIds = new Set(stackIds);
+    this.stackHistories.forEach((history, stackId) => {
+      if (!currentStackIds.has(stackId) && history.length > 0) {
+        this.stackHistories.delete(stackId);
+        changedStackIds.add(stackId);
+      } else if (!currentStackIds.has(stackId) && history.length === 0) {}
+    });
+    changedStackIds.forEach(stackId => {
+      this.emit(this.stackListeners.get(stackId));
+    });
+  }
+  areArraysEqual(a, b) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (a[i] !== b[i]) return false;
+    }
+    return true;
+  }
+  syncStateForSameRoute(base, pathname, _params, _query) {
+    if (!base.stackId) {
+      this.recomputeActiveRoute();
+      this.emit(this.listeners);
+      return;
+    }
+    const {
+      targetStackId,
+      targetRouteId
+    } = this.resolveTargetStackAndRoute(base, pathname);
+    const rootStackId = this.root?.getId();
+    if (rootStackId) {
+      this.activateContainerForRoute(targetRouteId, rootStackId);
+    }
+    this.activateStack(targetStackId);
+    this.ensureStackHasSeed(targetStackId, rootStackId ?? base.stackId);
+    this.updateActiveRouteFromStack(targetStackId, pathname);
+    this.emit(this.listeners);
+  }
+  resolveTargetStackAndRoute(base, pathname) {
+    const rootStackId = this.root?.getId();
+    let targetStackId = base.stackId;
+    let targetRouteId = base.routeId;
+    const currentActivePath = this.activeRoute?.path;
+    const currentActivePathname = currentActivePath ? this.parsePath(currentActivePath).pathname : '';
+    if (base.stackId === rootStackId && pathname === '/' && currentActivePathname !== '/') {
+      const childStackRoute = this.findChildStackRouteForPathname(rootStackId, pathname);
+      if (childStackRoute) {
+        targetStackId = childStackRoute.stackId;
+        targetRouteId = childStackRoute.routeId;
+      }
+    }
+    return {
+      targetStackId,
+      targetRouteId
+    };
+  }
+  findChildStackRouteForPathname(rootStackId, pathname) {
+    for (const route of this.registry) {
+      if (route.stackId !== rootStackId && route.pathnamePattern === pathname && !route.queryPattern) {
+        const rootRoute = this.findRootRouteWithContainer(rootStackId);
+        if (rootRoute?.childNode && this.isRouteInContainer(route.routeId, rootRoute.childNode)) {
+          return route;
+        }
+      }
+    }
+    return undefined;
+  }
+  findRootRouteWithContainer(rootStackId) {
+    return this.registry.find(r => r.stackId === rootStackId && r.childNode && canSwitchToRoute(r.childNode));
+  }
+  isRouteInContainer(routeId, container) {
+    if (canLookupRoutes(container) && container.hasRoute(routeId)) {
+      return true;
+    }
+    const visit = node => {
+      const routes = node.getNodeRoutes();
+      for (const r of routes) {
+        if (r.routeId === routeId) return true;
+        if (r.childNode && visit(r.childNode)) return true;
+      }
+      const children = node.getNodeChildren();
+      for (const child of children) {
+        if (visit(child.node)) return true;
+      }
+      return false;
+    };
+    return visit(container);
+  }
+  activateContainerForRoute(targetRouteId, rootStackId) {
+    const container = this.findContainerInStack(rootStackId);
+    if (container && canSwitchToRoute(container)) {
+      container.switchToRoute(targetRouteId);
+    }
+  }
+  findContainerInStack(stackId) {
+    const stackHistory = this.getStackHistory(stackId);
+    for (let i = stackHistory.length - 1; i >= 0; i--) {
+      const item = stackHistory[i];
+      if (item) {
+        const compiled = this.registry.find(r => r.routeId === item.routeId);
+        if (compiled?.childNode && canSwitchToRoute(compiled.childNode)) {
+          return compiled.childNode;
+        }
+      }
+    }
+    const rootRoute = this.findRootRouteWithContainer(stackId);
+    return rootRoute?.childNode;
+  }
+  activateStack(stackId) {
+    const activator = this.stackActivators.get(stackId);
+    if (activator) {
+      activator();
+    }
+  }
+  ensureStackHasSeed(stackId, rootStackId) {
+    const stackHistory = this.getStackHistory(stackId);
+    if (stackHistory.length > 0) return;
+    const stackNode = this.stackById.get(stackId);
+    if (!stackNode) return;
+    const seed = this.getAutoSeed(stackNode);
+    if (!seed) return;
+    const compiled = this.registry.find(r => r.routeId === seed.routeId);
+    const meta = this.routeById.get(seed.routeId);
+    const path = compiled?.path ?? meta?.path ?? seed.path;
+    const seedStackId = seed.stackId ?? stackNode.getId();
+    const item = {
+      key: this.generateKey(),
+      routeId: seed.routeId,
+      component: compiled?.component ?? (() => null),
+      options: this.mergeOptions(compiled?.options, seedStackId),
+      params: seed.params ?? {},
+      stackId: seedStackId,
+      path,
+      pattern: compiled?.path ?? seed.path
+    };
+    const prevHist = this.state.history;
+    const nextHist = [...prevHist, item];
+    this.setState({
+      history: nextHist
+    });
+    this.emit(this.stackListeners.get(seedStackId));
+    if (seedStackId !== stackId && rootStackId) {
+      this.activateContainerForRoute(seed.routeId, rootStackId);
+    }
+  }
+  updateActiveRouteFromStack(stackId, pathname) {
+    const stackHistory = this.getStackHistory(stackId);
+    if (stackHistory.length > 0) {
+      const topOfStack = stackHistory[stackHistory.length - 1];
+      if (topOfStack) {
+        const meta = this.routeById.get(topOfStack.routeId);
+        this.activeRoute = meta ? {
+          ...meta,
+          routeId: topOfStack.routeId,
+          params: topOfStack.params,
+          query: topOfStack.query,
+          path: topOfStack.path
+        } : {
+          routeId: topOfStack.routeId,
+          stackId: topOfStack.stackId,
+          params: topOfStack.params,
+          query: topOfStack.query,
+          path: topOfStack.path
+        };
+        return;
+      }
+    }
+    const targetRoute = this.registry.find(r => r.stackId === stackId && r.pathnamePattern === pathname);
+    if (targetRoute) {
+      const meta = this.routeById.get(targetRoute.routeId);
+      this.activeRoute = meta ? {
+        ...meta,
+        routeId: targetRoute.routeId,
+        params: {},
+        query: {},
+        path: targetRoute.path
+      } : {
+        routeId: targetRoute.routeId,
+        stackId: stackId,
+        params: {},
+        query: {},
+        path: targetRoute.path
+      };
+    }
+  }
+  emit(set) {
+    if (!set) return;
+    // Do not allow one listener to break all others.
+    for (const l of Array.from(set)) {
+      try {
+        l();
+      } catch (e) {
+        if (this.debugEnabled) {
+          console.error('[Router] listener error', e);
+        }
+      }
+    }
+  }
+  getTopOfStack(stackId) {
+    if (!stackId) return undefined;
+    const slice = this.getStackHistory(stackId);
+    return slice.length > 0 ? slice[slice.length - 1] : undefined;
+  }
+  findExistingRoute(stackId, routeId, pathname, params) {
+    const stackHistory = this.getStackHistory(stackId);
+    return stackHistory.find(item => {
+      if (item.routeId !== routeId) return false;
+      const itemPathname = item.path ? this.parsePath(item.path).pathname : '';
+      if (itemPathname !== pathname) return false;
+      return this.areShallowEqual(item.params ?? {}, params);
+    });
+  }
+  findExistingRouteByPathname(stackId, pathname, params) {
+    const stackHistory = this.getStackHistory(stackId);
+    return stackHistory.find(item => {
+      const itemPathname = item.path ? this.parsePath(item.path).pathname : '';
+      if (itemPathname !== pathname) return false;
+      return this.areShallowEqual(item.params ?? {}, params);
+    });
+  }
   buildRegistry() {
     this.registry.length = 0;
-    const addFromStack = (stack, scope, extras) => {
-      const stackId = stack.getId();
-      this.stackById.set(stackId, stack);
-      for (const r of stack.getRoutes()) {
-        this.registry.push({
+    const addFromNode = (node, basePath) => {
+      const normalizedBasePath = this.normalizeBasePath(basePath);
+      const baseSpecificity = this.computeBasePathSpecificity(normalizedBasePath);
+      const routes = node.getNodeRoutes();
+      const stackId = routes.length > 0 ? node.getId() : undefined;
+      if (stackId) {
+        this.stackById.set(stackId, node);
+      }
+      for (const r of routes) {
+        const compiled = {
           routeId: r.routeId,
-          scope,
-          path: r.path,
-          match: r.match,
+          path: this.combinePathWithBase(r.path, normalizedBasePath),
+          pathnamePattern: r.pathnamePattern === '*' ? '*' : this.joinPaths(normalizedBasePath, r.pathnamePattern),
+          isWildcardPath: r.isWildcardPath,
+          queryPattern: r.queryPattern,
+          baseSpecificity: r.baseSpecificity + baseSpecificity,
+          matchPath: pathname => {
+            const stripped = this.stripBasePath(normalizedBasePath, pathname);
+            if (stripped === null) return false;
+            if (r.isWildcardPath) {
+              return {
+                params: {}
+              };
+            }
+            const target = stripped === '' ? '/' : stripped;
+            return r.matchPath(target);
+          },
           component: r.component,
           controller: r.controller,
           options: r.options,
-          tabIndex: extras.tabIndex,
-          stackId
-        });
-        this.routeById.set(r.routeId, {
-          path: r.path,
           stackId,
-          tabIndex: extras.tabIndex,
-          scope
+          childNode: r.childNode
+        };
+        this.registry.push(compiled);
+        if (stackId) {
+          this.routeById.set(r.routeId, {
+            path: compiled.path,
+            stackId
+          });
+        }
+        this.log('buildRegistry route', {
+          routeId: compiled.routeId,
+          path: compiled.path,
+          pathnamePattern: compiled.pathnamePattern,
+          isWildcardPath: compiled.isWildcardPath,
+          baseSpecificity: compiled.baseSpecificity,
+          stackId
         });
+        if (r.childNode) {
+          const nextBaseForChild = r.isWildcardPath ? normalizedBasePath : this.joinPaths(normalizedBasePath, r.pathnamePattern);
+          addFromNode(r.childNode, nextBaseForChild);
+        }
       }
-      // init empty slice
-      if (!this.stackSlices.has(stackId)) this.stackSlices.set(stackId, EMPTY_ARRAY);
-    };
-    if (isNavigationStackLike(this.root)) {
-      addFromStack(this.root, 'root', {});
-    } else if (this.tabBar) {
-      const state = this.tabBar.getState();
-      state.tabs.forEach((tab, idx) => {
-        const stack = this.tabBar.stacks[tab.tabKey];
-        if (stack) {
-          addFromStack(stack, 'tab', {
-            tabIndex: idx
-          });
+      const children = node.getNodeChildren();
+      for (const child of children) {
+        const nextBase = child.prefix === '' ? normalizedBasePath : this.joinPaths(normalizedBasePath, child.prefix);
+        const childId = child.node.getId();
+        if (child.onMatch) {
+          this.stackActivators.set(childId, child.onMatch);
         }
-      });
+        addFromNode(child.node, nextBase);
+      }
+    };
+    if (this.root) {
+      addFromNode(this.root, '');
+    }
+  }
+  normalizeBasePath(input) {
+    if (!input || input === '/') {
+      return '';
     }
-    if (this.global) {
-      addFromStack(this.global, 'global', {});
+    let normalized = input.startsWith('/') ? input : `/${input}`;
+    if (normalized.length > 1 && normalized.endsWith('/')) {
+      normalized = normalized.slice(0, -1);
     }
+    return normalized;
   }
-  seedInitialHistory() {
-    if (this.state.history.length > 0) return;
-    if (this.tabBar) {
-      const state = this.tabBar.getState();
-      const activeIdx = state.index ?? 0;
-      const route = state.tabs[activeIdx];
-      if (!route) return;
-      const stack = this.tabBar.stacks[route.tabKey];
-      if (stack) {
-        const first = stack.getFirstRoute();
-        if (first) {
-          const newItem = {
-            key: this.generateKey(),
-            scope: 'tab',
-            routeId: first.routeId,
-            component: first.component,
-            options: this.mergeOptions(first.options, stack.getId()),
-            params: {},
-            tabIndex: activeIdx,
-            stackId: stack.getId()
-          };
-          this.applyHistoryChange('push', newItem);
+  joinPaths(basePath, childPath) {
+    if (childPath === '*') return '*';
+    const base = this.normalizeBasePath(basePath);
+    const child = this.normalizeBasePath(childPath || '/');
+    if (!base && !child) return '/';
+    if (!base) return child || '/';
+    if (!child) return base || '/';
+    const joined = `${base}${child.startsWith('/') ? child : `/${child}`}`;
+    return joined || '/';
+  }
+  stripBasePath(basePath, pathname) {
+    const normalizedBase = this.normalizeBasePath(basePath);
+    if (!normalizedBase) {
+      return pathname || '/';
+    }
+    if (normalizedBase === '/') {
+      return pathname || '/';
+    }
+    if (pathname === normalizedBase) {
+      return '/';
+    }
+    if (pathname.startsWith(`${normalizedBase}/`)) {
+      const rest = pathname.slice(normalizedBase.length);
+      return rest.length ? rest : '/';
+    }
+    return null;
+  }
+  combinePathWithBase(path, basePath) {
+    const parsed = qs.parseUrl(path);
+    const urlPart = parsed.url || '/';
+    const query = parsed.query;
+    const isWildcard = urlPart === '*';
+    const combinedPathname = isWildcard ? `${this.normalizeBasePath(basePath)}*` : this.joinPaths(basePath, urlPart);
+    const hasQuery = query && Object.keys(query).length > 0;
+    if (!hasQuery) {
+      return combinedPathname || '/';
+    }
+    return `${combinedPathname}?${qs.stringify(query)}`;
+  }
+  computeBasePathSpecificity(basePath) {
+    if (!basePath) return 0;
+    const segments = basePath.split('/').filter(Boolean);
+    return segments.length * 2;
+  }
+  getAutoSeed(node) {
+    const explicitSeed = node.seed?.();
+    if (explicitSeed) {
+      return explicitSeed;
+    }
+    const activeChildId = node.getActiveChildId?.();
+    if (activeChildId) {
+      const activeChild = node.getNodeChildren().find(child => child.node.getId() === activeChildId);
+      if (activeChild) {
+        const childSeed = this.getAutoSeed(activeChild.node);
+        if (childSeed) {
+          return childSeed;
         }
       }
-      return;
     }
-    if (isNavigationStackLike(this.root)) {
-      const first = this.root.getFirstRoute();
-      if (first) {
-        const newItem = {
+    const routes = node.getNodeRoutes();
+    if (routes.length > 0 && routes[0]) {
+      const firstRoute = routes[0];
+      return {
+        routeId: firstRoute.routeId,
+        params: {},
+        path: firstRoute.path,
+        stackId: node.getId()
+      };
+    }
+    return null;
+  }
+  seedInitialHistory() {
+    if (this.state.history.length > 0) return;
+    if (this.root) {
+      const seed = this.getAutoSeed(this.root);
+      if (seed) {
+        const compiled = this.registry.find(r => r.routeId === seed.routeId);
+        const meta = this.routeById.get(seed.routeId);
+        const path = compiled?.path ?? meta?.path ?? seed.path;
+        const stackId = seed.stackId ?? this.root.getId();
+        const item = {
           key: this.generateKey(),
-          scope: 'root',
-          routeId: first.routeId,
-          component: first.component,
-          options: this.mergeOptions(first.options, this.root.getId()),
-          params: {},
-          stackId: this.root.getId()
+          routeId: seed.routeId,
+          component: compiled?.component ?? (() => null),
+          options: this.mergeOptions(compiled?.options, stackId),
+          params: seed.params ?? {},
+          stackId,
+          path,
+          pattern: compiled?.path ?? seed.path
         };
-        this.applyHistoryChange('push', newItem);
+        this.applyHistoryChange('push', item);
+        this.addChildNodeSeedsToHistory(seed.routeId);
       }
+      return;
     }
   }
-  matchRoute(path) {
-    for (const r of this.registry) {
-      if (r.match(path)) return r;
+  addChildNodeSeedsToItems(routeId, items, finalRouteId) {
+    this.log('addChildNodeSeeds: called', {
+      routeId,
+      finalRouteId,
+      itemsLength: items.length,
+      items: items.map(i => ({
+        routeId: i.routeId,
+        stackId: i.stackId,
+        path: i.path
+      }))
+    });
+    const compiled = this.registry.find(r => r.routeId === routeId);
+    if (!compiled || !compiled.childNode) {
+      this.log('addChildNodeSeeds: no childNode', {
+        routeId
+      });
+      return;
+    }
+    const childNode = compiled.childNode;
+    if (finalRouteId && canSwitchToRoute(childNode)) {
+      this.log('addChildNodeSeeds: setting active child', {
+        finalRouteId
+      });
+      childNode.switchToRoute(finalRouteId);
+    }
+    const childSeed = this.getAutoSeed(childNode);
+    if (!childSeed) {
+      this.log('addChildNodeSeeds: no seed returned', {
+        routeId
+      });
+      return;
+    }
+    this.log('addChildNodeSeeds: got seed', {
+      routeId: childSeed.routeId,
+      stackId: childSeed.stackId,
+      path: childSeed.path
+    });
+    const childCompiled = this.registry.find(r => r.routeId === childSeed.routeId);
+    const childMeta = this.routeById.get(childSeed.routeId);
+    const childPath = childCompiled?.path ?? childMeta?.path ?? childSeed.path;
+    const childStackId = childSeed.stackId ?? childNode.getId();
+    const existingItem = items.find(item => item.routeId === childSeed.routeId && item.stackId === childStackId);
+    if (existingItem) {
+      this.log('addChildNodeSeeds: skipping duplicate', {
+        routeId: childSeed.routeId,
+        stackId: childStackId,
+        path: childPath,
+        existingItem: {
+          key: existingItem.key,
+          routeId: existingItem.routeId,
+          stackId: existingItem.stackId,
+          path: existingItem.path
+        }
+      });
+      return;
+    }
+    this.log('addChildNodeSeeds: adding child item', {
+      routeId: childSeed.routeId,
+      stackId: childStackId,
+      path: childPath,
+      itemsLength: items.length
+    });
+    const childItem = {
+      key: this.generateKey(),
+      routeId: childSeed.routeId,
+      component: childCompiled?.component ?? (() => null),
+      options: this.mergeOptions(childCompiled?.options, childStackId),
+      params: childSeed.params ?? {},
+      stackId: childStackId,
+      path: childPath,
+      pattern: childCompiled?.path ?? childSeed.path
+    };
+    // Insert right after the parent route item, so that child stack seeds do not
+    // accidentally become the active route for deep-links (order matters).
+    let parentIndex = -1;
+    for (let i = items.length - 1; i >= 0; i--) {
+      const it = items[i];
+      if (it && it.routeId === routeId) {
+        parentIndex = i;
+        break;
+      }
+    }
+    const insertIndex = parentIndex >= 0 ? parentIndex + 1 : items.length;
+    items.splice(insertIndex, 0, childItem);
+    if (childSeed.routeId) {
+      this.addChildNodeSeedsToItems(childSeed.routeId, items, finalRouteId);
     }
-    return undefined;
-  }
-  generateKey() {
-    return `route-${nanoid()}`;
   }
-  parsePath(path) {
-    const parsed = qs.parseUrl(path);
-    return {
-      pathname: parsed.url,
-      query: parsed.query
+  addChildNodeSeedsToHistory(routeId) {
+    const compiled = this.registry.find(r => r.routeId === routeId);
+    if (!compiled || !compiled.childNode) return;
+    const childNode = compiled.childNode;
+    const childSeed = this.getAutoSeed(childNode);
+    if (!childSeed) return;
+    const childCompiled = this.registry.find(r => r.routeId === childSeed.routeId);
+    const childMeta = this.routeById.get(childSeed.routeId);
+    const childPath = childCompiled?.path ?? childMeta?.path ?? childSeed.path;
+    const childStackId = childSeed.stackId ?? childNode.getId();
+    const childItem = {
+      key: this.generateKey(),
+      routeId: childSeed.routeId,
+      component: childCompiled?.component ?? (() => null),
+      options: this.mergeOptions(childCompiled?.options, childStackId),
+      params: childSeed.params ?? {},
+      stackId: childStackId,
+      path: childPath,
+      pattern: childCompiled?.path ?? childSeed.path
     };
+    this.applyHistoryChange('push', childItem);
+    if (childSeed.routeId) {
+      this.addChildNodeSeedsToHistory(childSeed.routeId);
+    }
   }
-  applyHistoryChange(action, item) {
-    const sid = item.stackId;
-    if (action === 'push') {
-      this.setState({
-        history: [...this.state.history, item]
+  matchBaseRoute(pathname, query) {
+    this.log('matchBaseRoute', {
+      pathname,
+      query
+    });
+    let best;
+    const candidates = [];
+    for (const r of this.registry) {
+      if (!r.stackId) continue;
+      let pathMatch;
+      if (r.isWildcardPath) {
+        pathMatch = {
+          params: {}
+        };
+      } else {
+        pathMatch = r.matchPath(pathname);
+      }
+      if (!pathMatch) continue;
+      if (!this.matchQueryPattern(r.queryPattern, query)) continue;
+      let spec = r.baseSpecificity;
+      const hasQueryPattern = r.queryPattern && Object.keys(r.queryPattern).length > 0;
+      if (hasQueryPattern) {
+        spec += 1000;
+      }
+      this.log('matchBaseRoute candidate', {
+        routeId: r.routeId,
+        path: r.path,
+        baseSpecificity: r.baseSpecificity,
+        adjustedSpecificity: spec,
+        hasQueryPattern,
+        stackId: r.stackId
       });
-      const prevSlice = this.stackSlices.get(sid) ?? EMPTY_ARRAY;
-      const nextSlice = [...prevSlice, item];
-      this.stackSlices.set(sid, nextSlice);
-      this.emit(this.stackListeners.get(sid));
-      this.recomputeVisibleRoute();
-      this.emit(this.listeners);
-    } else if (action === 'replace') {
-      const prevTop = this.state.history[this.state.history.length - 1];
-      const prevSid = prevTop?.stackId;
-      this.setState({
-        history: [...this.state.history.slice(0, -1), item]
+      if (!best || spec > best.specificity) {
+        best = {
+          route: r,
+          specificity: spec
+        };
+        candidates.length = 0;
+        candidates.push(best);
+      } else if (spec === best.specificity) {
+        candidates.push({
+          route: r,
+          specificity: spec
+        });
+      }
+    }
+    if (candidates.length > 1) {
+      this.log('matchBaseRoute: multiple candidates with same specificity', {
+        candidatesCount: candidates.length,
+        candidates: candidates.map(c => ({
+          routeId: c.route.routeId,
+          stackId: c.route.stackId,
+          path: c.route.path
+        }))
       });
-      if (prevSid && prevSid !== sid) {
-        // Cross-stack replace: do not modify the source stack.
-        // Update target stack without growing it unnecessarily.
-        const targetSlice = this.stackSlices.get(sid) ?? EMPTY_ARRAY;
-        if (targetSlice.length === 0) {
-          this.stackSlices.set(sid, [item]);
-        } else {
-          const targetTop = targetSlice[targetSlice.length - 1];
-          const sameRoute = targetTop?.routeId === item.routeId;
-          const sameParams = JSON.stringify(targetTop?.params ?? {}) === JSON.stringify(item.params ?? {});
-          if (sameRoute && sameParams) {
-            // No change needed for target stack
-            this.stackSlices.set(sid, targetSlice);
-          } else {
-            // Replace top of target stack
-            const replaced = [...targetSlice.slice(0, -1), item];
-            this.stackSlices.set(sid, replaced);
+      const rootStackId = this.root?.getId();
+      let bestFromHistory;
+      let bestChildStack;
+      let bestChildStackWithHistory;
+      for (const candidate of candidates) {
+        const candidateStackId = candidate.route.stackId;
+        const stackHistory = this.getStackHistory(candidateStackId);
+        const hasMatchingItem = stackHistory.some(item => {
+          const itemPathname = item.path ? this.parsePath(item.path).pathname : '';
+          return itemPathname === pathname;
+        });
+        this.log('matchBaseRoute: checking candidate', {
+          routeId: candidate.route.routeId,
+          stackId: candidateStackId,
+          isRootStack: candidateStackId === rootStackId,
+          stackHistoryLength: stackHistory.length,
+          hasMatchingItem
+        });
+        if (hasMatchingItem) {
+          if (candidateStackId !== rootStackId) {
+            bestChildStack = candidate.route;
+            this.log('matchBaseRoute: found child stack candidate with matching item', {
+              routeId: candidate.route.routeId,
+              stackId: candidateStackId
+            });
+            break;
+          } else if (!bestFromHistory) {
+            bestFromHistory = candidate.route;
+          }
+        } else if (candidateStackId !== rootStackId && stackHistory.length > 0) {
+          if (!bestChildStackWithHistory) {
+            bestChildStackWithHistory = candidate.route;
+            this.log('matchBaseRoute: found child stack candidate with history', {
+              routeId: candidate.route.routeId,
+              stackId: candidateStackId,
+              stackHistoryLength: stackHistory.length
+            });
           }
         }
-        this.emit(this.stackListeners.get(sid));
-      } else {
-        // Same-stack replace: replace top element
-        const prevSlice = this.stackSlices.get(sid) ?? EMPTY_ARRAY;
-        const nextSlice = prevSlice.length ? [...prevSlice.slice(0, -1), item] : [item];
-        this.stackSlices.set(sid, nextSlice);
-        this.emit(this.stackListeners.get(sid));
       }
-      this.recomputeVisibleRoute();
-      this.emit(this.listeners);
-    } else if (action === 'pop') {
-      // Remove specific item by key from global history
-      const nextHist = this.state.history.filter(h => h.key !== item.key);
-      this.setState({
-        history: nextHist
+      if (bestChildStack && best) {
+        best = {
+          route: bestChildStack,
+          specificity: best.specificity
+        };
+        this.log('matchBaseRoute: selected child stack with matching item', {
+          routeId: bestChildStack.routeId,
+          stackId: bestChildStack.stackId
+        });
+      } else if (bestChildStackWithHistory && best) {
+        best = {
+          route: bestChildStackWithHistory,
+          specificity: best.specificity
+        };
+        this.log('matchBaseRoute: selected child stack', {
+          routeId: bestChildStackWithHistory.routeId,
+          stackId: bestChildStackWithHistory.stackId
+        });
+      } else if (bestFromHistory && best) {
+        best = {
+          route: bestFromHistory,
+          specificity: best.specificity
+        };
+        this.log('matchBaseRoute: selected root stack with history', {
+          routeId: bestFromHistory.routeId,
+          stackId: bestFromHistory.stackId
+        });
+      }
+    }
+    if (best) {
+      this.log('matchBaseRoute winner', {
+        routeId: best.route.routeId,
+        path: best.route.path,
+        stackId: best.route.stackId,
+        specificity: best.specificity,
+        candidatesCount: candidates.length
       });
-
-      // Update slice only if the last item matches the popped one
-      const prevSlice = this.stackSlices.get(sid) ?? EMPTY_ARRAY;
-      const last = prevSlice.length ? prevSlice[prevSlice.length - 1] : undefined;
-      if (last && last.key === item.key) {
-        const nextSlice = prevSlice.slice(0, -1);
-        this.stackSlices.set(sid, nextSlice);
-        this.emit(this.stackListeners.get(sid));
-      }
-      this.recomputeVisibleRoute();
-      this.emit(this.listeners);
+    } else {
+      this.log('matchBaseRoute no match');
     }
+    return best?.route;
   }
-  setState(next) {
-    const prev = this.state;
-    const nextState = {
-      history: next.history ?? prev.history,
-      activeTabIndex: next.activeTabIndex ?? prev.activeTabIndex
-    };
-    this.state = nextState;
-    // Callers will emit updates explicitly.
-  }
-  emit(set) {
-    if (!set) return;
-    set.forEach(l => l());
+  generateKey() {
+    return `route-${nanoid()}`;
   }
-  getTopForTarget(stackId) {
-    if (!stackId) return undefined;
-    const slice = this.stackSlices.get(stackId) ?? EMPTY_ARRAY;
-    return slice.length ? slice[slice.length - 1] : undefined;
+  parsePath(path) {
+    const parsed = qs.parseUrl(path);
+    const result = {
+      pathname: parsed.url,
+      query: parsed.query
+    };
+    this.log('parsePath', {
+      input: path,
+      output: result
+    });
+    return result;
   }
   mergeOptions(routeOptions, stackId) {
-    const stackDefaults = stackId ? this.findStackById(stackId)?.getDefaultOptions() : undefined;
+    const stackNode = stackId ? this.findStackById(stackId) : undefined;
+    const stackDefaults = stackNode?.getDefaultOptions?.();
     const routerDefaults = this.routerScreenOptions;
     if (!routerDefaults && !stackDefaults && !routeOptions) return undefined;
     const merged = {
@@ -595,8 +1288,76 @@ export class Router {
   findStackById(stackId) {
     return this.stackById.get(stackId);
   }
-
-  // ==== Web integration (History API) ====
+  areShallowEqual(a, b) {
+    if (a === b) return true;
+    if (!a || !b) return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) return false;
+    for (const k of aKeys) {
+      if (!(k in b)) return false;
+      const av = a[k];
+      const bv = b[k];
+      if (av === bv) continue;
+      const aArr = Array.isArray(av);
+      const bArr = Array.isArray(bv);
+      if (aArr || bArr) {
+        if (!aArr || !bArr) return false;
+        if (av.length !== bv.length) return false;
+        for (let i = 0; i < av.length; i++) {
+          if (av[i] !== bv[i]) return false;
+        }
+        continue;
+      }
+      return false;
+    }
+    return true;
+  }
+  matchQueryPattern(pattern, query) {
+    if (!pattern) {
+      return true;
+    }
+    for (const [key, token] of Object.entries(pattern)) {
+      const raw = query[key];
+      if (raw == null) {
+        this.log('matchQueryPattern: key missing', {
+          key,
+          token,
+          query
+        });
+        return false;
+      }
+      if (typeof raw !== 'string') {
+        this.log('matchQueryPattern: non-string value', {
+          key,
+          token,
+          value: raw
+        });
+        return false;
+      }
+      if (token.type === 'const') {
+        if (raw !== token.value) {
+          this.log('matchQueryPattern: const mismatch', {
+            key,
+            expected: token.value,
+            actual: raw
+          });
+          return false;
+        }
+      } else if (token.type === 'param') {
+        this.log('matchQueryPattern: param ok', {
+          key,
+          value: raw,
+          paramName: token.name
+        });
+      }
+    }
+    this.log('matchQueryPattern: success', {
+      pattern,
+      query
+    });
+    return true;
+  }
   isWebEnv() {
     const g = globalThis;
     return !!(g.addEventListener && g.history && g.location);
@@ -605,54 +1366,135 @@ export class Router {
     const g = globalThis;
     return g.location ? `${g.location.pathname}${g.location.search}` : '/';
   }
-  readIndex(state) {
+  readHistoryIndex(state) {
     if (state && typeof state === 'object' && '__srIndex' in state) {
       const idx = state.__srIndex;
       if (typeof idx === 'number') return idx;
     }
     return 0;
   }
+  getHistoryIndexOrNull() {
+    const g = globalThis;
+    const st = g.history?.state;
+    if (st && typeof st === 'object' && '__srIndex' in st) {
+      const idx = st.__srIndex;
+      return typeof idx === 'number' ? idx : null;
+    }
+    return null;
+  }
   getHistoryIndex() {
     const g = globalThis;
-    return this.readIndex(g.history?.state);
+    return this.readHistoryIndex(g.history?.state);
   }
   ensureHistoryIndex() {
     const g = globalThis;
     const st = g.history?.state ?? {};
-    if (this.readIndex(st) === 0 && !(st && typeof st === 'object' && '__srIndex' in st)) {
-      const next = {
-        ...st,
+    let next = st;
+    let changed = false;
+    if (!('__srIndex' in next)) {
+      next = {
+        ...next,
         __srIndex: 0
       };
+      changed = true;
+    }
+    if (!('__srPath' in next)) {
+      next = {
+        ...next,
+        __srPath: this.getCurrentUrl()
+      };
+      changed = true;
+    }
+    if (changed) {
       try {
         g.history?.replaceState(next, '', g.location?.href);
-      } catch {
-        // ignore
+      } catch {}
+    }
+  }
+  getRouterPathFromHistory() {
+    const g = globalThis;
+    const st = g.history?.state;
+    if (st && typeof st === 'object' && '__srPath' in st) {
+      const p = st.__srPath;
+      if (typeof p === 'string' && p.length > 0) {
+        return p;
       }
     }
+    return this.getCurrentUrl();
   }
-  pushUrl(to) {
+  getReplaceDedupeFromHistory() {
+    const g = globalThis;
+    const st = g.history?.state;
+    if (st && typeof st === 'object' && '__srReplaceDedupe' in st) {
+      const v = st.__srReplaceDedupe;
+      return typeof v === 'boolean' ? v : false;
+    }
+    return false;
+  }
+  shouldSyncPathWithUrl(path) {
+    const {
+      pathname,
+      query
+    } = this.parsePath(path);
+    const base = this.matchBaseRoute(pathname, query);
+    if (!base) return true;
+    const mergedOptions = this.mergeOptions(base.options, base.stackId);
+    const rawsyncWithUrl = mergedOptions?.syncWithUrl;
+    if (typeof rawsyncWithUrl === 'boolean') {
+      return rawsyncWithUrl;
+    }
+    return true;
+  }
+  pushUrl(to, opts) {
     const g = globalThis;
     const st = g.history?.state ?? {};
-    const prev = this.readIndex(st);
+    const prev = this.readHistoryIndex(st);
+    const base = st;
+    const syncWithUrl = opts?.syncWithUrl ?? true;
+    const routerPath = to;
+    const visualUrl = syncWithUrl ? to : this.getCurrentUrl();
     const next = {
-      ...st,
-      __srIndex: prev + 1
+      ...base,
+      __srIndex: prev + 1,
+      __srPath: routerPath
     };
-    g.history?.pushState(next, '', to);
-    if (g.Event && g.dispatchEvent) {
-      g.dispatchEvent(new g.Event('pushState'));
-    }
+    g.history?.pushState(next, '', visualUrl);
   }
-  replaceUrl(to) {
+  replaceUrl(to, opts) {
     const g = globalThis;
     const st = g.history?.state ?? {};
-    g.history?.replaceState(st, '', to);
-    if (g.Event && g.dispatchEvent) {
-      g.dispatchEvent(new g.Event('replaceState'));
+    const base = st;
+    const syncWithUrl = opts?.syncWithUrl ?? true;
+    const routerPath = to;
+    const visualUrl = syncWithUrl ? to : this.getCurrentUrl();
+    const next = {
+      ...base,
+      __srPath: routerPath,
+      __srReplaceDedupe: !!opts?.dedupe
+    };
+    g.history?.replaceState(next, '', visualUrl);
+  }
+  replaceUrlSilently(to) {
+    if (!this.isWebEnv()) return;
+    this.suppressHistorySyncCount += 1;
+    this.replaceUrl(to, {
+      syncWithUrl: true
+    });
+  }
+  buildUrlFromActiveRoute() {
+    const ar = this.activeRoute;
+    if (!ar || !ar.path) {
+      return null;
     }
+    const path = ar.path;
+    const query = ar.query;
+    if (!query || Object.keys(query).length === 0) {
+      return path;
+    }
+    const search = qs.stringify(query);
+    return `${path}${search && search !== '' ? `?${search}` : ''}`;
   }
-  patchHistoryOnce() {
+  patchBrowserHistoryOnce() {
     const g = globalThis;
     const key = Symbol.for('sigmela_router_history_patch');
     if (g[key]) return;
@@ -677,42 +1519,78 @@ export class Router {
     }
     g[key] = true;
   }
-  lastBrowserIndex = 0;
-  pendingReplaceDedupe = false;
   setupBrowserHistory() {
     const g = globalThis;
-    this.patchHistoryOnce();
+    const gAny = g;
+    const activeKey = Symbol.for('sigmela_router_active_instance');
+    this.patchBrowserHistoryOnce();
     this.ensureHistoryIndex();
     this.lastBrowserIndex = this.getHistoryIndex();
+
+    // If a new Router instance is created (e.g. Fast Refresh / HMR), ensure only the latest
+    // instance reacts to browser history events to avoid duplicate navigation updates.
+    gAny[activeKey] = this;
     const onHistory = ev => {
-      const url = this.getCurrentUrl();
+      if (gAny[activeKey] !== this) return;
       if (ev.type === 'pushState') {
-        this.lastBrowserIndex = this.getHistoryIndex();
-        this.performNavigation(url, 'push');
+        const path = this.getRouterPathFromHistory();
+        const idx = this.getHistoryIndexOrNull();
+        this.lastBrowserIndex = idx !== null ? idx : Math.max(0, this.lastBrowserIndex + 1);
+        this.performNavigation(path, 'push');
         return;
       }
       if (ev.type === 'replaceState') {
-        const dedupe = this.pendingReplaceDedupe === true;
-        this.performNavigation(url, 'replace', {
+        if (this.suppressHistorySyncCount > 0) {
+          this.log('onHistory: replaceState suppressed (internal URL sync)');
+          this.suppressHistorySyncCount -= 1;
+          const idx = this.getHistoryIndexOrNull();
+          this.lastBrowserIndex = idx !== null ? idx : this.lastBrowserIndex;
+          return;
+        }
+        const path = this.getRouterPathFromHistory();
+        const dedupe = this.getReplaceDedupeFromHistory();
+        this.performNavigation(path, 'replace', {
           dedupe
         });
-        this.lastBrowserIndex = this.getHistoryIndex();
-        this.pendingReplaceDedupe = false;
+        const idx = this.getHistoryIndexOrNull();
+        this.lastBrowserIndex = idx !== null ? idx : this.lastBrowserIndex;
         return;
       }
       if (ev.type === 'popstate') {
-        const idx = this.getHistoryIndex();
-        const delta = idx - this.lastBrowserIndex;
+        const url = this.getRouterPathFromHistory();
+        const idx = this.getHistoryIndexOrNull();
+        const delta = idx !== null ? idx - this.lastBrowserIndex : 0;
+        this.log('popstate event', {
+          url,
+          idx,
+          prevIndex: this.lastBrowserIndex,
+          delta
+        });
+
+        // If browser history index isn't available (external history manipulations),
+        // treat popstate as a soft replace. The route path still comes from __srPath when present.
+        if (idx === null) {
+          this.performNavigation(url, 'replace', {
+            dedupe: true
+          });
+          return;
+        }
         if (delta < 0) {
-          let steps = -delta;
-          while (steps-- > 0) this.popOnce();
-          const target = this.parsePath(url).pathname;
-          const current = this.getVisibleRoute()?.path;
-          if (current !== target) this.performNavigation(url, 'replace');
+          this.performNavigation(url, 'replace', {
+            dedupe: true
+          });
         } else if (delta > 0) {
+          this.log('popstate: forward history step, treat as push', {
+            url
+          });
           this.performNavigation(url, 'push');
         } else {
-          this.performNavigation(url, 'replace');
+          this.log('popstate: same index, soft replace+dedupe', {
+            url
+          });
+          this.performNavigation(url, 'replace', {
+            dedupe: true
+          });
         }
         this.lastBrowserIndex = idx;
       }
@@ -721,123 +1599,267 @@ export class Router {
     g.addEventListener?.('replaceState', onHistory);
     g.addEventListener?.('popstate', onHistory);
   }
-  popOnce() {
-    if (this.tryPopActiveStack()) return;
+  syncUrlAfterInternalPop(popped) {
+    if (!this.isWebEnv()) return;
+    const compiled = this.registry.find(r => r.routeId === popped.routeId);
+    const isQueryRoute = compiled && compiled.queryPattern && Object.keys(compiled.queryPattern).length > 0;
+    if (isQueryRoute) {
+      const currentUrl = this.getCurrentUrl();
+      const {
+        pathname,
+        query
+      } = this.parsePath(currentUrl);
+      const pattern = compiled.queryPattern;
+      const nextQuery = {
+        ...query
+      };
+      for (const key of Object.keys(pattern)) {
+        delete nextQuery[key];
+      }
+      const hasQuery = Object.keys(nextQuery).length > 0;
+      const newSearch = hasQuery ? `?${qs.stringify(nextQuery)}` : '';
+      const nextUrl = `${pathname}${newSearch}`;
+      this.log('syncUrlWithStateAfterInternalPop (query)', {
+        poppedRouteId: popped.routeId,
+        from: currentUrl,
+        to: nextUrl
+      });
+      this.replaceUrlSilently(nextUrl);
+      return;
+    }
+    const from = this.getCurrentUrl();
+    const nextUrl = this.buildUrlFromActiveRoute();
+    if (!nextUrl) {
+      this.log('syncUrlWithStateAfterInternalPop: no activeRoute, skip URL sync', {
+        from
+      });
+      return;
+    }
+    this.log('syncUrlAfterInternalPop (base)', {
+      poppedRouteId: popped.routeId,
+      from,
+      to: nextUrl
+    });
+    this.replaceUrlSilently(nextUrl);
   }
-
-  // Attempts to pop exactly one screen within the active stack only.
-  // Returns true if a pop occurred; false otherwise.
-  tryPopActiveStack() {
-    const handlePop = item => {
-      if (item.options?.stackPresentation === 'sheet') {
-        const dismisser = this.sheetDismissers.get(item.key);
-        if (dismisser) {
-          this.unregisterSheetDismisser(item.key);
-          dismisser();
-          return true;
+  popFromActiveStack() {
+    const active = this.activeRoute;
+    if (!active || !active.stackId) {
+      if (this.root) {
+        const sid = this.root.getId();
+        if (sid) {
+          const stackHistory = this.getStackHistory(sid);
+          if (stackHistory.length > 0) {
+            const top = stackHistory[stackHistory.length - 1];
+            const isModalOrSheet = top.options?.stackPresentation === 'modal' || top.options?.stackPresentation === 'sheet';
+            if (stackHistory.length > 1 || isModalOrSheet) {
+              if (top.options?.stackPresentation === 'sheet') {
+                const dismisser = this.sheetDismissers.get(top.key);
+                if (dismisser) {
+                  this.unregisterSheetDismisser(top.key);
+                  dismisser();
+                  return top;
+                }
+              }
+              this.applyHistoryChange('pop', top);
+              return top;
+            }
+          }
         }
       }
-      this.applyHistoryChange('pop', item);
-      return true;
-    };
-    if (this.global) {
-      const gid = this.global.getId();
-      const gslice = this.getStackHistory(gid);
-      const gtop = gslice.length ? gslice[gslice.length - 1] : undefined;
-      if (gtop) {
-        return handlePop(gtop);
-      }
-    }
-    if (this.tabBar) {
-      const idx = this.getActiveTabIndex();
-      const state = this.tabBar.getState();
-      const route = state.tabs[idx];
-      if (!route) return false;
-      const stack = this.tabBar.stacks[route.tabKey];
-      if (!stack) return false;
-      const sid = stack.getId();
-      const slice = this.getStackHistory(sid);
-      if (slice.length > 1) {
-        const top = slice[slice.length - 1];
-        if (top) {
-          return handlePop(top);
-        }
+      return null;
+    }
+    let activeItem;
+    for (let i = this.state.history.length - 1; i >= 0; i--) {
+      const h = this.state.history[i];
+      if (h && active && h.stackId === active.stackId) {
+        activeItem = h;
+        break;
       }
-      return false;
     }
-    if (isNavigationStackLike(this.root)) {
-      const sid = this.root.getId();
-      const slice = this.getStackHistory(sid);
-      if (slice.length > 1) {
-        const top = slice[slice.length - 1];
-        if (top) {
-          return handlePop(top);
-        }
+    if (!active || !activeItem || !activeItem.stackId) return null;
+    const stackHistory = this.getStackHistory(activeItem.stackId);
+    const isModalOrSheet = activeItem.options?.stackPresentation === 'modal' || activeItem.options?.stackPresentation === 'sheet';
+    const allowRootPop = activeItem.options?.allowRootPop === true;
+    if (stackHistory.length <= 1 && !isModalOrSheet && !allowRootPop) {
+      return null;
+    }
+    if (activeItem.options?.stackPresentation === 'sheet') {
+      const dismisser = this.sheetDismissers.get(activeItem.key);
+      if (dismisser) {
+        this.unregisterSheetDismisser(activeItem.key);
+        dismisser();
+        return activeItem;
       }
     }
-    return false;
+    const top = stackHistory[stackHistory.length - 1];
+    this.applyHistoryChange('pop', top);
+    return top;
   }
-
-  // Expand deep URL into a stack chain on initial load
-  parse(url) {
+  buildHistoryFromUrl(url, reuseKeysFrom) {
     const {
       pathname,
       query
     } = this.parsePath(url);
-    const deepest = this.matchRoute(pathname);
-    if (!deepest) {
+    this.log('parse', {
+      url,
+      pathname,
+      query
+    });
+    const baseRoute = this.matchBaseRoute(pathname, {});
+    const deepest = this.matchBaseRoute(pathname, query);
+    const hasDeepestQueryPattern = deepest && deepest.queryPattern && Object.keys(deepest.queryPattern).length > 0;
+    const isDeepestOverlay = hasDeepestQueryPattern && deepest && baseRoute && deepest.routeId !== baseRoute.routeId;
+    if (!deepest || isDeepestOverlay && !baseRoute) {
       if (__DEV__) {
-        throw new Error(`Route not found: "${pathname}"`);
+        console.warn(`[Router] parse: no base route found for "${pathname}", seeding initial history`);
       }
       this.seedInitialHistory();
+      this.recomputeActiveRoute();
+      this.emit(this.listeners);
       return;
     }
-    if (deepest.scope === 'tab' && this.tabBar && deepest.tabIndex !== undefined) {
-      this.onTabIndexChange(deepest.tabIndex);
+    const segments = pathname.split('/').filter(Boolean);
+    const prefixes = segments.length > 0 ? segments.map((_, i) => '/' + segments.slice(0, i + 1).join('/')) : ['/'];
+    if (!prefixes.includes('/')) {
+      prefixes.unshift('/');
     }
-    const parts = pathname.split('/').filter(Boolean);
-    const prefixes = new Array(parts.length + 1);
-    let acc = '';
-    prefixes[0] = '/';
-    for (let i = 0; i < parts.length; i++) {
-      acc += `/${parts[i]}`;
-      prefixes[i + 1] = acc;
-    }
-    const candidates = [];
-    for (const route of this.registry) {
-      if (route.stackId !== deepest.stackId || route.scope !== deepest.scope) {
-        continue;
-      }
-      const segmentsCount = route.path.split('/').filter(Boolean).length;
-      const candidateUrl = prefixes[segmentsCount];
-      if (!candidateUrl) {
-        continue;
+    const items = [];
+    prefixes.forEach((prefixPath, index) => {
+      this.log('parse prefix', {
+        index,
+        prefixPath
+      });
+      let routeForPrefix;
+      if (index === prefixes.length - 1) {
+        routeForPrefix = baseRoute || deepest;
+      } else {
+        let best;
+        for (const route of this.registry) {
+          if (route.queryPattern) continue;
+          const matchResult = route.matchPath(prefixPath);
+          if (!matchResult) continue;
+          const spec = route.baseSpecificity;
+          this.log('parse candidate for prefix', {
+            prefixPath,
+            routeId: route.routeId,
+            path: route.path,
+            baseSpecificity: spec
+          });
+          if (!best || spec > best.spec) {
+            best = {
+              route,
+              spec
+            };
+          }
+        }
+        routeForPrefix = best?.route;
       }
-      const matchResult = route.match(candidateUrl);
-      if (!matchResult) {
-        continue;
+      if (!routeForPrefix) {
+        this.log('parse: no route for prefix', {
+          index,
+          prefixPath
+        });
+        return;
       }
-      candidates.push({
-        params: matchResult.params,
-        segmentCount: segmentsCount,
-        candidateUrl,
-        route
+      const matchResult = routeForPrefix.matchPath(prefixPath);
+      const params = matchResult ? matchResult.params : undefined;
+      const itemQuery = index === prefixes.length - 1 && !isDeepestOverlay ? query : {};
+      const item = this.createHistoryItem(routeForPrefix, params, itemQuery, prefixPath);
+      this.log('parse: push item', {
+        index,
+        routeId: routeForPrefix.routeId,
+        path: routeForPrefix.path,
+        prefixPath,
+        params,
+        itemQuery
       });
+      items.push(item);
+    });
+    let overlayItem;
+    if (isDeepestOverlay && deepest && baseRoute) {
+      overlayItem = this.createHistoryItem(deepest, undefined, query, pathname);
+      this.log('parse: push overlay item', {
+        routeId: deepest.routeId,
+        path: deepest.path,
+        pathname,
+        query
+      });
+      items.push(overlayItem);
+    }
+    if (items.length > 0) {
+      const lastItem = items[items.length - 1];
+      const lastItemCompiled = lastItem ? this.registry.find(r => r.routeId === lastItem.routeId) : undefined;
+      const isLastItemOverlay = lastItem && lastItemCompiled && lastItemCompiled.queryPattern && Object.keys(lastItemCompiled.queryPattern).length > 0;
+      const finalRouteId = isLastItemOverlay && items.length > 1 ? items[items.length - 2]?.routeId : lastItem?.routeId;
+      const searchStartIndex = isLastItemOverlay ? items.length - 2 : items.length - 1;
+      for (let i = searchStartIndex; i >= 0; i--) {
+        const item = items[i];
+        if (item && item.routeId) {
+          const compiled = this.registry.find(r => r.routeId === item.routeId);
+          if (compiled && compiled.childNode) {
+            this.addChildNodeSeedsToItems(item.routeId, items, finalRouteId);
+            // Don't break: we may have multiple nested containers (e.g. TabBar -> SplitView).
+            // All of them must be activated/seeded to make the UI consistent on initial deep-link.
+          }
+        }
+      }
+      if (overlayItem) {
+        const overlayIndex = items.findIndex(item => item.key === overlayItem.key);
+        if (overlayIndex >= 0 && overlayIndex < items.length - 1) {
+          items.splice(overlayIndex, 1);
+          items.push(overlayItem);
+        }
+      }
     }
-    if (!candidates.length) {
+    if (!items.length) {
+      if (__DEV__) {
+        console.warn('[Router] parse: no items built for URL, seeding initial history');
+      }
       this.seedInitialHistory();
+      this.recomputeActiveRoute();
+      this.emit(this.listeners);
       return;
     }
-    candidates.sort((a, b) => a.segmentCount - b.segmentCount);
-    const items = candidates.map((c, i) => this.createHistoryItem(c.route, c.params, i === candidates.length - 1 ? query : {}, c.candidateUrl));
-    const first = items[0];
-    const sid = first?.stackId ?? deepest.stackId;
+
+    // When rebuilding history (e.g. tab reset), preserve keys for matching items
+    // so web animations don't replay for the whole root stack.
+    this.reuseKeysFromPreviousHistory(items, reuseKeysFrom);
     this.setState({
       history: items
     });
-    if (sid) {
-      this.stackSlices.set(sid, items);
-      this.emit(this.stackListeners.get(sid));
+    this.stackListeners.forEach(set => this.emit(set));
+    this.recomputeActiveRoute();
+    this.emit(this.listeners);
+  }
+  reuseKeysFromPreviousHistory(next, prev) {
+    if (!prev || prev.length === 0) return;
+    const used = new Set();
+    const sameItemIdentity = (a, b) => {
+      if (a.routeId !== b.routeId) return false;
+      if ((a.stackId ?? '') !== (b.stackId ?? '')) return false;
+      if ((a.path ?? '') !== (b.path ?? '')) return false;
+      const sameParams = this.areShallowEqual(a.params ?? {}, b.params ?? {});
+      if (!sameParams) return false;
+      const sameQuery = this.areShallowEqual(a.query ?? {}, b.query ?? {});
+      if (!sameQuery) return false;
+
+      // Keep presentation stable: modal/sheet items should not steal keys from push items.
+      const ap = a.options?.stackPresentation ?? null;
+      const bp = b.options?.stackPresentation ?? null;
+      if (ap !== bp) return false;
+      return true;
+    };
+    for (const item of next) {
+      for (let i = prev.length - 1; i >= 0; i--) {
+        const candidate = prev[i];
+        if (!candidate) continue;
+        if (used.has(candidate.key)) continue;
+        if (!sameItemIdentity(item, candidate)) continue;
+        item.key = candidate.key;
+        used.add(candidate.key);
+        break;
+      }
     }
   }
 }