@sigmela/router 0.2.3 → 0.2.4

package/README.md

@@ -148,10 +148,60 @@ const stack = new NavigationStack({ header: { largeTitle: true } })
 
 Key methods:
 - `addScreen(pathPattern, componentOrNode, options?)`
-- `addModal(pathPattern, component, options?)` (shorthand for `stackPresentation: 'modal'`)
-- `addSheet(pathPattern, component, options?)` (shorthand for `stackPresentation: 'sheet'`)
+- `addModal(pathPattern, componentOrStack, options?)` (shorthand for `stackPresentation: 'modal'`)
+- `addSheet(pathPattern, componentOrStack, options?)` (shorthand for `stackPresentation: 'sheet'`)
 - `addStack(prefixOrStack, maybeStack?)` — compose nested stacks under a prefix
 
+### Modal Stacks (Stack in Stack)
+
+You can pass an entire `NavigationStack` to `addModal()` or `addSheet()` to create a multi-screen flow inside a modal:
+
+```tsx
+// Define a flow with multiple screens
+const emailVerifyStack = new NavigationStack()
+  .addScreen('/verify', EmailInputScreen)
+  .addScreen('/verify/sent', EmailSentScreen);
+
+// Mount the entire stack as a modal
+const rootStack = new NavigationStack()
+  .addScreen('/', HomeScreen)
+  .addModal('/verify', emailVerifyStack);
+```
+
+**How it works:**
+- Navigating to `/verify` opens the modal with `EmailInputScreen`
+- Inside the modal, `router.navigate('/verify/sent')` pushes `EmailSentScreen` within the same modal
+- `router.goBack()` navigates back inside the modal stack
+- `router.dismiss()` closes the entire modal from any depth
+
+**Example screen with navigation inside modal:**
+
+```tsx
+function EmailInputScreen() {
+  const router = useRouter();
+  
+  return (
+    <View>
+      <Button title="Next" onPress={() => router.navigate('/verify/sent')} />
+      <Button title="Close" onPress={() => router.dismiss()} />
+    </View>
+  );
+}
+
+function EmailSentScreen() {
+  const router = useRouter();
+  
+  return (
+    <View>
+      <Button title="Back" onPress={() => router.goBack()} />
+      <Button title="Done" onPress={() => router.dismiss()} />
+    </View>
+  );
+}
+```
+
+This pattern works recursively — you can nest stacks inside stacks to any depth.
+
 ### `Router`
 
 The `Router` holds navigation state and performs path matching.
@@ -169,6 +219,7 @@ Navigation:
 - `router.navigate(path)` — push
 - `router.replace(path, dedupe?)` — replace top of the active stack
 - `router.goBack()` — pop top of the active stack
+- `router.dismiss()` — close the nearest modal or sheet (including all screens in a modal stack)
 - `router.reset(path)` — **web-only**: rebuild Router state as if app loaded at `path`
 - `router.setRoot(rootKey, { transition? })` — swap root at runtime (`rootKey` from `config.roots`)
 
@@ -180,8 +231,6 @@ State/subscriptions:
 - `router.subscribeRoot(cb)` — notify when root is replaced via `setRoot`
 - `router.getStackHistory(stackId)` — slice of history for a stack
 
-> Note: `router.getGlobalStackId()` exists but currently returns `undefined`.
-
 ### `TabBar`
 
 `TabBar` is a container node that renders one tab at a time.
@@ -193,12 +242,16 @@ const tabBar = new TabBar({ component: CustomTabBar, initialIndex: 0 })
 ```
 
 Key methods:
-- `addTab({ key, stack?, screen?, title?, icon?, selectedIcon?, ... })`
+- `addTab({ key, stack?, node?, screen?, prefix?, title?, icon?, selectedIcon?, ... })`
 - `onIndexChange(index)` — switch active tab
 - `setBadge(index, badge | null)`
 - `setTabBarConfig(partialConfig)`
 - `getState()` and `subscribe(cb)`
 
+Notes:
+- Exactly one of `stack`, `node`, `screen` must be provided.
+- Use `prefix` to mount a tab's routes under a base path (e.g. `/mail`).
+
 Web behavior note:
 - The built-in **web** tab bar renderer resets Router history on tab switch (to keep URL and Router state consistent) using `router.reset(firstRoutePath)`.
 
@@ -207,22 +260,25 @@ Web behavior note:
 `SplitView` renders **two stacks**: `primary` and `secondary`.
 
 - On **native**, `secondary` overlays `primary` when it has at least one screen in its history.
-- On **web**, the layout becomes side-by-side at a fixed breakpoint (currently `>= 640px` in CSS).
+- On **web**, the layout becomes side-by-side at a fixed breakpoint (`minWidth`, default `640px`).
 
 ```tsx
-import { NavigationStack, SplitView } from '@sigmela/router';
+import { NavigationStack, SplitView, TabBar } from '@sigmela/router';
 
 const master = new NavigationStack().addScreen('/', ThreadsScreen);
 const detail = new NavigationStack().addScreen('/:threadId', ThreadScreen);
 
 const splitView = new SplitView({
-  minWidth: 640, // currently not used by the web renderer; kept for API compatibility
+  minWidth: 640,
   primary: master,
   secondary: detail,
   primaryMaxWidth: 390,
 });
 
