@sigmela/router 0.3.7 → 0.5.0

package/lib/module/Router.js

@@ -1,2171 +0,0 @@
-"use strict";
-
-import { nanoid } from 'nanoid/non-secure';
-import { Platform } from 'react-native';
-import qs from 'query-string';
-import { isModalLikePresentation } from "./types.js";
-function canSwitchToRoute(node) {
-  return node !== undefined && typeof node.switchToRoute === 'function';
-}
-function canLookupRoutes(node) {
-  return node !== undefined && typeof node.hasRoute === 'function';
-}
-const EMPTY_ARRAY = [];
-export class Router {
-  root = null;
-  listeners = new Set();
-  registry = [];
-  state = {
-    history: []
-  };
-  debugEnabled = false;
-  sheetDismissers = new Map();
-  dismissedStackIds = new Set();
-  stackListeners = new Map();
-  stackById = new Map();
-  routeById = new Map();
-  stackActivators = new Map();
-  compiledRouteById = new Map();
-  stackHistories = new Map();
-  activeRoute = null;
-  activeRouteListeners = new Set();
-  rootListeners = new Set();
-  rootTransition = undefined;
-  // Root swaps should behave like a fresh initial mount (no enter animation).
-  // We keep the API option for compatibility, but suppress transition application.
-  suppressRootTransitionOnNextRead = false;
-  lastBrowserIndex = 0;
-  suppressHistorySyncCount = 0;
-  // Used to prevent stale controller-driven navigations (controller calls present later).
-  navigationToken = 0;
-  // parsePath one-slot cache
-  lastParsedPath = null;
-  lastParsedResult = null;
-
-  // matchBaseRoute one-slot cache
-  lastMatchedPathname = null;
-  lastMatchedQuery = null;
-  lastMatchedResult = null;
-  constructor(config) {
-    this.debugEnabled = config.debug ?? false;
-    this.routerScreenOptions = config.screenOptions;
-    this.log('ctor');
-    this.roots = config.roots;
-    this.activeRootKey = config.root;
-    const initialRoot = this.roots[this.activeRootKey];
-    if (!initialRoot) {
-      throw new Error(`Router: root "${String(this.activeRootKey)}" not found in config.roots`);
-    }
-    this.root = initialRoot;
-    this.buildRegistry();
-    if (this.isWebEnv()) {
-      this.setupBrowserHistory();
-      const url = this.getCurrentUrl();
-      this.buildHistoryFromUrl(url);
-    } else {
-      this.seedInitialHistory();
-    }
-    this.recomputeActiveRoute();
-  }
-  isDebugEnabled() {
-    return this.debugEnabled;
-  }
-  isStackBeingDismissed(stackId) {
-    if (!stackId) return false;
-    return this.dismissedStackIds.has(stackId);
-  }
-  clearStackDismissed(stackId) {
-    if (!stackId) return;
-    this.dismissedStackIds.delete(stackId);
-  }
-  markStackDismissed(stackId) {
-    this.dismissedStackIds.add(stackId);
-  }
-  log(message, data) {
-    if (this.debugEnabled) {
-      if (data !== undefined) {
-        console.log(`[Router] ${message}`, data);
-      } else {
-        console.log(`[Router] ${message}`);
-      }
-    }
-  }
-  navigate = path => {
-    if (!path || typeof path !== 'string') {
-      if (__DEV__) throw new Error('Router.navigate: path must be a non-empty string');
-      console.warn('[Router] navigate called with invalid path');
-      return;
-    }
-    if (this.isWebEnv()) {
-      const syncWithUrl = this.shouldSyncPathWithUrl(path);
-      this.pushUrl(path, {
-        syncWithUrl
-      });
-      return;
-    }
-    this.performNavigation(path, 'push');
-  };
-  replace = (path, dedupe) => {
-    if (!path || typeof path !== 'string') {
-      if (__DEV__) throw new Error('Router.replace: path must be a non-empty string');
-      console.warn('[Router] replace called with invalid path');
-      return;
-    }
-    if (this.isWebEnv()) {
-      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 (!path || typeof path !== 'string') {
-      if (__DEV__) throw new Error('Router.reset: path must be a non-empty string');
-      console.warn('[Router] reset called with invalid path');
-      return;
-    }
-    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);
-  };
-  unregisterSheetDismisser = key => {
-    this.sheetDismissers.delete(key);
-  };
-  goBack = () => {
-    if (this.isWebEnv()) {
-      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.popFromActiveStack();
-  };
-
-  /**
-   * Closes the nearest modal or sheet, regardless of navigation depth inside it.
-   * Useful when a NavigationStack is rendered inside a modal and you want to
-   * close the entire modal from any screen within it.
-   */
-  dismiss = () => {
-    // Find the nearest modal/sheet item in history (searching from end)
-    let modalItem = null;
-    for (let i = this.state.history.length - 1; i >= 0; i--) {
-      const item = this.state.history[i];
-      if (item && isModalLikePresentation(item.options?.stackPresentation)) {
-        modalItem = item;
-        break;
-      }
-    }
-    if (!modalItem) {
-      this.log('dismiss: no modal found in history');
-      return;
-    }
-    this.log('dismiss: closing modal', {
-      key: modalItem.key,
-      routeId: modalItem.routeId,
-      stackId: modalItem.stackId,
-      presentation: modalItem.options?.stackPresentation
-    });
-
-    // Handle sheet dismisser if registered
-    if (modalItem.options?.stackPresentation === 'sheet') {
-      const dismisser = this.sheetDismissers.get(modalItem.key);
-      if (dismisser) {
-        this.unregisterSheetDismisser(modalItem.key);
-        dismisser();
-        return;
-      }
-    }
-
-    // Check if modal has a childNode (NavigationStack added via addModal)
-    const compiled = this.getCompiledRoute(modalItem.routeId);
-    const childNode = compiled?.childNode;
-    if (childNode) {
-      // Modal stack: remove all items from child stack AND the modal wrapper item
-      const childStackId = childNode.getId();
-      this.log('dismiss: closing modal stack', {
-        childStackId,
-        modalKey: modalItem.key
-      });
-      this.markStackDismissed(childStackId);
-
-      // Clear child stack's history cache BEFORE setState so listeners see clean state
-      this.stackHistories.delete(childStackId);
-      const newHistory = this.state.history.filter(item => item.stackId !== childStackId && item.key !== modalItem.key);
-      this.setState({
-        history: newHistory
-      });
-    } else {
-      // Simple modal: just pop the modal item
-      // applyHistoryChange already calls recomputeActiveRoute + emit(this.listeners)
-      this.applyHistoryChange('pop', modalItem);
-    }
-    if (childNode) {
-      // childNode branch uses setState directly, so we need to emit manually
-      this.recomputeActiveRoute();
-      this.emit(this.listeners);
-    }
-
-    // Sync URL on web
-    if (this.isWebEnv()) {
-      this.syncUrlAfterInternalPop(modalItem);
-    }
-  };
-  getState = () => {
-    return this.state;
-  };
-  subscribe(listener) {
-    this.listeners.add(listener);
-    return () => {
-      this.listeners.delete(listener);
-    };
-  }
-  subscribeActiveRoute = listener => {
-    this.activeRouteListeners.add(listener);
-    return () => {
-      this.activeRouteListeners.delete(listener);
-    };
-  };
-  getStackHistory = stackId => {
-    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;
-  };
-
-  /**
-   * Returns all history items in navigation order.
-   * Useful for rendering all screens including modal stacks.
-   */
-  getFullHistory = () => {
-    return this.state.history;
-  };
-  subscribeStack = (stackId, cb) => {
-    if (!stackId) return () => {};
-    let set = this.stackListeners.get(stackId);
-    if (!set) {
-      set = new Set();
-      this.stackListeners.set(stackId, set);
-    }
-    set.add(cb);
-    return () => {
-      set.delete(cb);
-      if (set.size === 0) {
-        this.stackListeners.delete(stackId);
-      }
-    };
-  };
-  getRootStackId() {
-    return this.root?.getId();
-  }
-  subscribeRoot(listener) {
-    this.rootListeners.add(listener);
-    return () => this.rootListeners.delete(listener);
-  }
-  emitRootChange() {
-    this.emit(this.rootListeners);
-  }
-  getRootTransition() {
-    if (this.suppressRootTransitionOnNextRead) {
-      this.suppressRootTransitionOnNextRead = false;
-      // Ensure we don't accidentally apply it on subsequent renders.
-      this.rootTransition = undefined;
-      return undefined;
-    }
-    return this.rootTransition;
-  }
-  setRoot(nextRootKey, options) {
-    const nextRoot = this.roots[nextRootKey];
-    if (!nextRoot) {
-      throw new Error(`Router: root "${String(nextRootKey)}" not found in config.roots`);
-    }
-    this.activeRootKey = nextRootKey;
-    this.root = nextRoot;
-    this.rootTransition = options?.transition ?? undefined;
-    // Make the incoming root behave like initial: suppress enter animation.
-    this.suppressRootTransitionOnNextRead = true;
-    this.registry.length = 0;
-    this.stackById.clear();
-    this.routeById.clear();
-    this.compiledRouteById.clear();
-    this.stackActivators.clear();
-    this.lastMatchedPathname = null;
-    this.lastMatchedQuery = null;
-    this.lastMatchedResult = null;
-    this.state = {
-      history: []
-    };
-    this.stackHistories.clear();
-    this.sheetDismissers.clear();
-    this.dismissedStackIds.clear();
-    this.stackListeners.clear();
-    this.buildRegistry();
-    this.seedInitialHistory();
-    this.recomputeActiveRoute();
-    this.emitRootChange();
-    this.emit(this.listeners);
-  }
-  getActiveRoute = () => {
-    return this.activeRoute;
-  };
-  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: {}
-        };
-      } 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
-      });
-    }
-    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);
-        const newRoute = meta ? {
-          ...meta,
-          routeId: top.routeId,
-          params: top.params,
-          query: top.query,
-          path: top.path
-        } : {
-          routeId: top.routeId,
-          stackId: top.stackId,
-          params: top.params,
-          query: top.query,
-          path: top.path
-        };
-
-        // Shallow compare to keep stable reference and avoid unnecessary re-renders
-        if (this.activeRoute && this.activeRoute.routeId === newRoute.routeId && this.activeRoute.stackId === newRoute.stackId && this.activeRoute.path === newRoute.path && this.activeRoute.params === newRoute.params && this.activeRoute.query === newRoute.query) {
-          return;
-        }
-        this.activeRoute = newRoute;
-        this.emit(this.activeRouteListeners);
-        return;
-      }
-    }
-    if (this.activeRoute !== null) {
-      this.activeRoute = null;
-      this.emit(this.activeRouteListeners);
-    }
-  }
-  performNavigation(path, action, opts) {
-    if (this.destroyed) return;
-    const {
-      pathname,
-      query
-    } = this.parsePath(path);
-    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}"`);
-      }
-      console.warn(`[Router] Route not found: "${pathname}"`);
-      return;
-    }
-
-    // Ensure the root-level container (e.g. TabBar) is activated for the matched route.
-    // This is important when the matched route belongs to a nested stack inside a composite node
-    // like SplitView: stackActivators won't fire for the tab itself in that case.
-    const rootStackId = this.root?.getId();
-    if (rootStackId) {
-      this.activateContainerForRoute(base.routeId, rootStackId);
-    }
-    const activator = base.stackId ? this.stackActivators.get(base.stackId) : undefined;
-    if (activator) {
-      activator();
-    }
-    const matchResult = base.matchPath(pathname);
-    const params = matchResult ? matchResult.params : undefined;
-
-    // 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') {
-      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,
-            path: pathname,
-            component: base.component,
-            options: this.mergeOptions(base.options, base.stackId),
-            pattern: base.path
-          };
-          this.applyHistoryChange('popTo', updatedExisting);
-          return;
-        }
-      }
-    }
-    if (action === 'replace' && opts?.dedupe) {
-      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;
-        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);
-          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,
-            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,
-            path: pathname
-          };
-          this.log('dedupe: found existing item, calling popTo', {
-            key: updatedExisting.key
-          });
-          this.applyHistoryChange('popTo', updatedExisting);
-          return;
-        }
-      }
-    }
-    if (base.controller) {
-      const controllerInput = {
-        params,
-        query
-      };
-      let didPresent = false;
-      const present = 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);
-
-        // Seed child node if present
-        if (base.childNode) {
-          this.addChildNodeSeedsToHistory(base.routeId);
-        }
-      };
-      base.controller(controllerInput, present);
-      return;
-    }
-    const newItem = this.createHistoryItem(base, params, query, pathname);
-    this.applyHistoryChange(action, newItem);
-
-    // If the matched route has a childNode (e.g., NavigationStack added via addModal),
-    // seed the child stack's history so StackRenderer has items to render.
-    if (base.childNode) {
-      this.addChildNodeSeedsToHistory(base.routeId);
-    }
-  }
-  createHistoryItem(matched, params, query, pathname, passProps) {
-    const normalizedParams = params && Object.keys(params).length > 0 ? params : undefined;
-    return {
-      key: this.generateKey(),
-      routeId: matched.routeId,
-      component: matched.component,
-      options: this.mergeOptions(matched.options, matched.stackId),
-      params: normalizedParams,
-      query,
-      passProps,
-      stackId: matched.stackId,
-      pattern: matched.path,
-      path: pathname
-    };
-  }
-  applyHistoryChange(action, item) {
-    const stackId = item.stackId;
-    if (!stackId) {
-      if (__DEV__) {
-        console.warn(`[Router] Navigation dropped: item has no stackId (routeId: ${item.routeId}, path: ${item.path})`);
-      }
-      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) continue;
-        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) continue;
-        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);
-      }
-      let insertPos = copy.length;
-      for (let i = copy.length - 1; i >= 0; i--) {
-        if (copy[i]?.stackId === stackId) {
-          insertPos = i + 1;
-          break;
-        }
-      }
-      copy.splice(insertPos, 0, updatedItem);
-      nextHist = copy;
-    }
-    this.setState({
-      history: nextHist
-    }, item.stackId);
-    this.recomputeActiveRoute();
-    this.emit(this.listeners);
-  }
-  setState(next, affectedStackId) {
-    const prev = this.state;
-    const nextState = {
-      history: next.history ?? prev.history
-    };
-    this.state = nextState;
-    if (nextState.history !== prev.history) {
-      this.updateStackHistories(affectedStackId);
-    }
-    this.log('setState', nextState);
-  }
-  updateStackHistories(affectedStackId) {
-    if (affectedStackId) {
-      // Fast path: only update the one affected stack — O(H) instead of O(S×H)
-      const newHist = this.state.history.filter(h => h.stackId === affectedStackId);
-      const oldHist = this.stackHistories.get(affectedStackId);
-      if (!this.areArraysEqual(oldHist, newHist)) {
-        if (newHist.length === 0) {
-          this.stackHistories.delete(affectedStackId);
-        } else {
-          this.stackHistories.set(affectedStackId, newHist);
-        }
-        const listeners = this.stackListeners.get(affectedStackId);
-        if (listeners) this.emit(listeners);
-      }
-      return;
-    }
-
-    // Slow path: full recompute — used by buildHistoryFromUrl, setRoot, etc.
-    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);
-      }
-    });
-    changedStackIds.forEach(stackId => {
-      this.emit(this.stackListeners.get(stackId));
-    });
-  }
-  areArraysEqual(a, b) {
-    if (!a) return false;
-    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) {
-    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.getCompiledRoute(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.getCompiledRoute(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
-    }, seedStackId);
-    // setState with affectedStackId already emits to the stack's listeners
-
-    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
-        };
-        this.emit(this.activeRouteListeners);
-        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
-      };
-      this.emit(this.activeRouteListeners);
-    }
-  }
-  emitDepth = 0;
-  emit(set) {
-    if (!set) return;
-    if (this.emitDepth > 5) {
-      if (this.debugEnabled) console.warn('[Router] emit recursion limit reached');
-      return;
-    }
-    this.emitDepth++;
-    try {
-      for (const l of Array.from(set)) {
-        try {
-          l();
-        } catch (e) {
-          if (this.debugEnabled) {
-            console.error('[Router] listener error', e);
-          }
-        }
-      }
-    } finally {
-      this.emitDepth--;
-    }
-  }
-  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 addFromNode = (node, basePath, inheritedOptions) => {
-      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);
-      }
-      let isFirstRoute = true;
-      for (const r of routes) {
-        // Merge options: first route inherits parent options (e.g., for nested stacks)
-        const mergedOptions = isFirstRoute && inheritedOptions ? {
-          ...inheritedOptions,
-          ...r.options
-        } : r.options;
-
-        // Always register the route.
-        // If it has a childNode, r.component is already childNode.getRenderer() (set by extractComponent).
-        const compiled = {
-          routeId: r.routeId,
-          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: mergedOptions,
-          stackId,
-          childNode: r.childNode
-        };
-        this.registry.push(compiled);
-        this.compiledRouteById.set(compiled.routeId, 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,
-          hasChildNode: !!compiled.childNode
-        });
-        isFirstRoute = false;
-
-        // Also register routes from childNode (for navigation inside the nested stack)
-        if (r.childNode) {
-          const nextBaseForChild = r.isWildcardPath ? normalizedBasePath : this.joinPaths(normalizedBasePath, r.pathnamePattern);
-          // Child routes don't inherit parent options - they use their own
-          addFromNode(r.childNode, nextBaseForChild);
-        }
-      }
-      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 '';
-    }
-    let normalized = input.startsWith('/') ? input : `/${input}`;
-    if (normalized.length > 1 && normalized.endsWith('/')) {
-      normalized = normalized.slice(0, -1);
-    }
-    return normalized;
-  }
-  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;
-        }
-      }
-    }
-    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.getCompiledRoute(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(),
-          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', item);
-        this.addChildNodeSeedsToHistory(seed.routeId);
-      }
-      return;
-    }
-  }
-  addChildNodeSeedsToItems(routeId, items, finalRouteId, visited = new Set()) {
-    if (visited.has(routeId) || visited.size > 50) return;
-    visited.add(routeId);
-    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.getCompiledRoute(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.getCompiledRoute(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, visited);
-    }
-  }
-  addChildNodeSeedsToHistory(routeId, visited = new Set()) {
-    if (visited.has(routeId) || visited.size > 50) return;
-    visited.add(routeId);
-    const compiled = this.getCompiledRoute(routeId);
-    if (!compiled || !compiled.childNode) return;
-    const childNode = compiled.childNode;
-    const childSeed = this.getAutoSeed(childNode);
-    if (!childSeed) return;
-    const childCompiled = this.getCompiledRoute(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, visited);
-    }
-  }
-  matchBaseRoute(pathname, query) {
-    // One-slot cache: uses reference equality for query object
-    if (this.lastMatchedPathname !== null && pathname === this.lastMatchedPathname && query === this.lastMatchedQuery) {
-      return this.lastMatchedResult ?? undefined;
-    }
-    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;
-      }
-
-      // Routes with childNode AND modal/sheet presentation are "wrapper" routes
-      // that should take priority over the child stack's own routes when both match.
-      // This ensures addModal('/path', NavigationStack) renders the wrapper modal
-      // and not the child stack's first screen directly.
-      if (r.childNode && isModalLikePresentation(r.options?.stackPresentation)) {
-        spec += 1;
-      }
-      this.log('matchBaseRoute candidate', {
-        routeId: r.routeId,
-        path: r.path,
-        baseSpecificity: r.baseSpecificity,
-        adjustedSpecificity: spec,
-        hasQueryPattern,
-        hasChildNode: !!r.childNode,
-        stackId: r.stackId
-      });
-      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
-        }))
-      });
-      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
-            });
-          }
-        }
-      }
-      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
-      });
-    } else {
-      this.log('matchBaseRoute no match');
-    }
-    const result = best?.route;
-    this.lastMatchedPathname = pathname;
-    this.lastMatchedQuery = query;
-    this.lastMatchedResult = result ?? null;
-    return result;
-  }
-  generateKey() {
-    return `route-${nanoid()}`;
-  }
-  parsePath(path) {
-    if (path === this.lastParsedPath && this.lastParsedResult) {
-      return this.lastParsedResult;
-    }
-    const parsed = qs.parseUrl(path);
-    const result = {
-      pathname: parsed.url,
-      query: parsed.query
-    };
-    this.lastParsedPath = path;
-    this.lastParsedResult = result;
-    this.log('parsePath', {
-      input: path,
-      output: result
-    });
-    return result;
-  }
-  mergeOptions(routeOptions, stackId) {
-    const stackNode = stackId ? this.findStackById(stackId) : undefined;
-    const stackDefaults = stackNode?.getDefaultOptions?.();
-    const routerDefaults = this.routerScreenOptions;
-    if (!routerDefaults && !stackDefaults && !routeOptions) return undefined;
-    const merged = {
-      ...(routerDefaults ?? {}),
-      ...(stackDefaults ?? {}),
-      ...(routeOptions ?? {})
-    };
-    if (merged.stackPresentation === 'modal' && merged.convertModalToSheetForAndroid && Platform.OS === 'android') {
-      merged.stackPresentation = 'sheet';
-    }
-    return merged;
-  }
-  findStackById(stackId) {
-    return this.stackById.get(stackId);
-  }
-  getCompiledRoute(routeId) {
-    return this.compiledRouteById.get(routeId);
-  }
-  areShallowEqual(a, b) {
-    if (a === b) return true;
-    const na = a ?? {};
-    const nb = b ?? {};
-    const aKeys = Object.keys(na);
-    const bKeys = Object.keys(nb);
-    if (aKeys.length !== bKeys.length) return false;
-    for (const k of aKeys) {
-      if (!(k in nb)) return false;
-      const av = na[k];
-      const bv = nb[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);
-  }
-  getCurrentUrl() {
-    const g = globalThis;
-    return g.location ? `${g.location.pathname}${g.location.search}` : '/';
-  }
-  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.readHistoryIndex(g.history?.state);
-  }
-  ensureHistoryIndex() {
-    const g = globalThis;
-    const st = g.history?.state ?? {};
-    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 (e) {
-        if (this.debugEnabled) console.warn('[Router] ensureHistoryIndex replaceState failed', e);
-      }
-    }
-  }
-  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();
-  }
-  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.readHistoryIndex(st);
-    const base = st;
-    const syncWithUrl = opts?.syncWithUrl ?? true;
-    const routerPath = to;
-    const visualUrl = syncWithUrl ? to : this.getCurrentUrl();
-    const next = {
-      ...base,
-      __srIndex: prev + 1,
-      __srPath: routerPath
-    };
-    g.history?.pushState(next, '', visualUrl);
-  }
-  replaceUrl(to, opts) {
-    const g = globalThis;
-    const st = g.history?.state ?? {};
-    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;
-    if (this.suppressHistorySyncCount > 10) {
-      console.warn('[Router] suppressHistorySyncCount reset from', this.suppressHistorySyncCount);
-      this.suppressHistorySyncCount = 0;
-    }
-    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}` : ''}`;
-  }
-  patchBrowserHistoryOnce() {
-    const g = globalThis;
-    const key = Symbol.for('sigmela_router_history_patch');
-    if (g[key]) return;
-    const hist = g.history;
-    if (hist && hist.pushState && hist.replaceState) {
-      const originalPush = hist.pushState.bind(hist);
-      const originalReplace = hist.replaceState.bind(hist);
-      hist.pushState = (data, unused, url) => {
-        const res = originalPush(data, unused, url);
-        if (g.Event && g.dispatchEvent) {
-          g.dispatchEvent(new g.Event('pushState'));
-        }
-        return res;
-      };
-      hist.replaceState = (data, unused, url) => {
-        const res = originalReplace(data, unused, url);
-        if (g.Event && g.dispatchEvent) {
-          g.dispatchEvent(new g.Event('replaceState'));
-        }
-        return res;
-      };
-    }
-    g[key] = true;
-  }
-  setupBrowserHistory() {
-    // Abort previous listeners in case setupBrowserHistory is called twice
-    this.abortController?.abort();
-    this.abortController = new AbortController();
-    const {
-      signal
-    } = this.abortController;
-    const g = globalThis;
-    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 => {
-      if (gAny[activeKey] !== this) return;
-      if (ev.type === 'pushState') {
-        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') {
-        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
-        });
-        const idx = this.getHistoryIndexOrNull();
-        this.lastBrowserIndex = idx !== null ? idx : this.lastBrowserIndex;
-        return;
-      }
-      if (ev.type === 'popstate') {
-        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) {
-          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.log('popstate: same index, soft replace+dedupe', {
-            url
-          });
-          this.performNavigation(url, 'replace', {
-            dedupe: true
-          });
-        }
-        this.lastBrowserIndex = idx;
-      }
-    };
-    g.addEventListener?.('pushState', onHistory, {
-      signal
-    });
-    g.addEventListener?.('replaceState', onHistory, {
-      signal
-    });
-    g.addEventListener?.('popstate', onHistory, {
-      signal
-    });
-  }
-  destroyed = false;
-  destroy() {
-    this.destroyed = true;
-    this.abortController?.abort();
-    this.listeners.clear();
-    this.stackListeners.clear();
-    this.activeRouteListeners.clear();
-    this.rootListeners.clear();
-  }
-  syncUrlAfterInternalPop(popped) {
-    if (!this.isWebEnv()) return;
-    const compiled = this.getCompiledRoute(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);
-  }
-  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];
-            if (!top) return null;
-            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;
-            }
-          }
-        }
-      }
-      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;
-      }
-    }
-    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;
-      }
-    }
-    const top = stackHistory[stackHistory.length - 1];
-    if (!top) return null;
-    this.applyHistoryChange('pop', top);
-    return top;
-  }
-  buildHistoryFromUrl(url, reuseKeysFrom) {
-    const {
-      pathname,
-      query
-    } = this.parsePath(url);
-    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__) {
-        console.warn(`[Router] parse: no base route found for "${pathname}", seeding initial history`);
-      } else {
-        console.warn(`[Router] No base route found for "${pathname}"`);
-      }
-      this.seedInitialHistory();
-      this.recomputeActiveRoute();
-      this.emit(this.listeners);
-      return;
-    }
-    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 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;
-      }
-      if (!routeForPrefix) {
-        this.log('parse: no route for prefix', {
-          index,
-          prefixPath
-        });
-        return;
-      }
-      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.getCompiledRoute(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.getCompiledRoute(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 (!items.length) {
-      if (__DEV__) {
-        console.warn('[Router] parse: no items built for URL, seeding initial history');
-      } else {
-        console.warn('[Router] No items built for URL, seeding initial history');
-      }
-      this.seedInitialHistory();
-      this.recomputeActiveRoute();
-      this.emit(this.listeners);
-      return;
-    }
-
-    // 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
-    });
-    // setState -> updateStackHistories already emits to changed stacks
-
-    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;
-      }
-    }
-  }
-}