@omerdlw/base-framework 2.0.0 → 3.0.0

package/dist/{chunk-3MSK4XGK.js → chunk-JIXBFFRD.js}

@@ -1,9 +1,10 @@
+import { NAVIGATION_STATUS, createNavigator } from './chunk-HLL5EHXC.js';
 import { Z_INDEX } from './chunk-QI3ALLIB.js';
 import { useNotificationVisible } from './chunk-SYAVGTOX.js';
 import { useOptionalMediaState, useOptionalMediaActions } from './chunk-R2YGFJDJ.js';
-import { useOptionalLoadingActions, useOptionalLoadingState } from './chunk-XASQT4CQ.js';
+import { useOptionalLoadingActions, useOptionalLoadingState } from './chunk-66EYJBIP.js';
 import { defineThemeSpec, useModuleMotion, useTheme, cssTransition, staggerDelay, gpuTransform, useOptionalModuleMotion } from './chunk-7TAVYJ3A.js';
-import { getOrCreateGlobalContext, defineModule, useRegistryEntries, useModuleRegistration } from './chunk-GF7TUX5I.js';
+import { getOrCreateGlobalContext, defineModule, useModule, useRegistryEntries, useModuleRegistration } from './chunk-GF7TUX5I.js';
 import { createStore, cn, isImageIconSource, clamp, useIsomorphicLayoutEffect, isObject, isPlainObject, trimToNull, shallowEqual, useGlobalEvent, useRequiredContext, globalEvents, toArray, useIsFullscreenStateActive, useClickOutside, report, normalizePath, useStore, createScheduler, EVENT_TYPES, toUserMessage } from './chunk-TV3WEF5G.js';
 import { Tooltip, Icon, Button, Spinner } from './chunk-3BUP64Q6.js';
 import React, { createContext, memo, createElement, isValidElement, cloneElement, Suspense, useEffect, useState, useCallback, useMemo, use, useSyncExternalStore, useRef, useLayoutEffect, useReducer, lazy, useContext, useId } from 'react';
@@ -436,27 +437,8 @@ var DOCK_CARD_LAYOUT = Object.freeze({
   actionGap: DOCK_CARD_DIMENSIONS.actionGap,
   baseHeight: DOCK_CARD_DIMENSIONS.height
 });
-var DOCK_TRANSACTION_EVENTS = Object.freeze({
-  START: "START",
-  COMPLETE: "COMPLETE",
-  CANCEL: "CANCEL",
-  FAIL: "FAIL",
-  TIME_OUT: "TIME_OUT"
-});
-var DOCK_TRANSACTION_STATUS = Object.freeze({
-  PENDING: "pending",
-  COMPLETED: "completed",
-  CANCELLED: "cancelled",
-  FAILED: "failed",
-  TIMED_OUT: "timed-out"
-});
-var DOCK_TRANSACTION_REASON = Object.freeze({
-  GUARD: "guard",
-  SUPERSEDED: "superseded",
-  TIME_OUT: "time-out"
-});
-var DOCK_TRANSACTION_TIMEOUT_MS = 15e3;
 var DOCK_PREFETCH_INTENT_DELAY_MS = 90;
