@sigmela/router 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this package are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
 [semantic versioning](https://semver.org/).
 
+## 0.6.0
+
+### Added
+
+- `Router.Protected` supports an undecided guard: `when` accepts `'pending'`
+  (and `undefined`), which holds the matched URL and renders the new `pending`
+  node instead of redirecting. Apps that gate routes on asynchronously loaded
+  context can now keep deep links through boot; previously the only way to say
+  "not yet" was `false`, which redirected the visitor away.
+- `RouterGuardState` is exported for typing guard values.
+
+### Notes
+
+- Existing `when={boolean}` guards are unaffected: `true` renders, `false`
+  redirects, exactly as before.
+
 ## 0.5.0
 
 ### Added

package/README.md

@@ -110,6 +110,38 @@ function ProductDetail({ product }) {
 }
 ```
 
+### Guards that are not decided yet
+
+`Router.Protected` answers three states, not two. A guard whose `when` is
+`false` redirects; a guard that is still resolving — `'pending'`, or
+`undefined` so `when={user?.isAdmin}` works before the user loads — **holds the
+URL** and renders its `pending` node instead of the subtree:
+
+```tsx
+<Router.Protected
+  when={contextLoading ? 'pending' : isReady}
+  redirectTo="/home"
+  pending={<AppLoadingScreen />}
+>
+  <Router.Screen path="/catalog/products" element={ProductsScreen} />
+</Router.Protected>
+```
+
+This is what keeps deep links alive while an app boots. Without it a guard has
+to answer `false` while it is still loading, which redirects the visitor away
+from the URL they opened — and a catch-all loading screen cannot rescue it,
+because the guarded route is the more specific match.
+
+Semantics worth knowing:
+
+- Guards resolve outside-in; the first one that is not `true` decides. An
+  undecided outer guard defers a later denial, since it is not yet known
+  whether that guard would even be reached.
+- A denial always wins immediately, including on a screen that is already
+  open — revoking access redirects right away.
+- A guard that turns undecided again while its screen is on-screen keeps that
+  screen rendered rather than flashing the pending node.
+
 ## Hooks
 
 | Hook | Returns |

package/dist/Router.d.ts

@@ -10,6 +10,13 @@ export interface RouterNavigateOptions {
 export type RouterNavigateFunction = (to: string | number, options?: RouterNavigateOptions) => void;
 export type RouterReplaceFunction = (to: string, options?: RouterNavigateOptions) => void;
 type RouterGuardValue<T> = T | ((props: RouterRouteRenderProps) => T);
+/**
+ * A guard answers one of three things: allowed, denied, or not decided yet.
+ * `'pending'` (and `undefined`, so `when={user?.isAdmin}` works before the user
+ * loads) holds the URL and renders the guard's `pending` node — it must not
+ * redirect, or every deep link would be lost while the app boots.
+ */
+export type RouterGuardState = boolean | 'pending';
 export type RouterSplitPane = 'primary' | 'secondary';
 export interface RouterRouteRenderProps {
     params: DefaultParams;
@@ -124,8 +131,10 @@ export interface RouterSplitViewProps extends RouterRouteProps {
 }
 export type RouterSplitViewSlotProps = RouterRouteProps;
 export interface RouterProtectedProps extends RouterRouteProps {
-    when: RouterGuardValue<boolean>;
+    when: RouterGuardValue<RouterGuardState | undefined>;
     redirectTo: RouterGuardValue<string>;
+    /** Rendered instead of the subtree while `when` is undecided. */
+    pending?: ReactNode;
 }
 export interface RouterRedirectProps extends RouterRouteProps {
     to: RouterGuardValue<string>;

package/dist/Router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Router.d.ts","sourceRoot":"","sources":["../src/Router.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"Router.d.ts","sourceRoot":"","sources":["../src/Router.tsx"],"names":[],"mappings":"AAAA,OAAO,EAeL,KAAK,aAAa,EAElB,KAAK,WAAW,EAChB,KAAK,GAAG,EAER,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,EAOL,KAAK,aAAa,EAEnB,MAAM,QAAQ,CAAC;AAShB,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,cAAc,CAAC;AAGtB,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAC3D,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,mBAAmB,CAAC;AAgBjE,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AASD,MAAM,MAAM,sBAAsB,GAAG,CACnC,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,OAAO,CAAC,EAAE,qBAAqB,KAC5B,IAAI,CAAC;AACV,MAAM,MAAM,qBAAqB,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAC1F,KAAK,gBAAgB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,sBAAsB,KAAK,CAAC,CAAC,CAAC;AACtE;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,SAAS,CAAC;AACnD,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,WAAW,CAAC;AA6BtD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,iBAAiB,CAAC;IAChC,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAwB,SAAQ,sBAAsB;IACrE,YAAY,EAAE,eAAe,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,gBAAgB,GACxB,gBAAgB,GAChB,iBAAiB,GACjB,mBAAmB,CAAC;AAExB,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,eAAe,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IACnC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,KAAK,mBAAmB,GAAG,SAAS,GAAG,CAAC,CAAC,KAAK,EAAE,sBAAsB,KAAK,SAAS,CAAC,CAAC;AAEtF,KAAK,kBAAkB,GAAG,SAAS,GAAG,WAAW,CAAC;AAElD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,sBAAsB,KAAK,MAAM,CAAC,CAAC;IAChE,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAC7C,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC;AAED,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACzD,2EAA2E;IAC3E,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,wBAAyB,SAAQ,gBAAgB;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,wBAAwB,GAAG,gBAAgB,CAAC;AAExD,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D,IAAI,EAAE,gBAAgB,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;IACrD,UAAU,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACrC,iEAAiE;IACjE,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,EAAE,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,sBAAsB,CAAC;IACjC,mFAAmF;IACnF,OAAO,EAAE,qBAAqB,CAAC;IAC/B,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAUD,UAAU,eAAe;IACvB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AA+yDD,wBAAgB,QAAQ,IAAI,uBAAuB,CAMlD;AAED,wBAAgB,eAAe,IAAI,uBAAuB,CAEzD;AAED,wBAAgB,SAAS,CAAC,OAAO,SAAS,aAAa,GAAG,aAAa,KAAK,OAAO,CAElF;AAED,wBAAgB,eAAe,IAAI,eAAe,CAEjD;AAED,wBAAgB,eAAe,CAAC,MAAM,GAAG,OAAO,KAAK,MAAM,CAE1D;AAED,wBAAgB,SAAS,IAAI,SAAS,CA8BrC;AAED,wBAAgB,SAAS,IAAI,eAAe,CAM3C;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,0GAA0G;IAC1G,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,6GAA6G;IAC7G,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,wBAAgB,eAAe,IAAI,eAAe,CAMjD;AAk6DD,iBAAS,UAAU,CAAC,KAAK,EAAE,eAAe,2CAUzC;AAiCD,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;CAcjB,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Router, useCurrentModal, useCurrentRoute, useDrawer, useHistoryState, useParams, useRoute, useRouter, useSearchParams, type CurrentModalApi, type RouterDrawerApi, type RouterDrawerGroup, type RouterDrawerGroupProps, type RouterDrawerItem, type RouterDrawerItemProps, type RouterDrawerNode, type RouterDrawerSection, type RouterDrawerSectionProps, type RouterDrawerProps, type RouterApi, type RouterNavigateFunction, type RouterReplaceFunction, type RouterRedirectProps, type RouterRouteContextValue, type RouterRouteLayoutProps, type RouterProtectedProps, type RouterRouteRenderProps, type RouterScreenAnimation, type RouterSplitPane, type RouterSplitViewProps, type RouterSplitViewSlotProps, type RouterTabBarTab, } from './Router';
+export { Router, useCurrentModal, useCurrentRoute, useDrawer, useHistoryState, useParams, useRoute, useRouter, useSearchParams, type CurrentModalApi, type RouterDrawerApi, type RouterDrawerGroup, type RouterDrawerGroupProps, type RouterDrawerItem, type RouterDrawerItemProps, type RouterDrawerNode, type RouterDrawerSection, type RouterDrawerSectionProps, type RouterDrawerProps, type RouterGuardState, type RouterApi, type RouterNavigateFunction, type RouterReplaceFunction, type RouterRedirectProps, type RouterRouteContextValue, type RouterRouteLayoutProps, type RouterProtectedProps, type RouterRouteRenderProps, type RouterScreenAnimation, type RouterSplitPane, type RouterSplitViewProps, type RouterSplitViewSlotProps, type RouterTabBarTab, } from './Router';
 export type { RouterShellMode } from './types';
 export type { RouterOverlayLayout } from './types';
 export { Modal, ModalFrame, Sheet, SheetFrame, useModalSwipeTarget, useSheetDragEngine, sheetDragStartsInInteractiveControl, sheetScrollAtTop, type SheetDragUpdate, } from './components';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,eAAe,EACf,eAAe,EACf,SAAS,EACT,eAAe,EACf,SAAS,EACT,QAAQ,EACR,SAAS,EACT,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EACL,KAAK,EACL,UAAU,EACV,KAAK,EACL,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,mCAAmC,EACnC,gBAAgB,EAChB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,eAAe,EACf,eAAe,EACf,SAAS,EACT,eAAe,EACf,SAAS,EACT,QAAQ,EACR,SAAS,EACT,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EACL,KAAK,EACL,UAAU,EACV,KAAK,EACL,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,mCAAmC,EACnC,gBAAgB,EAChB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1235,7 +1235,8 @@ function compileStackRoutes(children, parentPath, parentId = "root", inheritedGu
       const guard = {
         id: props.id ?? routeId,
         when: child.props.when,
-        redirectTo: child.props.redirectTo
+        redirectTo: child.props.redirectTo,
+        pending: child.props.pending
       };
       if (routeChildren.length > 0) {
         routes.push(
@@ -1279,10 +1280,11 @@ function compileStackRoutes(children, parentPath, parentId = "root", inheritedGu
       const overlayFlow = {
         id: `${routeId}/overlay-flow`,
         kind: presentation,
-        routes: flowRoutes
+        routes: flowRoutes,
+        entries: []
       };
       for (const flowRoute of flowRoutes) {
-        routes.push({
+        const entryRoute = {
           id: `${overlayFlow.id}:${flowRoute.id}`,
           path: flowRoute.path,
           presentation,
@@ -1294,7 +1296,9 @@ function compileStackRoutes(children, parentPath, parentId = "root", inheritedGu
           fallback: flowRoute.fallback ?? props.fallback,
           childRoute: flowRoute,
           overlayFlow
-        });
+        };
+        overlayFlow.entries.push(entryRoute);
+        routes.push(entryRoute);
       }
       return;
     }
@@ -1634,16 +1638,25 @@ function routeRenderPropsForMatch(pathname, search, historyState, match) {
 function resolveGuardValue(value, props) {
   return typeof value === "function" ? value(props) : value;
 }
-function guardRedirectForMatch(match, pathname, search, historyState) {
+var GUARD_ALLOW = { status: "allow" };
+function resolveRouteGuard(match, pathname, search, historyState) {
   const props = routeRenderPropsForMatch(pathname, search, historyState, match);
   for (const guard of match.route.guards) {
-    if (resolveGuardValue(guard.when, props)) continue;
-    return resolveGuardValue(guard.redirectTo, props);
+    const value = resolveGuardValue(guard.when, props);
+    if (value === true) continue;
+    if (value === false) {
+      return { status: "redirect", to: resolveGuardValue(guard.redirectTo, props) };
+    }
+    return { status: "pending", element: guard.pending ?? null };
   }
   if (match.route.redirectTo) {
-    return resolveGuardValue(match.route.redirectTo, props);
+    return { status: "redirect", to: resolveGuardValue(match.route.redirectTo, props) };
   }
-  return null;
+  return GUARD_ALLOW;
+}
+function guardRedirectForMatch(match, pathname, search, historyState) {
+  const outcome = resolveRouteGuard(match, pathname, search, historyState);
+  return outcome.status === "redirect" ? outcome.to : null;
 }
 var PUSH_PRESENTATIONS = /* @__PURE__ */ new Set(["push"]);
 var OVERLAY_PRESENTATIONS = /* @__PURE__ */ new Set(["modal", "sheet"]);
@@ -3020,6 +3033,34 @@ function modalFlowScreenFromMatch(match, pathname, search, state, historyIndex,
     )
   };
 }
+function overlayFlowRootPathname(rootPath, pathname) {
+  const depth = rootPath.split("/").filter(Boolean).length;
+  const segments = pathname.split("/").filter(Boolean);
+  if (segments.length <= depth) return pathname;
+  return `/${segments.slice(0, depth).join("/")}`;
+}
+function seedModalFlowScreens(match, pathname, search, state) {
+  const target = modalFlowScreenFromMatch(match, pathname, search, state, 0, "push");
+  if (!target) return void 0;
+  const flow = match.route.overlayFlow;
+  const rootEntry = flow?.entries[0];
+  const rootRoute = flow?.routes[0];
+  if (!flow || !rootEntry || !rootRoute || rootRoute === match.route.childRoute) {
+    return [target];
+  }
+  const rootScreen = {
+    overlayRoute: rootEntry,
+    route: rootRoute,
+    params: match.params,
+    pathname: rootRoute.path ? overlayFlowRootPathname(rootRoute.path, pathname) : pathname,
+    search,
+    historyState: stateWithHistoryIndex(state, 0, createRouterId(), "push")
+  };
+  return [
+    rootScreen,
+    { ...target, historyState: stateWithHistoryIndex(state, 1, createRouterId(), "push") }
+  ];
+}
 function RouterRuntime({
   children,
   fallback,
@@ -3058,11 +3099,27 @@ function RouterRuntime({
     };
   }, [shell]);
   const searchPath = search ? `?${search}` : "";
-  const guardRedirect = useMemo(
-    () => rawMatch ? guardRedirectForMatch(rawMatch, pathname, searchPath, historyState) : null,
+  const guardOutcome = useMemo(
+    () => rawMatch ? resolveRouteGuard(rawMatch, pathname, searchPath, historyState) : null,
     [historyState, pathname, rawMatch, searchPath]
   );
-  const match = guardRedirect ? null : rawMatch;
+  const guardRedirect = guardOutcome?.status === "redirect" ? guardOutcome.to : null;
+  const matchedRoute = guardRedirect ? null : rawMatch;
+  const match = useMemo(() => {
+    if (!matchedRoute) return null;
+    if (guardOutcome?.status !== "pending") return matchedRoute;
+    return {
+      ...matchedRoute,
+      route: {
+        ...matchedRoute.route,
+        element: guardOutcome.element,
+        elementType: void 0,
+        component: void 0,
+        layout: void 0,
+        overlayLayout: void 0
+      }
+    };
+  }, [guardOutcome, matchedRoute]);
   useLayoutEffect(() => {
     if (!guardRedirect) return;
     const target = parseNavigationTarget(guardRedirect, pathname);
@@ -3381,22 +3438,21 @@ function RouterRuntime({
         if (updateActiveModalFlow(overlayMatch, target, overlayState, "push")) {
           return;
         }
-        const initialFlowScreen = modalFlowScreenFromMatch(
+        const initialFlowScreens = seedModalFlowScreens(
           overlayMatch,
           target.pathname,
           target.search,
-          overlayState,
-          0,
-          "push"
+          overlayState
         );
+        const activeFlowScreen = initialFlowScreens?.[initialFlowScreens.length - 1];
         pushModalEntry({
           kind: overlayMatch.route.presentation,
           route: overlayMatch.route,
           params: overlayMatch.params,
           pathname: target.pathname,
           search: target.search,
-          historyState: initialFlowScreen?.historyState ?? overlayState,
-          flowScreens: initialFlowScreen ? [initialFlowScreen] : void 0
+          historyState: activeFlowScreen?.historyState ?? overlayState,
+          flowScreens: initialFlowScreens
         });
         return;
       }
@@ -3451,14 +3507,13 @@ function RouterRuntime({
         if (updateActiveModalFlow(overlayMatch, target, overlayState, "replace")) {
           return;
         }
-        const initialFlowScreen = modalFlowScreenFromMatch(
+        const initialFlowScreens = seedModalFlowScreens(
           overlayMatch,
           target.pathname,
           target.search,
-          overlayState,
-          0,
-          "replace"
+          overlayState
         );
+        const activeFlowScreen = initialFlowScreens?.[initialFlowScreens.length - 1];
         pushModalEntry(
           {
             kind: overlayMatch.route.presentation,
@@ -3466,8 +3521,8 @@ function RouterRuntime({
             params: overlayMatch.params,
             pathname: target.pathname,
             search: target.search,
-            historyState: initialFlowScreen?.historyState ?? overlayState,
-            flowScreens: initialFlowScreen ? [initialFlowScreen] : void 0
+            historyState: activeFlowScreen?.historyState ?? overlayState,
+            flowScreens: initialFlowScreens
           },
           true
         );