-const root = new NavigationStack().addScreen('/mail', splitView);
+// Mount SplitView directly as a tab (no wrapper stack needed).
+const tabBar = new TabBar()
+  .addTab({ key: 'mail', node: splitView, prefix: '/mail', title: 'Mail' })
+  .addTab({ key: 'settings', stack: settingsStack, title: 'Settings' });
 ```
 
 ## Controllers

package/lib/module/Navigation.js

@@ -5,13 +5,22 @@ import { RouterContext } from "./RouterContext.js";
 import { ScreenStack } from "./ScreenStack/index.js";
 import { StyleSheet } from 'react-native';
 import { useSyncExternalStore, memo, useCallback, useEffect, useState } from 'react';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 const EMPTY_HISTORY = [];
 function useStackHistory(router, stackId) {
   const subscribe = useCallback(cb => stackId ? router.subscribeStack(stackId, cb) : () => {}, [router, stackId]);
   const get = useCallback(() => stackId ? router.getStackHistory(stackId) : EMPTY_HISTORY, [router, stackId]);
   return useSyncExternalStore(subscribe, get, get);
 }
+
+/**
+ * Navigation component renders the root and global stacks.
+ *
+ * Modal stacks (NavigationStack added via addModal) are rendered as regular ScreenStackItems
+ * with their component being the StackRenderer that subscribes to its own stack history.
+ * This creates a clean recursive structure: stacks render their items, nested stacks
+ * (via childNode) render their own items through StackRenderer.
+ */
 export const Navigation = /*#__PURE__*/memo(({
   router,
   appearance
@@ -30,23 +39,17 @@ export const Navigation = /*#__PURE__*/memo(({
     rootId
   } = root;
   const rootTransition = router.getRootTransition();
-  const globalId = router.getGlobalStackId();
   const rootItems = useStackHistory(router, rootId);
-  const globalItems = useStackHistory(router, globalId);
   return /*#__PURE__*/_jsx(RouterContext.Provider, {
     value: router,
-    children: /*#__PURE__*/_jsxs(ScreenStack, {
+    children: /*#__PURE__*/_jsx(ScreenStack, {
       style: styles.flex,
-      children: [rootItems.map(item => /*#__PURE__*/_jsx(ScreenStackItem, {
+      children: rootItems.map(item => /*#__PURE__*/_jsx(ScreenStackItem, {
         stackId: rootId,
         item: item,
         stackAnimation: rootTransition,
         appearance: appearance
-      }, `root-${item.key}`)), globalItems.map(item => /*#__PURE__*/_jsx(ScreenStackItem, {
-        appearance: appearance,
-        stackId: globalId,
-        item: item
-      }, `global-${item.key}`))]
+      }, `root-${item.key}`))
     }, rootId ?? 'root')
   });
 });

package/lib/module/NavigationStack.js

@@ -3,6 +3,7 @@
 import { nanoid } from 'nanoid/non-secure';
 import { match as pathMatchFactory } from 'path-to-regexp';
 import qs from 'query-string';
+import React from 'react';
 export class NavigationStack {
   routes = [];
   children = [];
@@ -130,7 +131,18 @@ export class NavigationStack {
     return this.children.slice();
   }
   getRenderer() {
-    return () => null;
+    // eslint-disable-next-line consistent-this
+    const stackInstance = this;
+    return function NavigationStackRenderer(props) {
+      // Lazy require to avoid circular dependency (StackRenderer imports NavigationStack)
+      const {
+        StackRenderer
+      } = require('./StackRenderer');
+      return /*#__PURE__*/React.createElement(StackRenderer, {
+        stack: stackInstance,
+        appearance: props.appearance
+      });
+    };
   }
   seed() {
     const first = this.getFirstRoute();

package/lib/module/Router.js

@@ -3,6 +3,7 @@
 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';
 }
@@ -56,6 +57,9 @@ export class Router {
     }
     this.recomputeActiveRoute();
   }
+  isDebugEnabled() {
+    return this.debugEnabled;
+  }
   log(message, data) {
     if (this.debugEnabled) {
       if (data !== undefined) {
@@ -136,6 +140,72 @@ export class Router {
     }
     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.registry.find(r => r.routeId === 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
+      });
+      const newHistory = this.state.history.filter(item => item.stackId !== childStackId && item.key !== modalItem.key);
+      this.setState({
+        history: newHistory
+      });
+
+      // Clear child stack's history cache
+      this.stackHistories.delete(childStackId);
+    } else {
+      // Simple modal: just pop the modal item
+      this.applyHistoryChange('pop', modalItem);
+    }
+    this.recomputeActiveRoute();
+    this.emit(this.listeners);
+
+    // Sync URL on web
+    if (this.isWebEnv()) {
+      this.syncUrlAfterInternalPop(modalItem);
+    }
+  };
   getState = () => {
     return this.state;
   };
@@ -154,6 +224,14 @@ export class Router {
     }
     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);
@@ -172,9 +250,6 @@ export class Router {
   getRootStackId() {
     return this.root?.getId();
   }
-  getGlobalStackId() {
-    return undefined;
-  }
   subscribeRoot(listener) {
     this.rootListeners.add(listener);
     return () => this.rootListeners.delete(listener);
@@ -508,12 +583,23 @@ export class Router {
         }
         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;
@@ -862,7 +948,7 @@ export class Router {
   }
   buildRegistry() {
     this.registry.length = 0;
-    const addFromNode = (node, basePath) => {
+    const addFromNode = (node, basePath, inheritedOptions) => {
       const normalizedBasePath = this.normalizeBasePath(basePath);
       const baseSpecificity = this.computeBasePathSpecificity(normalizedBasePath);
       const routes = node.getNodeRoutes();
@@ -870,7 +956,16 @@ export class Router {
       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),
@@ -891,7 +986,7 @@ export class Router {
           },
           component: r.component,
           controller: r.controller,
-          options: r.options,
+          options: mergedOptions,
           stackId,
           childNode: r.childNode
         };
@@ -908,10 +1003,15 @@ export class Router {
           pathnamePattern: compiled.pathnamePattern,
           isWildcardPath: compiled.isWildcardPath,
           baseSpecificity: compiled.baseSpecificity,
-          stackId
+          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);
         }
       }
@@ -1172,12 +1272,21 @@ export class Router {
       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) {

package/lib/module/ScreenStack/ScreenStack.web.js

@@ -1,11 +1,11 @@
 "use strict";
 
-import { memo, useRef, useLayoutEffect, useMemo, useEffect, Children, isValidElement, Fragment } from 'react';
+import { memo, useRef, useLayoutEffect, useMemo, useEffect, Children, isValidElement, Fragment, useCallback, useContext } from 'react';
 import { useTransitionMap } from 'react-transition-state';
 import { ScreenStackItemsContext, ScreenStackAnimatingContext, useScreenStackConfig } from "./ScreenStackContext.js";
 import { getPresentationTypeClass, computeAnimationType } from "./animationHelpers.js";
+import { RouterContext } from "../RouterContext.js";
 import { jsx as _jsx } from "react/jsx-runtime";
-const devLog = (_, __) => {};
 const isScreenStackItemElement = child => {
   if (! /*#__PURE__*/isValidElement(child)) return false;
   const anyProps = child.props;
@@ -54,6 +54,12 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
     transitionTime = 250,
     animated = true
   } = props;
+  const router = useContext(RouterContext);
+  const debugEnabled = router?.isDebugEnabled() ?? false;
+  const devLog = useCallback((msg, data) => {
+    if (!debugEnabled) return;
+    console.log(msg, data !== undefined ? JSON.stringify(data) : '');
+  }, [debugEnabled]);
   devLog('[ScreenStack] Render', {
     transitionTime,
     animated,
@@ -81,7 +87,7 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
       stackChildrenLength: stackItems.length
     });
     return stackItems;
-  }, [children]);
+  }, [children, devLog]);
   const routeKeys = useMemo(() => {
     const keys = stackChildren.map(child => {
       const item = child.props.item;
@@ -89,7 +95,7 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
     });
     devLog('[ScreenStack] routeKeys', keys);
     return keys;
-  }, [stackChildren]);
+  }, [devLog, stackChildren]);
   const childMap = useMemo(() => {
     const map = new Map(childMapRef.current);
     for (const child of stackChildren) {
@@ -103,7 +109,7 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
       keys: Array.from(map.keys())
     });
     return map;
-  }, [stackChildren]);
+  }, [devLog, stackChildren]);
   const {
     stateMap,
     toggle,
@@ -166,7 +172,7 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
       exitingKeys
     });
     return result;
-  }, [routeKeys, stateMapEntries]);
+  }, [devLog, routeKeys, stateMapEntries]);
   const containerClassName = useMemo(() => {
     return 'screen-stack';
   }, []);
@@ -227,7 +233,7 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
     }
     lastDirectionRef.current = direction;
     devLog('[ScreenStack] === LIFECYCLE EFFECT END ===');
-  }, [routeKeys, direction, setItem, toggle, stateMapEntries, stateMap, animateFirstScreenAfterEmpty]);
+  }, [routeKeys, direction, setItem, toggle, stateMapEntries, stateMap, animateFirstScreenAfterEmpty, devLog]);
   useLayoutEffect(() => {
     devLog('[ScreenStack] === CLEANUP EFFECT START ===');
     const routeKeySet = new Set(routeKeys);
@@ -253,7 +259,7 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
       }
     }
     devLog('[ScreenStack] === CLEANUP EFFECT END ===');
-  }, [routeKeys, stateMapEntries, deleteItem]);
+  }, [routeKeys, stateMapEntries, deleteItem, devLog]);
   useEffect(() => {
     if (!isInitialMountRef.current) return;
     const hasMountedItem = stateMapEntries.some(([, st]) => st.isMounted);
@@ -271,7 +277,7 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
       isInitialMountRef.current = false;
       devLog('[ScreenStack] Initial mount completed');
     }
-  }, [stateMapEntries, routeKeys.length, animateFirstScreenAfterEmpty]);
+  }, [stateMapEntries, routeKeys.length, animateFirstScreenAfterEmpty, devLog]);
 
   // Clear suppression key once it is no longer the top screen (so it can animate normally as
   // a background when new screens are pushed).

package/lib/module/ScreenStack/animationHelpers.js

@@ -1,11 +1,14 @@
 "use strict";
 
+import { isModalLikePresentation } from "../types.js";
 export function getPresentationTypeClass(presentation) {
   switch (presentation) {
     case 'push':
       return 'push';
     case 'modal':
       return 'modal';
+    case 'modalRight':
+      return 'modal-right';
     case 'transparentModal':
       return 'transparent-modal';
     case 'containedModal':
@@ -40,7 +43,7 @@ export function computeAnimationType(_key, isInStack, isTop, direction, presenta
     return 'none';
   }
   const isEntering = isInStack && isTop;
-  const isModalLike = ['modal', 'transparentModal', 'containedModal', 'containedTransparentModal', 'fullScreenModal', 'formSheet', 'pageSheet', 'sheet'].includes(presentation);
+  const isModalLike = isModalLikePresentation(presentation);
   if (isModalLike) {
     if (!isInStack) {
       return getAnimationTypeForPresentation(presentation, false, direction);
@@ -48,7 +51,14 @@ export function computeAnimationType(_key, isInStack, isTop, direction, presenta
     if (isEntering) {
       return getAnimationTypeForPresentation(presentation, true, direction);
     }
-    return 'none';
+
+    // Modal-like screen that's NOT top (background) - animate like push
+    // This happens when navigating inside a modal stack
+    if (direction === 'forward') {
+      return 'push-background';
+    } else {
+      return 'pop-background';
+    }
   }
   if (!isInStack) {
     if (direction === 'forward') {

package/lib/module/ScreenStackItem/ScreenStackItem.js

@@ -17,6 +17,9 @@ export const ScreenStackItem = /*#__PURE__*/memo(({
     stackPresentation,
     ...screenProps
   } = item.options || {};
+
+  // On native, modalRight behaves as regular modal
+  const nativePresentation = stackPresentation === 'modalRight' ? 'modal' : stackPresentation;
   const route = {
     presentation: stackPresentation ?? 'push',
     params: item.params,
@@ -54,7 +57,7 @@ export const ScreenStackItem = /*#__PURE__*/memo(({
     style: StyleSheet.absoluteFill,
     contentStyle: appearance?.screen,
     headerConfig: headerConfig,
-    stackPresentation: stackPresentation,
+    stackPresentation: nativePresentation,
     stackAnimation: stackAnimation ?? item.options?.stackAnimation,
     children: /*#__PURE__*/_jsx(RouteLocalContext.Provider, {
       value: route,

package/lib/module/ScreenStackItem/ScreenStackItem.web.js

@@ -1,11 +1,11 @@
 "use strict";
 
 import { RouteLocalContext, useRouter } from "../RouterContext.js";
-import { memo, useMemo } from 'react';
+import { isModalLikePresentation } from "../types.js";
+import { memo, useMemo, useCallback } from 'react';
 import { StyleSheet, View } from 'react-native';
 import { useScreenStackItemsContext } from "../ScreenStack/ScreenStackContext.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-const devLog = (_, __) => {};
 export const ScreenStackItem = /*#__PURE__*/memo(({
   item,
   appearance,
@@ -13,6 +13,11 @@ export const ScreenStackItem = /*#__PURE__*/memo(({
 }) => {
   const itemsContext = useScreenStackItemsContext();
   const router = useRouter();
+  const debugEnabled = router.isDebugEnabled();
+  const devLog = useCallback((msg, data) => {
+    if (!debugEnabled) return;
+    console.log(msg, data !== undefined ? JSON.stringify(data) : '');
+  }, [debugEnabled]);
   const key = item.key;
   const itemState = itemsContext.items[key];
   const presentationType = itemState?.presentationType;
@@ -21,7 +26,7 @@ export const ScreenStackItem = /*#__PURE__*/memo(({
   const transitionStatus = itemState?.transitionStatus;
   const zIndex = itemState?.zIndex ?? 0;
   const presentation = item.options?.stackPresentation ?? 'push';
-  const isModalLike = ['modal', 'transparentModal', 'containedModal', 'containedTransparentModal', 'fullScreenModal', 'formSheet', 'pageSheet', 'sheet'].includes(presentation);
+  const isModalLike = isModalLikePresentation(presentation);
   const className = useMemo(() => {
     const classes = ['screen-stack-item'];
     if (presentationType) {
@@ -46,12 +51,20 @@ export const ScreenStackItem = /*#__PURE__*/memo(({
       className: classes.join(' ')
     });
     return classes.join(' ');
-  }, [presentationType, animationType, transitionStatus, phase, item.key, item.path]);
+  }, [presentationType, animationType, transitionStatus, phase, devLog, item.key, item.path]);
   const mergedStyle = useMemo(() => ({
     flex: 1,
     ...style,
     zIndex
   }), [style, zIndex]);
+  const modalContainerStyle = useMemo(() => {
+    if (!isModalLike || !item.options?.maxWidth) {
+      return undefined;
+    }
+    return {
+      maxWidth: `${item.options.maxWidth}px`
+    };
+  }, [isModalLike, item.options?.maxWidth]);
   const value = {
     presentation,
     params: item.params,
@@ -67,9 +80,10 @@ export const ScreenStackItem = /*#__PURE__*/memo(({
     className: className,
     children: [isModalLike && /*#__PURE__*/_jsx("div", {
       className: "stack-modal-overlay",
-      onClick: () => router.goBack()
+      onClick: () => router.dismiss()
     }), /*#__PURE__*/_jsx("div", {
       className: isModalLike ? 'stack-modal-container' : 'stack-screen-container',
+      style: modalContainerStyle,
       children: appearance?.screen ? /*#__PURE__*/_jsx(View, {
         style: [appearance?.screen, styles.flex],
         children: /*#__PURE__*/_jsx(RouteLocalContext.Provider, {

package/lib/module/SplitView/RenderSplitView.native.js

@@ -1,85 +1,78 @@
 "use strict";
 
-import { StackRenderer } from "../StackRenderer.js";
+import { ScreenStackItem } from "../ScreenStackItem/index.js";
+import { ScreenStack } from "../ScreenStack/index.js";
 import { SplitViewContext } from "./SplitViewContext.js";
 import { useRouter } from "../RouterContext.js";
-import { memo, useCallback, useSyncExternalStore } from 'react';
-import { StyleSheet, View } from 'react-native';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-const StackSliceRenderer = /*#__PURE__*/memo(({
-  stack,
-  appearance,
-  fallbackToFirstRoute
-}) => {
-  const router = useRouter();
-  const stackId = stack.getId();
-  const subscribe = useCallback(cb => router.subscribeStack(stackId, cb), [router, stackId]);
-  const get = useCallback(() => router.getStackHistory(stackId), [router, stackId]);
-  const history = useSyncExternalStore(subscribe, get, get);
-  let historyToRender = history;
-  if (fallbackToFirstRoute && historyToRender.length === 0) {
-    const first = stack.getFirstRoute();
-    if (first) {
-      const activePath = router.getActiveRoute()?.path;
-      historyToRender = [{
-        key: `splitview-seed-${stackId}`,
-        routeId: first.routeId,
-        component: first.component,
-        options: first.options,
-        stackId,
-        pattern: first.path,
-        path: activePath ?? first.path
-      }];
-    }
-  }
-  return /*#__PURE__*/_jsx(StackRenderer, {
-    appearance: appearance,
-    stack: stack,
-    history: historyToRender
-  });
-});
-StackSliceRenderer.displayName = 'SplitViewStackSliceRendererNative';
+import { memo, useCallback, useSyncExternalStore, useMemo } from 'react';
+import { StyleSheet } from 'react-native';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * On native (iPhone), SplitView renders primary and secondary screens
+ * in a SINGLE ScreenStack to get native push/pop animations.
+ *
+ * The combined history is: [...primaryHistory, ...secondaryHistory]
+ * This way, navigating from primary to secondary is a native push.
+ */
 export const RenderSplitView = /*#__PURE__*/memo(({
   splitView,
   appearance
 }) => {
   const router = useRouter();
+
+  // Subscribe to primary stack
+  const primaryId = splitView.primary.getId();
+  const subscribePrimary = useCallback(cb => router.subscribeStack(primaryId, cb), [router, primaryId]);
+  const getPrimary = useCallback(() => router.getStackHistory(primaryId), [router, primaryId]);
+  const primaryHistory = useSyncExternalStore(subscribePrimary, getPrimary, getPrimary);
+
+  // Subscribe to secondary stack
   const secondaryId = splitView.secondary.getId();
-  const subscribe = useCallback(cb => router.subscribeStack(secondaryId, cb), [router, secondaryId]);
-  const get = useCallback(() => router.getStackHistory(secondaryId), [router, secondaryId]);
-  const secondaryHistory = useSyncExternalStore(subscribe, get, get);
-  const hasSecondary = secondaryHistory.length > 0;
+  const subscribeSecondary = useCallback(cb => router.subscribeStack(secondaryId, cb), [router, secondaryId]);
+  const getSecondary = useCallback(() => router.getStackHistory(secondaryId), [router, secondaryId]);
+  const secondaryHistory = useSyncExternalStore(subscribeSecondary, getSecondary, getSecondary);
+
+  // Fallback: if primary is empty, seed with first route
+  const primaryHistoryToRender = useMemo(() => {
+    if (primaryHistory.length > 0) {
+      return primaryHistory;
+    }
+    const first = splitView.primary.getFirstRoute();
+    if (!first) return [];
+    const activePath = router.getActiveRoute()?.path;
+    return [{
+      key: `splitview-seed-${primaryId}`,
+      routeId: first.routeId,
+      component: first.component,
+      options: first.options,
+      stackId: primaryId,
+      pattern: first.path,
+      path: activePath ?? first.path
+    }];
+  }, [primaryHistory, splitView.primary, primaryId, router]);
+
+  // Combine histories: primary screens first, then secondary screens on top
+  // This gives native push animation when navigating from primary to secondary
+  const combinedHistory = useMemo(() => {
+    return [...primaryHistoryToRender, ...secondaryHistory];
+  }, [primaryHistoryToRender, secondaryHistory]);
+
+  // Use primary stack ID for the combined ScreenStack
+  // (secondary items will animate as if pushed onto this stack)
   return /*#__PURE__*/_jsx(SplitViewContext.Provider, {
     value: splitView,
-    children: /*#__PURE__*/_jsxs(View, {
+    children: /*#__PURE__*/_jsx(ScreenStack, {
       style: styles.container,
-      children: [/*#__PURE__*/_jsx(View, {
-        style: styles.primary,
-        pointerEvents: hasSecondary ? 'none' : 'auto',
-        children: /*#__PURE__*/_jsx(StackSliceRenderer, {
-          appearance: appearance,
-          stack: splitView.primary,
-          fallbackToFirstRoute: true
-        })
-      }), hasSecondary ? /*#__PURE__*/_jsx(View, {
-        style: styles.secondary,
-        children: /*#__PURE__*/_jsx(StackSliceRenderer, {
-          appearance: appearance,
-          stack: splitView.secondary
-        })
-      }) : null]
+      children: combinedHistory.map(item => /*#__PURE__*/_jsx(ScreenStackItem, {
+        appearance: appearance,
+        stackId: item.stackId,
+        item: item
+      }, `splitview-${item.key}`))
     })
   });
 });
 const styles = StyleSheet.create({
   container: {
     flex: 1
-  },
-  primary: {
-    flex: 1
-  },
-  secondary: {
-    ...StyleSheet.absoluteFillObject,
-    zIndex: 2
   }
 });

package/lib/module/TabBar/RenderTabBar.native.js

@@ -160,6 +160,7 @@ export const RenderTabBar = /*#__PURE__*/memo(({
   tabBar,
   appearance = {}
 }) => {
+  const router = useRouter();
   const subscribe = useCallback(cb => tabBar.subscribe(cb), [tabBar]);
   const snapshot = useSyncExternalStore(subscribe, tabBar.getState, tabBar.getState);
   const {
@@ -182,11 +183,82 @@ export const RenderTabBar = /*#__PURE__*/memo(({
   const onNativeFocusChange = useCallback(event => {
     const tabKey = event.nativeEvent.tabKey;
     const tabIndex = tabs.findIndex(route => route.tabKey === tabKey);
-    tabBar.onIndexChange(tabIndex);
-  }, [tabs, tabBar]);
+    if (tabIndex === -1) return;
+    const targetTab = tabs[tabIndex];
+    if (!targetTab) return;
+    const targetStack = tabBar.stacks[targetTab.tabKey];
+    const targetNode = tabBar.nodes[targetTab.tabKey];
+
+    // Update TabBar UI state
+    if (tabIndex !== index) {
+      tabBar.onIndexChange(tabIndex);
+    }
+
+    // Navigate to the target stack's first route if needed
+    if (targetStack) {
+      const stackId = targetStack.getId();
+      const stackHistory = router.getStackHistory(stackId);
+      // Only navigate if stack is empty (first visit)
+      if (stackHistory.length === 0) {
+        const firstRoute = targetStack.getFirstRoute();
+        if (firstRoute?.path) {
+          router.navigate(firstRoute.path);
+        }
+      }
+    } else if (targetNode) {
+      // For nodes like SplitView, check if we need to seed it
+      const nodeId = targetNode.getId?.();
+      if (nodeId) {
+        const nodeHistory = router.getStackHistory(nodeId);
+        if (nodeHistory.length === 0) {
+          const seed = targetNode.seed?.();
+          if (seed?.path) {
+            const prefix = targetTab.tabPrefix ?? '';
+            const fullPath = prefix && !seed.path.startsWith(prefix) ? `${prefix}${seed.path.startsWith('/') ? '' : '/'}${seed.path}` : seed.path;
+            router.navigate(fullPath);
+          }
+        }
+      }
+    }
+  }, [tabs, tabBar, index, router]);
   const onTabPress = useCallback(nextIndex => {
-    tabBar.onIndexChange(nextIndex);
-  }, [tabBar]);
+    const targetTab = tabs[nextIndex];
+    if (!targetTab) return;
+    const targetStack = tabBar.stacks[targetTab.tabKey];
+    const targetNode = tabBar.nodes[targetTab.tabKey];
+
+    // Update TabBar UI state
+    if (nextIndex !== index) {
+      tabBar.onIndexChange(nextIndex);
+    }
+
+    // Navigate to the target stack's first route if needed
+    if (targetStack) {
+      const stackId = targetStack.getId();
+      const stackHistory = router.getStackHistory(stackId);
+      // Only navigate if stack is empty (first visit)
+      if (stackHistory.length === 0) {
+        const firstRoute = targetStack.getFirstRoute();
+        if (firstRoute?.path) {
+          router.navigate(firstRoute.path);
+        }
+      }
+    } else if (targetNode) {
+      // For nodes like SplitView, check if we need to seed it
+      const nodeId = targetNode.getId?.();
+      if (nodeId) {
+        const nodeHistory = router.getStackHistory(nodeId);
+        if (nodeHistory.length === 0) {
+          const seed = targetNode.seed?.();
+          if (seed?.path) {
+            const prefix = targetTab.tabPrefix ?? '';
+            const fullPath = prefix && !seed.path.startsWith(prefix) ? `${prefix}${seed.path.startsWith('/') ? '' : '/'}${seed.path}` : seed.path;
+            router.navigate(fullPath);
+          }
+        }
+      }
+    }
+  }, [tabs, tabBar, index, router]);
   const containerProps = {
     tabBarBackgroundColor: backgroundColor,
     tabBarItemTitleFontFamily: title?.fontFamily,

package/lib/module/styles.css

@@ -48,7 +48,7 @@
 /* Show overlay only for modal-like presentations.
    IMPORTANT: use direct child (>) to avoid collapsing overlay from nested stacks,
    when modal ScreenStackItem is inside push ScreenStackItem container. */
-.screen-stack-item:not(.modal):not(.contained-modal):not(.fullscreen-modal):not(.formsheet):not(.pagesheet):not(.sheet)
+.screen-stack-item:not(.modal):not(.modal-right):not(.contained-modal):not(.fullscreen-modal):not(.formsheet):not(.pagesheet):not(.sheet)
   > .stack-modal-overlay {
   display: none;
 }
@@ -75,6 +75,7 @@
 
 /* Overlay in initial state — transparent */
 .screen-stack-item.modal.transition-preEnter > .stack-modal-overlay,
+.screen-stack-item.modal-right.transition-preEnter > .stack-modal-overlay,
 .screen-stack-item.contained-modal.transition-preEnter > .stack-modal-overlay,
 .screen-stack-item.fullscreen-modal.transition-preEnter > .stack-modal-overlay,
 .screen-stack-item.formsheet.transition-preEnter > .stack-modal-overlay,
@@ -88,6 +89,8 @@
 /* Overlay on enter — start animation */
 .screen-stack-item.modal.transition-entering > .stack-modal-overlay,
 .screen-stack-item.modal.phase-active.transition-preEnter > .stack-modal-overlay,
+.screen-stack-item.modal-right.transition-entering > .stack-modal-overlay,
+.screen-stack-item.modal-right.phase-active.transition-preEnter > .stack-modal-overlay,
 .screen-stack-item.contained-modal.transition-entering > .stack-modal-overlay,
 .screen-stack-item.contained-modal.phase-active.transition-preEnter > .stack-modal-overlay,
 .screen-stack-item.fullscreen-modal.transition-entering > .stack-modal-overlay,
@@ -106,6 +109,8 @@
 /* For modal-like in active / entered states — fully visible */
 .screen-stack-item.modal.phase-active > .stack-modal-overlay,
 .screen-stack-item.modal.transition-entered > .stack-modal-overlay,
+.screen-stack-item.modal-right.phase-active > .stack-modal-overlay,
+.screen-stack-item.modal-right.transition-entered > .stack-modal-overlay,
 .screen-stack-item.contained-modal.phase-active > .stack-modal-overlay,
 .screen-stack-item.contained-modal.transition-entered > .stack-modal-overlay,
 .screen-stack-item.fullscreen-modal.phase-active > .stack-modal-overlay,
@@ -124,6 +129,8 @@
 /* Overlay on modal-like close — disappearance animation */
 .screen-stack-item.modal.phase-exiting > .stack-modal-overlay,
 .screen-stack-item.modal.transition-exiting > .stack-modal-overlay,
+.screen-stack-item.modal-right.phase-exiting > .stack-modal-overlay,
+.screen-stack-item.modal-right.transition-exiting > .stack-modal-overlay,
 .screen-stack-item.contained-modal.phase-exiting > .stack-modal-overlay,
 .screen-stack-item.contained-modal.transition-exiting > .stack-modal-overlay,
 .screen-stack-item.fullscreen-modal.phase-exiting > .stack-modal-overlay,
@@ -153,6 +160,7 @@
 
 /* Modal-like content container always above overlay */
 .screen-stack-item.modal .stack-modal-container,
+.screen-stack-item.modal-right .stack-modal-container,
 .screen-stack-item.contained-modal .stack-modal-container,
 .screen-stack-item.fullscreen-modal .stack-modal-container,
 .screen-stack-item.formsheet .stack-modal-container,
@@ -202,6 +210,7 @@
 
 /* IMPORTANT: modal elements should not move like regular screens */
 .screen-stack > .screen-stack-item.modal,
+.screen-stack > .screen-stack-item.modal-right,
 .screen-stack > .screen-stack-item.sheet {
   transform: translate3d(0, 0, 0) !important;
 }
@@ -229,7 +238,12 @@
 
 /* PUSH BACKGROUND - background screen shifts left */
 /* Important: use !important to override general rules for inactive */
-.screen-stack-item.push.push-background {
+.screen-stack-item.push.push-background,
+.screen-stack-item.modal.push-background,
+.screen-stack-item.modal-right.push-background,
+.screen-stack-item.sheet.push-background,
+.screen-stack-item.formsheet.push-background,
+.screen-stack-item.pagesheet.push-background {
   transform: translateX(-25%) !important;
   transition:
     transform 300ms cubic-bezier(0.22, 0.61, 0.36, 1),
@@ -238,7 +252,12 @@
 
 /* POP BACKGROUND - background screen on pop stays at -25% */
 /* Background elements on pop get pop-background instead of none, to preserve -25% position */
-.screen-stack-item.push.pop-background {
+.screen-stack-item.push.pop-background,
+.screen-stack-item.modal.pop-background,
+.screen-stack-item.modal-right.pop-background,
+.screen-stack-item.sheet.pop-background,
+.screen-stack-item.formsheet.pop-background,
+.screen-stack-item.pagesheet.pop-background {
   transform: translateX(-25%) !important;
   /* Don't set transition, so element stays in place without animation */
   filter: none;
@@ -294,7 +313,8 @@
 /* ==================== MOBILE MODAL (<= 639px) — bottom sheet ==================== */
 @media (max-width: 639px) {
   /* Inner container for modal — bottom sheet full width with top border radius */
-  .screen-stack-item.modal .stack-modal-container {
+  .screen-stack-item.modal .stack-modal-container,
+  .screen-stack-item.modal-right .stack-modal-container {
     width: 100%;
     margin: 0;
     border-radius: 0;
@@ -311,19 +331,23 @@
   }
 
   /* MODAL ENTER - modal enters (bottom to top) */
-  .screen-stack-item.modal.modal-enter.transition-preEnter .stack-modal-container {
+  .screen-stack-item.modal.modal-enter.transition-preEnter .stack-modal-container,
+  .screen-stack-item.modal-right.modal-right-enter.transition-preEnter .stack-modal-container {
     transform: translateY(100%);
     filter: none;
   }
 
   .screen-stack-item.modal.modal-enter.transition-entering .stack-modal-container,
-  .screen-stack-item.modal.modal-enter.transition-entered .stack-modal-container {
+  .screen-stack-item.modal.modal-enter.transition-entered .stack-modal-container,
+  .screen-stack-item.modal-right.modal-right-enter.transition-entering .stack-modal-container,
+  .screen-stack-item.modal-right.modal-right-enter.transition-entered .stack-modal-container {
     transform: translateY(0);
     filter: none;
   }
 
   /* MODAL EXIT - modal closes (exits downward) */
-  .screen-stack-item.modal.modal-exit.transition-exiting .stack-modal-container {
+  .screen-stack-item.modal.modal-exit.transition-exiting .stack-modal-container,
+  .screen-stack-item.modal-right.modal-right-exit.transition-exiting .stack-modal-container {
     transform: translateY(100%);
     filter: none;
     transition:
@@ -370,10 +394,57 @@
   }
 }
 
-/* ==================== DESKTOP MODAL (>= 640px) — sheet on right ==================== */
+/* ==================== DESKTOP MODAL (>= 640px) — centered card ==================== */
 @media (min-width: 640px) {
-  /* Inner container for modal — right sheet 393px, with margin and border radius */
+  /* Inner container for modal — centered card 600px width, 75% height */
   .screen-stack-item.modal .stack-modal-container {
+    width: 600px;
+    max-width: calc(100% - 48px);
+    height: 75vh;
+    max-height: calc(100% - 48px);
+    margin: auto; /* center in parent */
+    border-radius: 38px;
+    overflow: hidden;
+    background: #fff;
+
+    transform: translateY(0);
+    transition:
+      transform 300ms cubic-bezier(0.22, 0.61, 0.36, 1),
+      filter 300ms cubic-bezier(0.22, 0.61, 0.36, 1);
+  }
+
+  /* Center the modal container using flexbox on parent */
+  .screen-stack-item.modal {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  /* MODAL ENTER - modal enters (bottom to center) */
+  .screen-stack-item.modal.modal-enter.transition-preEnter .stack-modal-container {
+    transform: translateY(100vh);
+    filter: none;
+  }
+
+  .screen-stack-item.modal.modal-enter.transition-entering .stack-modal-container,
+  .screen-stack-item.modal.modal-enter.transition-entered .stack-modal-container {
+    transform: translateY(0);
+    filter: none;
+  }
+
+  /* MODAL EXIT - modal closes (exits downward) */
+  .screen-stack-item.modal.modal-exit.transition-exiting .stack-modal-container {
+    transform: translateY(100vh);
+    filter: none;
+    transition:
+      transform 300ms cubic-bezier(0.22, 0.61, 0.36, 1),
+      filter 300ms cubic-bezier(0.22, 0.61, 0.36, 1);
+  }
+
+  /* ==================== MODAL-RIGHT — slide from right (previous modal behavior) ==================== */
+
+  /* Inner container for modal-right — right sheet 393px */
+  .screen-stack-item.modal-right .stack-modal-container {
     width: 393px;
     max-width: calc(100% - 36px);
     height: calc(100% - 36px);
@@ -381,7 +452,7 @@
     margin-left: auto; /* align to right edge */
     border-radius: 16px;
     overflow: hidden;
-    background: #fff; /* or var(--modal-bg) */
+    background: #fff;
 
     transform: translateX(0);
     transition:
@@ -389,20 +460,20 @@
       filter 300ms cubic-bezier(0.22, 0.61, 0.36, 1);
   }
 
-  /* MODAL ENTER - modal enters (right to left) */
-  .screen-stack-item.modal.modal-enter.transition-preEnter .stack-modal-container {
+  /* MODAL-RIGHT ENTER - modal enters (right to left) */
+  .screen-stack-item.modal-right.modal-right-enter.transition-preEnter .stack-modal-container {
     transform: translateX(100%);
     filter: none;
   }
 
-  .screen-stack-item.modal.modal-enter.transition-entering .stack-modal-container,
-  .screen-stack-item.modal.modal-enter.transition-entered .stack-modal-container {
+  .screen-stack-item.modal-right.modal-right-enter.transition-entering .stack-modal-container,
+  .screen-stack-item.modal-right.modal-right-enter.transition-entered .stack-modal-container {
     transform: translateX(0);
     filter: none;
   }
 
-  /* MODAL EXIT - modal closes (exits to right) */
-  .screen-stack-item.modal.modal-exit.transition-exiting .stack-modal-container {
+  /* MODAL-RIGHT EXIT - modal closes (exits to right) */
+  .screen-stack-item.modal-right.modal-right-exit.transition-exiting .stack-modal-container {
     transform: translateX(100%);
     filter: none;
     transition:
@@ -439,6 +510,10 @@
   .screen-stack:has(> .screen-stack-item.modal.phase-active)
     > .screen-stack-item.push.phase-inactive,
   .screen-stack:has(> .screen-stack-item.modal.phase-active)
+    > .screen-stack-item.push.phase-inactive.transition-entered,
+  .screen-stack:has(> .screen-stack-item.modal-right.phase-active)
+    > .screen-stack-item.push.phase-inactive,
+  .screen-stack:has(> .screen-stack-item.modal-right.phase-active)
     > .screen-stack-item.push.phase-inactive.transition-entered {
     transform: translate3d(0, 0, 0) !important;
     filter: none;

package/lib/module/types.js

@@ -1,3 +1,13 @@
 "use strict";
 
-export {};
+/**
+ * Presentations that behave like modals (overlay on top of content).
+ */
+export const MODAL_LIKE_PRESENTATIONS = new Set(['modal', 'modalRight', 'transparentModal', 'containedModal', 'containedTransparentModal', 'fullScreenModal', 'formSheet', 'pageSheet', 'sheet']);
+
+/**
+ * Check if a presentation type is modal-like (renders as overlay).
+ */
+export function isModalLikePresentation(presentation) {
+  return presentation !== undefined && MODAL_LIKE_PRESENTATIONS.has(presentation);
+}

package/lib/typescript/src/Navigation.d.ts

@@ -4,6 +4,14 @@ interface NavigationProps {
     router: Router;
     appearance?: NavigationAppearance;
 }
+/**
+ * Navigation component renders the root and global stacks.
+ *
+ * Modal stacks (NavigationStack added via addModal) are rendered as regular ScreenStackItems
+ * with their component being the StackRenderer that subscribes to its own stack history.
+ * This creates a clean recursive structure: stacks render their items, nested stacks
+ * (via childNode) render their own items through StackRenderer.
+ */
 export declare const Navigation: import("react").NamedExoticComponent<NavigationProps>;
 export {};
 //# sourceMappingURL=Navigation.d.ts.map

package/lib/typescript/src/NavigationStack.d.ts

@@ -1,4 +1,5 @@
 import type { ScreenOptions } from './types';
+import React from 'react';
 import { type MixedComponent } from './createController';
 import type { NavigationNode, NodeRoute, NodeChild } from './navigationNode';
 type BuiltRoute = NodeRoute;
@@ -17,8 +18,8 @@ export declare class NavigationStack implements NavigationNode {
     private log;
     getId(): string;
     addScreen(pathPattern: string, mixedComponent: MixedComponent | NavigationNode, options?: ScreenOptions): NavigationStack;
-    addModal(path: string, mixedComponent: MixedComponent, options?: ScreenOptions): NavigationStack;
-    addSheet(path: string, mixedComponent: MixedComponent, options?: ScreenOptions): NavigationStack;
+    addModal(path: string, mixedComponent: MixedComponent | NavigationNode, options?: ScreenOptions): NavigationStack;
+    addSheet(path: string, mixedComponent: MixedComponent | NavigationNode, options?: ScreenOptions): NavigationStack;
     addStack(prefixOrStack: string | NavigationStack, maybeStack?: NavigationStack): NavigationStack;
     getChildren(): ChildNode[];
     getRoutes(): BuiltRoute[];

package/lib/typescript/src/Router.d.ts

@@ -34,6 +34,7 @@ export declare class Router {
     private suppressHistorySyncCount;
     private navigationToken;
     constructor(config: RouterConfig);
+    isDebugEnabled(): boolean;
     private log;
     navigate: (path: string) => void;
     replace: (path: string, dedupe?: boolean) => void;
@@ -48,12 +49,22 @@ export declare class Router {
     registerSheetDismisser: (key: string, dismisser: () => void) => void;
     unregisterSheetDismisser: (key: string) => void;
     goBack: () => void;
+    /**
+     * 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: () => void;
     getState: () => RouterState;
     subscribe(listener: Listener): () => void;
     getStackHistory: (stackId?: string) => HistoryItem[];
+    /**
+     * Returns all history items in navigation order.
+     * Useful for rendering all screens including modal stacks.
+     */
+    getFullHistory: () => HistoryItem[];
     subscribeStack: (stackId: string, cb: Listener) => (() => void);
     getRootStackId(): string | undefined;
-    getGlobalStackId(): string | undefined;
     subscribeRoot(listener: Listener): () => void;
     private emitRootChange;
     getRootTransition(): RootTransition | undefined;

package/lib/typescript/src/ScreenStack/ScreenStackContext.d.ts

@@ -1,7 +1,7 @@
 import type { ScreenStackItemPhase } from '../ScreenStackItem/ScreenStackItem.types';
 import type { TransitionStatus } from 'react-transition-state';
-export type PresentationTypeClass = 'push' | 'modal' | 'transparent-modal' | 'contained-modal' | 'contained-transparent-modal' | 'fullscreen-modal' | 'formsheet' | 'pagesheet' | 'sheet';
-export type AnimationType = 'push-enter' | 'push-exit' | 'push-background' | 'pop-enter' | 'pop-exit' | 'pop-background' | 'modal-enter' | 'modal-exit' | 'transparent-modal-enter' | 'transparent-modal-exit' | 'contained-modal-enter' | 'contained-modal-exit' | 'fullscreen-modal-enter' | 'fullscreen-modal-exit' | 'formsheet-enter' | 'formsheet-exit' | 'pagesheet-enter' | 'pagesheet-exit' | 'sheet-enter' | 'sheet-exit' | 'no-animate' | 'none';
+export type PresentationTypeClass = 'push' | 'modal' | 'modal-right' | 'transparent-modal' | 'contained-modal' | 'contained-transparent-modal' | 'fullscreen-modal' | 'formsheet' | 'pagesheet' | 'sheet';
+export type AnimationType = 'push-enter' | 'push-exit' | 'push-background' | 'pop-enter' | 'pop-exit' | 'pop-background' | 'modal-enter' | 'modal-exit' | 'modal-right-enter' | 'modal-right-exit' | 'transparent-modal-enter' | 'transparent-modal-exit' | 'contained-modal-enter' | 'contained-modal-exit' | 'fullscreen-modal-enter' | 'fullscreen-modal-exit' | 'formsheet-enter' | 'formsheet-exit' | 'pagesheet-enter' | 'pagesheet-exit' | 'sheet-enter' | 'sheet-exit' | 'no-animate' | 'none';
 export type ScreenStackItemState = {
     presentationType: PresentationTypeClass;
     animationType: AnimationType;

package/lib/typescript/src/SplitView/RenderSplitView.native.d.ts

@@ -4,5 +4,12 @@ export interface RenderSplitViewProps {
     splitView: SplitView;
     appearance?: NavigationAppearance;
 }
+/**
+ * On native (iPhone), SplitView renders primary and secondary screens
+ * in a SINGLE ScreenStack to get native push/pop animations.
+ *
+ * The combined history is: [...primaryHistory, ...secondaryHistory]
+ * This way, navigating from primary to secondary is a native push.
+ */
 export declare const RenderSplitView: import("react").NamedExoticComponent<RenderSplitViewProps>;
 //# sourceMappingURL=RenderSplitView.native.d.ts.map

package/lib/typescript/src/types.d.ts

@@ -1,6 +1,14 @@
 import type { ColorValue, StyleProp, ViewStyle, TextStyle } from 'react-native';
 import type { BottomTabsScreenProps, ScreenProps as RNSScreenProps, ScreenStackHeaderConfigProps, TabBarItemLabelVisibilityMode, TabBarMinimizeBehavior } from 'react-native-screens';
-export type StackPresentationTypes = 'push' | 'modal' | 'transparentModal' | 'containedModal' | 'containedTransparentModal' | 'fullScreenModal' | 'formSheet' | 'pageSheet' | 'sheet';
+export type StackPresentationTypes = 'push' | 'modal' | 'modalRight' | 'transparentModal' | 'containedModal' | 'containedTransparentModal' | 'fullScreenModal' | 'formSheet' | 'pageSheet' | 'sheet';
+/**
+ * Presentations that behave like modals (overlay on top of content).
+ */
+export declare const MODAL_LIKE_PRESENTATIONS: ReadonlySet<StackPresentationTypes>;
+/**
+ * Check if a presentation type is modal-like (renders as overlay).
+ */
+export declare function isModalLikePresentation(presentation: StackPresentationTypes | undefined): boolean;
 export type TabItem = Omit<BottomTabsScreenProps, 'isFocused' | 'children'>;
 export type NavigationState<Route extends TabItem> = {
     index: number;
@@ -29,6 +37,11 @@ export type ScreenOptions = Partial<Omit<RNSScreenProps, 'stackPresentation'>> &
      * Useful for secondary stacks in split-view / overlays.
      */
     allowRootPop?: boolean;
+    /**
+     * Maximum width for modal presentation on web (in pixels).
+     * Only applies to modal-like presentations on web platform.
+     */
+    maxWidth?: number;
 };
 export type HistoryItem = {
     key: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigmela/router",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "React Native Router",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",