+var DOCK_PENDING_ROUTE_HOLD_MS = 2500;
 var DOCK_CONTINUITY_EVENTS = Object.freeze({
   CLEAR: "CLEAR",
   CONSUME_RETURN: "CONSUME_RETURN",
@@ -1608,6 +1590,10 @@ var DOCK_COMPOSITOR_STYLE = Object.freeze({
   backfaceVisibility: "hidden",
   transform: "translateZ(0)"
 });
+var DOCK_UNSEEN_EXIT = Object.freeze({
+  opacity: 0,
+  transition: Object.freeze({ duration: 0 })
+});
 var DOCK_SURFACE_DRAG_CONSTRAINTS = Object.freeze({
   top: 0,
   bottom: 0
@@ -2796,7 +2782,6 @@ function useDockHeightController({
   const heightRef = useRef({ content: 0 });
   const rafRef = useRef(null);
   const isHudRef = useRef(isHud);
-  const surfacePhaseRef = useRef(surfacePhase);
   const lastAppliedContainerHeightRef = useRef(
     isHud ? DOCK_CARD_LAYOUT.hudHeight : DOCK_CARD_LAYOUT.baseHeight
   );
@@ -2805,19 +2790,15 @@ function useDockHeightController({
   );
   useIsomorphicLayoutEffect(() => {
     isHudRef.current = isHud;
-    surfacePhaseRef.current = surfacePhase;
-  }, [isHud, surfacePhase]);
+  }, [isHud]);
   const applyHeight = useCallback(() => {
     if (rafRef.current !== null) {
       cancelAnimationFrame(rafRef.current);
       rafRef.current = null;
     }
     const { content } = heightRef.current;
-    const currentPhase = surfacePhaseRef.current;
-    const isLockedToBaseHeight = currentPhase === DOCK_SURFACE_PHASE.DISMISSING_ACTION || currentPhase === DOCK_SURFACE_PHASE.COLLAPSING_BODY || currentPhase === DOCK_SURFACE_PHASE.RESTORING_HEADER;
-    const computedContentHeight = isLockedToBaseHeight ? 0 : content;
     const height = getContainerHeight({
-      cardContentHeight: computedContentHeight,
+      cardContentHeight: content,
       isHud: isHudRef.current
     });
     const totalSpacerHeight = height + DOCK_HEIGHT_BUFFER;
@@ -3028,210 +3009,6 @@ function openDockGuardConfirmation({
     }
   });
 }
-function createDockTransactionState() {
-  return { active: null, last: null };
-}
-function createDockTransaction({
-  from = "",
-  id,
-  source = "dock",
-  startedAt = Date.now(),
-  to = ""
-}) {
-  return {
-    from: String(from || ""),
-    id,
-    source,
-    startedAt,
-    status: DOCK_TRANSACTION_STATUS.PENDING,
-    to: String(to || "")
-  };
-}
-function settleDockTransaction(transaction, action, status) {
-  return {
-    ...transaction,
-    endedAt: action.endedAt ?? Date.now(),
-    error: action.error ?? null,
-    reason: action.reason ?? null,
-    status
-  };
-}
-var TRANSACTION_STATUS_MAP = Object.freeze({
-  [DOCK_TRANSACTION_EVENTS.COMPLETE]: DOCK_TRANSACTION_STATUS.COMPLETED,
-  [DOCK_TRANSACTION_EVENTS.CANCEL]: DOCK_TRANSACTION_STATUS.CANCELLED,
-  [DOCK_TRANSACTION_EVENTS.FAIL]: DOCK_TRANSACTION_STATUS.FAILED,
-  [DOCK_TRANSACTION_EVENTS.TIME_OUT]: DOCK_TRANSACTION_STATUS.TIMED_OUT
-});
-function dockTransactionReducer(state, action) {
-  if (action?.type === DOCK_TRANSACTION_EVENTS.START) {
-    const nextTransaction = action.transaction;
-    if (nextTransaction?.id == null) return state;
-    const supersededTransaction = state.active ? settleDockTransaction(
-      state.active,
-      { reason: DOCK_TRANSACTION_REASON.SUPERSEDED },
-      DOCK_TRANSACTION_STATUS.CANCELLED
-    ) : state.last;
-    return { active: nextTransaction, last: supersededTransaction };
-  }
-  const newStatus = action ? TRANSACTION_STATUS_MAP[action.type] : void 0;
-  if (newStatus && action && state.active && state.active.id === action.id) {
-    return {
-      active: null,
-      last: settleDockTransaction(state.active, action, newStatus)
-    };
-  }
-  return state;
-}
-function useDockTransactions({
-  onTransactionEvent = null,
-  onTimeout = null,
-  timeoutMs = DOCK_TRANSACTION_TIMEOUT_MS
-} = {}) {
-  const [state, dispatch] = useReducer(
-    dockTransactionReducer,
-    void 0,
-    createDockTransactionState
-  );
-  const activeTransactionRef = useRef(null);
-  const nextTransactionIdRef = useRef(0);
-  const timeoutRef = useRef(null);
-  const onTimeoutRef = useRef(onTimeout);
-  const onTransactionEventRef = useRef(onTransactionEvent);
-  useEffect(() => {
-    onTimeoutRef.current = onTimeout;
-  }, [onTimeout]);
-  useEffect(() => {
-    onTransactionEventRef.current = onTransactionEvent;
-  }, [onTransactionEvent]);
-  const clearTransactionTimeout = useCallback(() => {
-    if (timeoutRef.current !== null) {
-      clearTimeout(timeoutRef.current);
-      timeoutRef.current = null;
-    }
-  }, []);
-  const settleTransaction = useCallback(
-    (id, type, details = {}) => {
-      const activeTransaction = activeTransactionRef.current;
-      if (!activeTransaction || activeTransaction.id !== id) return false;
-      clearTransactionTimeout();
-      activeTransactionRef.current = null;
-      const event = { ...details, endedAt: Date.now(), id, type };
-      const settledTransaction = settleDockTransaction(
-        activeTransaction,
-        event,
-        TRANSACTION_STATUS_MAP[type] || DOCK_TRANSACTION_STATUS.TIMED_OUT
-      );
-      dispatch(event);
-      onTransactionEventRef.current?.({
-        transaction: settledTransaction,
-        type
-      });
-      return true;
-    },
-    [clearTransactionTimeout]
-  );
-  const beginTransaction = useCallback(
-    ({
-      from,
-      source,
-      to
-    } = {}) => {
-      const activeTransaction = activeTransactionRef.current;
-      if (activeTransaction) {
-        settleTransaction(
-          activeTransaction.id,
-          DOCK_TRANSACTION_EVENTS.CANCEL,
-          { reason: DOCK_TRANSACTION_REASON.SUPERSEDED }
-        );
-      }
-      const transaction = createDockTransaction({
-        from,
-        id: ++nextTransactionIdRef.current,
-        source,
-        to
-      });
-      activeTransactionRef.current = transaction;
-      dispatch({ transaction, type: DOCK_TRANSACTION_EVENTS.START });
-      onTransactionEventRef.current?.({
-        transaction,
-        type: DOCK_TRANSACTION_EVENTS.START
-      });
-      const safeTimeout = Number(timeoutMs);
-      if (Number.isFinite(safeTimeout) && safeTimeout > 0) {
-        timeoutRef.current = setTimeout(() => {
-          if (!settleTransaction(
-            transaction.id,
-            DOCK_TRANSACTION_EVENTS.TIME_OUT,
-            { reason: DOCK_TRANSACTION_REASON.TIME_OUT }
-          ))
-            return;
-          onTimeoutRef.current?.(transaction);
-        }, safeTimeout);
-      }
-      return transaction;
-    },
-    [settleTransaction, timeoutMs]
-  );
-  const completeTransaction = useCallback(
-    (id) => settleTransaction(id, DOCK_TRANSACTION_EVENTS.COMPLETE),
-    [settleTransaction]
-  );
-  const cancelTransaction = useCallback(
-    (id, reason = null) => settleTransaction(id, DOCK_TRANSACTION_EVENTS.CANCEL, { reason }),
-    [settleTransaction]
-  );
-  const cancelActiveTransaction = useCallback(
-    (reason = null) => activeTransactionRef.current ? cancelTransaction(activeTransactionRef.current.id, reason) : false,
-    [cancelTransaction]
-  );
-  const failTransaction = useCallback(
-    (id, error) => settleTransaction(id, DOCK_TRANSACTION_EVENTS.FAIL, { error }),
-    [settleTransaction]
-  );
-  const completeTransactionForPath = useCallback(
-    (pathname) => {
-      const activeTransaction = activeTransactionRef.current;
-      if (!activeTransaction || !isSamePath(activeTransaction.to, pathname))
-        return false;
-      return completeTransaction(activeTransaction.id);
-    },
-    [completeTransaction]
-  );
-  const isTransactionCurrent = useCallback(
-    (id) => activeTransactionRef.current?.id === id,
-    []
-  );
-  useEffect(() => {
-    return () => {
-      clearTransactionTimeout();
-      activeTransactionRef.current = null;
-    };
-  }, [clearTransactionTimeout]);
-  return useMemo(
-    () => ({
-      activeTransaction: state.active,
-      beginTransaction,
-      cancelActiveTransaction,
-      cancelTransaction,
-      completeTransaction,
-      completeTransactionForPath,
-      failTransaction,
-      isTransactionCurrent,
-      lastTransaction: state.last
-    }),
-    [
-      state.active,
-      state.last,
-      beginTransaction,
-      cancelActiveTransaction,
-      cancelTransaction,
-      completeTransaction,
-      completeTransactionForPath,
-      failTransaction,
-      isTransactionCurrent
-    ]
-  );
-}
 
 // src/modules/dock/routing/navigation.ts
 function getRoutePolicyOverrides(item) {
@@ -3306,7 +3083,8 @@ function createDockTopology(items = [], { pathname = "" } = {}) {
   };
 }
 function useRoutePrefetch(router, {
-  intentDelayMs = DOCK_PREFETCH_INTENT_DELAY_MS
+  intentDelayMs = DOCK_PREFETCH_INTENT_DELAY_MS,
+  navigator: navigator2 = null
 } = {}) {
   const routeStatesRef = useRef(/* @__PURE__ */ new Map());
   const cancelRoutePrefetch = useCallback((href) => {
@@ -3318,7 +3096,7 @@ function useRoutePrefetch(router, {
   }, []);
   const prefetchRoute = useCallback(
     (href, { immediate = false } = {}) => {
-      if (!isSafeInternalHref(href) || typeof router?.prefetch !== "function")
+      if (!isSafeInternalHref(href) || !navigator2 && typeof router?.prefetch !== "function")
         return false;
       const routeState = routeStatesRef.current.get(href);
       if (routeState?.isPrefetched || routeState?.timeoutId != null)
@@ -3327,6 +3105,11 @@ function useRoutePrefetch(router, {
         const currentState = routeStatesRef.current.get(href);
         if (!currentState) return;
         currentState.timeoutId = null;
+        if (navigator2) {
+          routeStatesRef.current.delete(href);
+          navigator2.prefetch(href);
+          return;
+        }
         currentState.isPrefetched = true;
         try {
           router.prefetch(href, {
@@ -3353,7 +3136,7 @@ function useRoutePrefetch(router, {
       else nextState.timeoutId = setTimeout(startPrefetch, delay);
       return true;
     },
-    [intentDelayMs, router]
+    [intentDelayMs, navigator2, router]
   );
   useEffect(() => {
     const routeStates = routeStatesRef.current;
@@ -3431,6 +3214,25 @@ function emitDockEvent(eventType, data = {}) {
     ...data
   });
 }
+function useDockNavigator(router) {
+  const shared = useModule("navigation");
+  const [own] = useState(
+    () => shared ? null : createNavigator({ router })
+  );
+  useEffect(() => {
+    own?.setRouter(router);
+  }, [own, router]);
+  useEffect(() => own ? () => own.dispose() : void 0, [own]);
+  return useMemo(
+    () => own ?? { ...shared.actions, dispose: () => {
+    }, store: shared.store },
+    [own, shared]
+  );
+}
+var selectTrips = (state) => ({
+  active: state.active,
+  last: state.last
+});
 function useDockNavigation() {
   const pathname = usePathname();
   const { locationKey, syncLocationKey } = useDockLocationKey();
@@ -3447,95 +3249,78 @@ function useDockNavigation() {
     "useDockNavigation",
     "DockProvider"
   );
+  const navigator2 = useDockNavigator(router);
+  const { active: activeTransaction, last: lastTransaction } = useStore(
+    navigator2.store,
+    selectTrips,
+    shallowEqual
+  );
   const previousLocationKeyRef = useRef(locationKey);
-  const handleTransactionTimeout = useCallback(() => {
-    clearPreparedRouteReset();
-    stopLoading();
-  }, [clearPreparedRouteReset, stopLoading]);
-  const {
-    activeTransaction,
-    beginTransaction,
-    cancelActiveTransaction,
-    cancelTransaction,
-    completeTransactionForPath,
-    failTransaction,
-    isTransactionCurrent,
-    lastTransaction
-  } = useDockTransactions({
-    onTimeout: handleTransactionTimeout
-  });
+  const settledTripRef = useRef(lastTransaction);
+  useEffect(() => {
+    if (settledTripRef.current === lastTransaction) return;
+    settledTripRef.current = lastTransaction;
+    if (!lastTransaction) return;
+    if (lastTransaction.status === NAVIGATION_STATUS.COMPLETED) {
+      syncLocationKey();
+    } else if (lastTransaction.status === NAVIGATION_STATUS.TIMED_OUT || lastTransaction.status === NAVIGATION_STATUS.FAILED) {
+      clearPreparedRouteReset();
+      stopLoading();
+    }
+  }, [clearPreparedRouteReset, lastTransaction, stopLoading, syncLocationKey]);
   const cancelDock = useCallback(
     (reason = "guard") => {
-      cancelActiveTransaction(reason);
+      navigator2.cancel(reason);
       clearPreparedRouteReset();
       closeSurface({ cancelled: true, reason, success: false });
     },
-    [cancelActiveTransaction, clearPreparedRouteReset, closeSurface]
+    [clearPreparedRouteReset, closeSurface, navigator2]
   );
   const commitDock = useCallback(
-    ({
+    async ({
+      force = false,
       from,
       href,
+      item,
       routePolicy,
-      source = "dock",
-      transaction = null
+      source = "dock"
     }) => {
-      const activeRouteTransaction = transaction || beginTransaction({ from, source, to: href });
-      if (!isTransactionCurrent(activeRouteTransaction.id)) return false;
-      try {
-        continuity?.remember?.(from);
+      const result = await navigator2.navigate(href, {
+        force,
+        guard: guards.count() > 0 ? () => guards.check(href, from) : void 0,
+        onCommit: () => {
+          continuity?.remember?.(from);
+          blurActiveElement();
+          prepareRouteReset(routePolicy);
+          emitDockEvent(DOCK_EVENTS.NAVIGATE_START, { from, to: href });
+        },
+        source
+      });
+      if (result.ok) {
+        emitDockEvent(DOCK_EVENTS.NAVIGATE, { from, item, to: href });
+        return true;
+      }
+      if (result.blocked) {
         blurActiveElement();
-        prepareRouteReset(routePolicy);
-        emitDockEvent(DOCK_EVENTS.NAVIGATE_START, { from, to: href });
-        router.push(href);
-        emitDockEvent(DOCK_EVENTS.NAVIGATE, {
+        openDockGuardConfirmation({
+          closeSurface,
+          commit: (confirmed) => void commitDock({ ...confirmed, force: true }).catch(
+            (error) => report("Dock route transition", error)
+          ),
           from,
-          item: void 0,
-          to: href
+          href,
+          message: result.blocked.message,
+          routePolicy
         });
-        if (typeof window !== "undefined") {
-          const currentUrl = new URL(window.location.href);
-          const destinationUrl = new URL(href, window.location.origin);
-          if (normalizePath(currentUrl.pathname) === normalizePath(destinationUrl.pathname)) {
-            window.requestAnimationFrame(() => {
-              const currentLocKey = getDockLocationKey({
-                hash: window.location.hash,
-                pathname: window.location.pathname,
-                search: window.location.search
-              });
-              if (!isSamePath(currentLocKey, href) || !completeTransactionForPath(currentLocKey))
-                return;
-              emitDockEvent(DOCK_EVENTS.NAVIGATE_END, {
-                duration: void 0,
-                from,
-                to: currentLocKey
-              });
-              previousLocationKeyRef.current = currentLocKey;
-              syncLocationKey();
-              stopLoading();
-            });
-          }
-        }
-        return true;
-      } catch (error) {
-        clearPreparedRouteReset();
-        failTransaction(activeRouteTransaction.id, error);
-        stopLoading();
-        report("Dock route transition", error);
-        return false;
       }
+      return false;
     },
     [
-      beginTransaction,
-      clearPreparedRouteReset,
-      completeTransactionForPath,
+      closeSurface,
       continuity,
-      failTransaction,
-      isTransactionCurrent,
-      prepareRouteReset,
-      router,
-      stopLoading,
-      syncLocationKey
+      guards,
+      navigator2,
+      prepareRouteReset
     ]
   );
   const navigate = useCallback(
@@ -3551,62 +3336,27 @@ function useDockNavigation() {
         return false;
       }
       if (isSamePath(href, from)) return false;
-      const transaction = beginTransaction({ from, source, to: href });
       try {
-        if (!force && guards.count() > 0) {
-          const guardResult = await guards.check(href, from);
-          if (!isTransactionCurrent(transaction.id)) return false;
-          if (guardResult.blocked) {
-            cancelTransaction(transaction.id, "guard");
-            blurActiveElement();
-            openDockGuardConfirmation({
-              closeSurface,
-              commit: commitDock,
-              from,
-              href,
-              message: guardResult.message,
-              routePolicy
-            });
-            return false;
-          }
-        }
-        return commitDock({
-          from,
-          href,
-          routePolicy,
-          source,
-          transaction
-        });
+        return await commitDock({ force, from, href, routePolicy, source });
       } catch (error) {
-        failTransaction(transaction.id, error);
         stopLoading();
-        report("Dock navigation guard", error);
+        report("Dock navigation", error);
         return false;
       }
     },
-    [
-      guards,
-      beginTransaction,
-      cancelTransaction,
-      commitDock,
-      failTransaction,
-      isTransactionCurrent,
-      closeSurface,
-      locationKey,
-      stopLoading
-    ]
+    [commitDock, locationKey, stopLoading]
   );
   useEffect(() => {
+    navigator2.arrive(locationKey);
     if (previousLocationKeyRef.current === locationKey) return;
     emitDockEvent(DOCK_EVENTS.NAVIGATE_END, {
       duration: void 0,
       from: previousLocationKeyRef.current,
       to: locationKey
     });
-    completeTransactionForPath(locationKey);
     previousLocationKeyRef.current = locationKey;
     stopLoading();
-  }, [completeTransactionForPath, locationKey, stopLoading]);
+  }, [locationKey, navigator2, stopLoading]);
   return {
     activeTransaction,
     cancelDock,
@@ -3672,6 +3422,16 @@ function sortToolbarActionsByOrder(actions) {
     (left, right) => (right.order ?? 0) - (left.order ?? 0)
   );
 }
+var PAGE_FACING_SURFACE_PHASES = /* @__PURE__ */ new Set([
+  DOCK_SURFACE_PHASE.DISMISSING_ACTION,
+  DOCK_SURFACE_PHASE.COLLAPSING_BODY,
+  DOCK_SURFACE_PHASE.RESTORING_HEADER
+]);
+function isSurfaceLayerShown(item) {
+  return Boolean(
+    item?.isSurface && !PAGE_FACING_SURFACE_PHASES.has(item.surfacePhase ?? "")
+  );
+}
 function isActionlessDockItem(activeItem) {
   const isSurfaceActive = Boolean(
     activeItem?.isSurface && activeItem?.surfacePhase !== DOCK_SURFACE_PHASE.RESTORING_HEADER
@@ -3784,10 +3544,13 @@ function ownsPathname(path, pathname) {
   return !path || isInlineActionPathMatch(path, pathname);
 }
 function useActionSlot(item, pathname, { isTop = false } = {}) {
-  const { action, isLoading, isOverlay, path, isStatus, isSurface } = item;
+  const { isLoading, path, isStatus, isSurface, surfacePhase } = item;
+  const isOverlay = Boolean(item.isOverlay && !isSurface);
+  const action = isSurface ? item.restingAction : item.action;
+  const showsSurface = isSurfaceLayerShown({ isSurface, surfacePhase });
   const hasMedia = useDockHasMedia();
   return useMemo(() => {
-    if (isLoading || isOverlay && !isStatus || isSurface) return null;
+    if (isLoading || isOverlay && !isStatus || showsSurface) return null;
     if (isStatus) {
       return action && isRenderableAction(action) ? { kind: "action", action } : null;
     }
@@ -3806,7 +3569,7 @@ function useActionSlot(item, pathname, { isTop = false } = {}) {
     isLoading,
     isOverlay,
     isStatus,
-    isSurface,
+    showsSurface,
     isTop,
     hasMedia,
     path,
@@ -3890,7 +3653,10 @@ function useDockCardItemModel({
   const [isHovered, setIsHovered] = useState(false);
   const pathname = usePathname();
   const router = useRouter();
-  const { cancelRoutePrefetch, prefetchRoute } = useRoutePrefetch(router);
+  const navigation = useModule("navigation");
+  const { cancelRoutePrefetch, prefetchRoute } = useRoutePrefetch(router, {
+    navigator: navigation?.actions
+  });
   const hasMedia = useDockHasMedia();
   const isTopHudActive = Boolean(isTop && isHudActive);
   const isCurrentActive = Boolean(
@@ -3956,9 +3722,13 @@ function useDockCardItemModel({
       }
     };
   }, [effectiveStyle, isActive, isStatusCard, showBorder, theme]);
-  const renderedActionSlot = item.isSurface && !isHeaderRestoring || isTopHudActive ? null : actionSlot;
+  const showsSurfaceLayer = isSurfaceLayerShown(item);
+  const renderedActionSlot = showsSurfaceLayer || isTopHudActive ? null : actionSlot;
+  const isActionDismissed = Boolean(
+    item.isSurface && item.surfacePhase === DOCK_SURFACE_PHASE.DISMISSING_ACTION
+  );
   const hasNestedInteractiveContent = Boolean(
-    renderedActionSlot || item.isSurface && !isHeaderRestoring
+    renderedActionSlot || showsSurfaceLayer
   );
   const dockMotion = useDockMotion();
   const headerRestoreVariants = useMemo(() => {
@@ -4066,6 +3836,8 @@ function useDockCardItemModel({
     cardContentRef,
     itemStyle,
     renderedActionSlot,
+    isActionDismissed,
+    showsSurfaceLayer,
     hasNestedInteractiveContent,
     headerRestoreVariants,
     handleMouseEnter,
@@ -5163,6 +4935,7 @@ function applySurfaceToDockItem(item, rawSurfaceEntry, options = {}) {
     isSurface: true,
     isOverlay: true,
     ...activeSurface,
+    restingAction: item.action ?? null,
     restingWidth: item.width ?? null,
     surfacePhase,
     actions: null,
@@ -6034,27 +5807,31 @@ function buildDockItems({
     return filterDockItems(flattenedItems, searchQuery);
   return flattenedItems;
 }
-function resolveBaseActiveItem({
+function resolveBaseActiveItemMatch({
   rawItems,
   dockItems,
   pathname,
   isNotFoundPage
 }) {
   const normalizedPathname = normalizePath(pathname);
+  const matched = (item) => ({
+    item,
+    isFallback: false
+  });
   const selectedDataSource = dockItems.find(
     (item) => item.isDataSource && item.isSelected
   );
-  if (selectedDataSource) return selectedDataSource;
+  if (selectedDataSource) return matched(selectedDataSource);
   if (isNotFoundPage)
-    return rawItems.find(isNotFoundItem) || rawItems[0] || null;
+    return matched(rawItems.find(isNotFoundItem) || rawItems[0] || null);
   const matchInDock = dockItems.find(
     (item) => isSamePath(item.path, normalizedPathname) || item.targetPath && isSamePath(item.targetPath, normalizedPathname)
   );
-  if (matchInDock) return matchInDock;
+  if (matchInDock) return matched(matchInDock);
   const matchInRaw = rawItems.find(
     (item) => isSamePath(item.path, normalizedPathname) || item.targetPath && isSamePath(item.targetPath, normalizedPathname)
   );
-  if (matchInRaw) return matchInRaw;
+  if (matchInRaw) return matched(matchInRaw);
   let prefixMatchedRawItem = null;
   let longestPrefixLength = -1;
   for (let i = 0; i < rawItems.length; i++) {
@@ -6065,11 +5842,65 @@ function resolveBaseActiveItem({
     }
   }
   if (prefixMatchedRawItem) {
-    return dockItems.find(
+    const item = dockItems.find(
       (entry) => isSamePath(entry?.path, prefixMatchedRawItem?.path) || entry?.name && entry.name === prefixMatchedRawItem?.name
     ) || prefixMatchedRawItem;
+    return {
+      item,
+      isFallback: normalizePath(prefixMatchedRawItem.path) === "/"
+    };
+  }
+  return { item: rawItems[0] || null, isFallback: true };
+}
+function selectPendingRouteItem({
+  match,
+  heldItem,
+  pathname,
+  isHolding
+}) {
+  if (!match.isFallback || !isHolding || !heldItem) return match.item;
+  if (heldItem.path && isSamePath(heldItem.path, pathname)) return match.item;
+  return heldItem;
+}
+function usePendingRouteHold(pathname, match, {
+  holdMs = DOCK_PENDING_ROUTE_HOLD_MS,
+  isNavigating = false
+} = {}) {
+  const normalizedPathname = normalizePath(pathname);
+  const [lastMatched, setLastMatched] = useState(
+    () => match.isFallback ? null : match.item
+  );
+  const [hold, setHold] = useState(() => ({
+    isOpen: false,
+    pathname: normalizedPathname
+  }));
+  if (!match.isFallback && match.item !== lastMatched) {
+    setLastMatched(match.item);
+  }
+  if (hold.pathname !== normalizedPathname) {
+    setHold({ isOpen: true, pathname: normalizedPathname });
   }
-  return rawItems[0] || null;
+  useEffect(() => {
+    if (!hold.isOpen || isNavigating) return;
+    const timer = setTimeout(
+      () => setHold(
+        (current) => current.pathname === hold.pathname ? { ...current, isOpen: false } : current
+      ),
+      holdMs
+    );
+    return () => clearTimeout(timer);
+  }, [hold, holdMs, isNavigating]);
+  const selected = selectPendingRouteItem({
+    heldItem: lastMatched,
+    isHolding: hold.isOpen && hold.pathname === normalizedPathname,
+    match,
+    pathname: normalizedPathname
+  });
+  const isHeld = selected !== match.item;
+  return useMemo(
+    () => isHeld && selected ? { ...selected, isRoutePending: true } : selected,
+    [isHeld, selected]
+  );
 }
 function resolveActiveItem({
   rawItems,
@@ -6084,14 +5915,15 @@ function resolveActiveItem({
   actionStackClass,
   surfaceActions,
   isPageLoading,
-  attention
+  attention,
+  baseActiveItem: resolvedBaseActiveItem
 }) {
-  const baseActiveItem = resolveBaseActiveItem({
+  const baseActiveItem = resolvedBaseActiveItem !== void 0 ? resolvedBaseActiveItem : resolveBaseActiveItemMatch({
     rawItems,
     dockItems,
     pathname,
     isNotFoundPage
-  });
+  }).item;
   if (!baseActiveItem) return null;
   if (attention?.kind === DOCK_ATTENTION_KIND.SURFACE)
     return applySurfaceToDockItem(
@@ -6143,7 +5975,7 @@ function useDockItems() {
   );
   return { rawItems };
 }
-function useDockDisplay(overridePathname) {
+function useDockDisplay(overridePathname, { isNavigating = false } = {}) {
   const routerPathname = usePathname();
   const pathname = overridePathname || routerPathname;
   const loadingState = useDockLoadingState();
@@ -6223,8 +6055,21 @@ function useDockDisplay(overridePathname) {
     () => buildDockItems({ rawItems, expanded, searchQuery, isNotFoundPage }),
     [rawItems, expanded, searchQuery, isNotFoundPage]
   );
+  const baseMatch = useMemo(
+    () => resolveBaseActiveItemMatch({
+      rawItems,
+      dockItems,
+      pathname,
+      isNotFoundPage
+    }),
+    [rawItems, dockItems, pathname, isNotFoundPage]
+  );
+  const baseActiveItem = usePendingRouteHold(pathname, baseMatch, {
+    isNavigating
+  });
   const activeItem = useMemo(
     () => resolveActiveItem({
+      baseActiveItem,
       rawItems,
       dockItems,
       pathname,
@@ -6249,6 +6094,7 @@ function useDockDisplay(overridePathname) {
       attention
     }),
     [
+      baseActiveItem,
       rawItems,
       dockItems,
       pathname,
@@ -6301,8 +6147,15 @@ function useDockLayout({
   const routePathname = usePathname();
   const pathname = overridePathname || routePathname;
   const { displayItems, displayActiveIndex } = useMemo(() => {
-    const items = dockItems || [];
-    const activeIndex = findDockItemIndex(items, activeItem ?? null, pathname);
+    const registeredItems = dockItems || [];
+    const registeredIndex = findDockItemIndex(
+      registeredItems,
+      activeItem ?? null,
+      pathname
+    );
+    const isHeldOutsideStack = registeredIndex === -1 && Boolean(activeItem?.isRoutePending);
+    const items = isHeldOutsideStack ? [activeItem, ...registeredItems] : registeredItems;
+    const activeIndex = isHeldOutsideStack ? 0 : registeredIndex;
     const itemsWithActiveItem = replaceActiveItem(
       items,
       activeIndex,
@@ -6357,7 +6210,9 @@ function useDock() {
     pathname
   } = core;
   const effectivePathname = activeTransaction?.to ? normalizePath(activeTransaction.to) : pathname;
-  const display = useDockDisplay(effectivePathname);
+  const display = useDockDisplay(effectivePathname, {
+    isNavigating: Boolean(activeTransaction)
+  });
   const { dockItems, activeItem, statusState, attention, topology } = display;
   const isHudModeActive = attention?.kind === DOCK_ATTENTION_KIND.HUD || attention?.kind === DOCK_ATTENTION_KIND.OPERATION;
   const isSurfaceActive = Boolean(activeItem?.isSurface);
@@ -7834,6 +7689,7 @@ function StandardItemContent({
   badge,
   isActive = false,
   footerNode,
+  isActionDismissed = false,
   isHudActive = false,
   hud = null,
   clearHud = null,
@@ -7841,6 +7697,13 @@ function StandardItemContent({
   pathname
 }) {
   const dockMotion = useDockMotion();
+  const actionVariants = useMemo(
+    () => ({
+      ...dockMotion.variants.textCrossfade,
+      dismissed: dockMotion.variants.actionDismiss.exit
+    }),
+    [dockMotion]
+  );
   const {
     item,
     isPlaying,
@@ -7913,15 +7776,27 @@ function StandardItemContent({
             contextCommands
           }
         ),
-        footerNode ? /* @__PURE__ */ jsx(
-          "div",
+        /* @__PURE__ */ jsx(AnimatePresence, { mode: "popLayout", initial: false, children: footerNode ? /* @__PURE__ */ jsx(
+          motion.div,
           {
+            variants: actionVariants,
+            initial: "hidden",
+            animate: isActionDismissed ? "dismissed" : "visible",
+            exit: "exit",
+            transition: isActionDismissed ? dockMotion.transitions.actionDismiss : dockMotion.transitions.fade,
             className: theme.slots.cardFooter,
             style: theme.styles.cardFooter,
-            children: footerNode
+            children: /* @__PURE__ */ jsx(
+              "div",
+              {
+                className: theme.slots.cardAction,
+                onClick: stopPropagationOnly,
+                children: footerNode
+              }
+            )
           },
-          "dock-surface-footer"
-        ) : null
+          "dock-card-footer"
+        ) : null })
       ]
     },
     "dock-standard-content"
@@ -7964,6 +7839,8 @@ var DockCardItem = memo(function DockCardItem2({
     cardContentRef,
     itemStyle,
     renderedActionSlot,
+    isActionDismissed,
+    showsSurfaceLayer,
     hasNestedInteractiveContent,
     headerRestoreVariants,
     handleMouseEnter,
@@ -8005,6 +7882,7 @@ var DockCardItem = memo(function DockCardItem2({
   });
   const theme = useDockTheme();
   const renderedActionNode = renderActionSlot(renderedActionSlot);
+  const layerExit = isCollapsedBackgroundCard ? DOCK_UNSEEN_EXIT : "exit";
   if (isCollapsedGhostCard) {
     return /* @__PURE__ */ jsx(
       motion.div,
@@ -8105,13 +7983,13 @@ var DockCardItem = memo(function DockCardItem2({
               willChange: "transform",
               pointerEvents: !expanded && position > 0 && !isExtensionShelf ? "none" : "auto"
             },
-            children: /* @__PURE__ */ jsx(AnimatePresence, { mode: "popLayout", initial: false, children: item.isSurface && item.surfacePhase !== DOCK_SURFACE_PHASE.DISMISSING_ACTION && item.surfacePhase !== DOCK_SURFACE_PHASE.COLLAPSING_BODY && item.surfacePhase !== DOCK_SURFACE_PHASE.RESTORING_HEADER ? /* @__PURE__ */ jsx(
+            children: /* @__PURE__ */ jsx(AnimatePresence, { mode: "popLayout", initial: false, children: showsSurfaceLayer ? /* @__PURE__ */ jsx(
               motion.div,
               {
                 variants: dockMotion.variants.headerSwap,
                 initial: "hidden",
                 animate: "visible",
-                exit: "exit",
+                exit: layerExit,
                 transition: dockMotion.transitions.headerSwap,
                 style: DOCK_COMPOSITOR_STYLE,
                 className: theme.slots.cardSurface,
@@ -8124,7 +8002,7 @@ var DockCardItem = memo(function DockCardItem2({
                 variants: dockMotion.variants.extensionShelf,
                 initial: "hidden",
                 animate: "visible",
-                exit: "exit",
+                exit: layerExit,
                 transition: dockMotion.transitions.headerSwap,
                 style: DOCK_COMPOSITOR_STYLE,
                 className: theme.slots.cardShelf,
@@ -8137,7 +8015,7 @@ var DockCardItem = memo(function DockCardItem2({
                 variants: headerRestoreVariants,
                 initial: "hidden",
                 animate: item.surfacePhase === DOCK_SURFACE_PHASE.DISMISSING_ACTION ? "hidden" : "visible",
-                exit: "exit",
+                exit: layerExit,
                 transition: item.surfacePhase === DOCK_SURFACE_PHASE.DISMISSING_ACTION ? dockMotion.transitions.anticipation : dockMotion.transitions.headerSwap,
                 style: { ...DOCK_COMPOSITOR_STYLE, willChange: "transform" },
                 className: theme.slots.cardStandard,
@@ -8155,33 +8033,8 @@ var DockCardItem = memo(function DockCardItem2({
                     clearHud,
                     contextCommands,
                     pathname,
-                    footerNode: renderedActionNode ? /* @__PURE__ */ jsx(AnimatePresence, { mode: "popLayout", initial: false, children: item.surfacePhase === DOCK_SURFACE_PHASE.DISMISSING_ACTION ? /* @__PURE__ */ jsx(
-                      motion.div,
-                      {
-                        variants: dockMotion.variants.actionDismiss,
-                        initial: "visible",
-                        animate: "exit",
-                        exit: "exit",
-                        transition: dockMotion.transitions.actionDismiss,
-                        className: theme.slots.cardAction,
-                        onClick: stopPropagationOnly,
-                        children: /* @__PURE__ */ jsx(Suspense, { children: renderedActionNode })
-                      },
-                      "dock-action-component-dismiss"
-                    ) : /* @__PURE__ */ jsx(
-                      motion.div,
-                      {
-                        variants: dockMotion.variants.textCrossfade,
-                        initial: "hidden",
-                        animate: "visible",
-                        exit: "exit",
-                        transition: dockMotion.transitions.fade,
-                        className: theme.slots.cardAction,
-                        onClick: stopPropagationOnly,
-                        children: /* @__PURE__ */ jsx(Suspense, { children: renderedActionNode })
-                      },
-                      "dock-action-component"
-                    ) }) : null
+                    footerNode: renderedActionNode ? /* @__PURE__ */ jsx(Suspense, { children: renderedActionNode }) : null,
+                    isActionDismissed
                   }
                 )
               },
@@ -9868,7 +9721,7 @@ var dockModule = defineModule({
   context: DockContext,
   Provider: DockModuleProvider,
   Overlay: Dock,
-  uses: ["loading", "media", "notification"],
+  uses: ["loading", "media", "navigation", "notification"],
   registry: {
     cleanupDelayMs: 600,
     keyPolicy: "path",
@@ -9884,5 +9737,5 @@ var dockModule = defineModule({
 });
 
 export { DOCK_EVENTS, DOCK_HUD_PRIORITY, DOCK_HUD_RENDER_MODE, DOCK_HUD_VARIANT, Dock, DockCardBanner, DockCardHeader, DockDescription, DockIcon, DockProvider, DockSurfaceAction, DockSurfaceExtension, DockSurfaceHeaderButton, DockTitle, ErrorActions, GuardActions, createDockGuardRegistry, createErrorStatus, createGuardStatus, createInlineSurfaceEntry, createSurfaceEntryDefinition, createSurfaceFlowBuilder, defineBreadcrumb, defineDockAction, defineHud, defineStepSurface, defineSurface, dockModule, dockTheme, isValidBannerUrl, useDock, useDockActionClass, useDockActions, useDockBanner, useDockConfig, useDockContextActions, useDockDimensions, useDockGuard, useDockHeight, useDockHud, useDockMotion, useDockRegistration, useDockSelector, useDockState, useDockTheme, useHud, useOptionalDockActions, useOptionalDockState, useSurface, useSurfaceAction, useSurfaceDimensions, useSurfaceFlow, useSurfaceHeader, useSurfaceId, useSurfaceReturn, useSurfaceStep };
-//# sourceMappingURL=chunk-3MSK4XGK.js.map
-//# sourceMappingURL=chunk-3MSK4XGK.js.map
+//# sourceMappingURL=chunk-JIXBFFRD.js.map
+//# sourceMappingURL=chunk-JIXBFFRD.js.map