vue-stack-tabs 1.4.1 → 2.2.0

package/src/lib/hooks/useTabPanel.tsx

@@ -16,7 +16,7 @@ import { computed, ref } from 'vue'
 import type { DefineComponent, VNode } from 'vue'
 import { isNavigationFailure, useRouter } from 'vue-router'
 import type { RouteLocationNormalizedLoaded } from 'vue-router'
-import { encodeTabInfo, createPageId, decodeTabInfo } from '../utils/tabInfoEncoder'
+import { encodeTabInfo, createId, createPageId, decodeTabInfo } from '../utils/tabInfoEncoder'
 import { defu } from 'defu'
 import { Stack } from '../model/TabModel'
 import {
@@ -26,14 +26,15 @@ import {
   toSafeTabUrl,
   decodeSafeTabUrl,
   cloneLocationQuery,
-  clonePage
+  isSameQueryIgnoringReserved,
+  normalizePathname
 } from '../utils/urlParser'
 import { TabEventType, useTabEmitter } from './useTabEventBus'
 import { runNavigationTransaction } from './tabPanel/navigationTransaction'
 import { useI18n } from 'vue-i18n-lite'
 
 import { resolveStackTabsRuntimeContext, type StackTabsRuntimeContext } from './stackTabsContext'
-import { createTabPanelEviction } from './tabPanel/evict'
+import { getTabStore } from './tabPanel/tabStore'
 import { createTabPanelScroll } from './tabPanel/scroll'
 import { createTabPanelSession } from './tabPanel/session'
 import { createTabPanelRefresh } from './tabPanel/refresh'
@@ -45,6 +46,9 @@ const cloneRouteQuery = (route: RouteLocationNormalizedLoaded, tabInfo: ITabBase
   __tab: route.query.__tab ?? encodeTabInfo(tabInfo)
 })
 
+/** homeTab 未显式指定 id 时使用的固定 id，保证刷新前后 __tab 与标签身份一致。 */
+const DEFAULT_HOME_TAB_ID = '__stack_tabs_home__'
+
 /** 规范化路径（nginx 等可能加尾部斜杠） */
 export const normalizePathForCache = (route: RouteLocationNormalizedLoaded): string => {
   const lastMatch = route.matched[route.matched.length - 1]
@@ -53,32 +57,57 @@ export const normalizePathForCache = (route: RouteLocationNormalizedLoaded): str
   return matchPath === path ? path : route.path
 }
 
-export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
+const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
   const router = useRouter()
-  const runtimeContext = providedRuntimeContext ?? resolveStackTabsRuntimeContext()
   const emitter = useTabEmitter(runtimeContext)
   const { t } = useI18n()
+  const { tabs, defaultTabs, caches, refreshKey, iframeRefreshKeys, isInitialized } = runtimeContext
+  const store = getTabStore(runtimeContext)
   const {
-    tabs,
-    defaultTabs,
-    caches,
-    components,
-    tabIdsToEvict,
-    refreshKey,
-    iframeRefreshKeys,
-    isInitialized,
-    cacheIdsToEvict
-  } = runtimeContext
-  const {
+    getTabs,
+    getTab,
+    getActiveTab,
+    findTabByTopPagePath,
+    hasTab,
+    canAddTab,
+    getPages,
+    getTopPage,
+    getPageRefreshVersion,
+    getPageSnapshot,
+    addTab,
+    addTabs,
+    activateTab,
+    updateTabTitle: updateTabTitleInStore,
+    moveTab,
+    removeTab: removeTabFromStore,
+    removeTabs: removeTabsFromStore,
+    appendPage,
+    popPages,
+    replacePages,
+    clearPages,
+    updatePage,
+    updatePages,
+    consumeBackParams,
     markCacheForEviction,
-    markTabPagesForEviction,
     markTabPagesForEvictionOnly,
     addCache,
     removeCache,
     evictMarkedCaches,
     evictPageCache,
-    replacePageCaches
-  } = createTabPanelEviction(runtimeContext)
+    replacePageCaches,
+    isTabMarkedForEviction,
+    isCacheMarkedForEviction,
+    unmarkCacheForEviction,
+    clearTabEvictionMarks,
+    getComponent,
+    setComponent,
+    deleteComponent,
+    snapshotComponents,
+    restoreComponents,
+    snapshotCaches,
+    restoreCaches,
+    reset: resetStore
+  } = store
   const { restoreScroller, saveScroller, removeScroller, addPageScroller } =
     createTabPanelScroll(runtimeContext)
   const {
@@ -89,32 +118,46 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     getSessionKey
   } = createTabPanelSession(runtimeContext)
 
-  const size = (): number => tabs.value.length
+  const size = (): number => getTabs().length
 
   /**
-   * 初始化：根据 defaultTabs 创建标签与初始页面，并尝试从 sessionStorage 恢复上次激活的标签
+   * 初始化：先创建固定首页（homeTab），再创建 defaultTabs，并尝试从 sessionStorage 恢复上次激活的标签
    * @param staticTabs - 初始标签配置
+   * @param homeTab - 固定首页；始终位于第一位、不可关闭、不可移动
    */
-  const initialize = (staticTabs: ITabData[]) => {
+  const initialize = (staticTabs: ITabData[], homeTab?: ITabData) => {
+    // 重复调用会累加 defaultTabs 并重复注册标签；初始化后直接忽略。
+    if (isInitialized.value) {
+      if (!import.meta.env.PROD) {
+        console.warn('[vue-stack-tabs] initialize() called more than once; ignored.')
+      }
+      return
+    }
     const newDefaults: ITabItem[] = []
     const newTabs: ITabItem[] = []
+    let homeTabId = ''
 
-    for (const item of staticTabs) {
+    /** 由 ITabData 构建运行时标签；homeTab 通过 options 强制固定属性 */
+    const buildTab = (
+      item: ITabData,
+      options: { pinned?: boolean; closable?: boolean } = {}
+    ): ITabItem => {
       // 先用默认值填充非空缺字段，避免在循环里提前求值生成用不到的 UUID。
       const fullItem = defu(item, {
         refreshable: true,
         closable: true,
         iframe: false
       })
-      // id 单独兜底，避免每次循环都无意义地调用 crypto.randomUUID。
-      fullItem.id = item.id ?? crypto.randomUUID()
+      // homeTab 未指定 id 时使用固定 id，避免每次初始化生成新 id 后与 session 恢复标签重复。
+      fullItem.id = item.id ?? (options.pinned ? DEFAULT_HOME_TAB_ID : createId())
+      if (options.closable !== undefined) fullItem.closable = options.closable
       const tabId = fullItem.id
       const uri = parseUrl(fullItem.path)
       const cacheName = createPageId()
       const page: ITabPage = {
         id: cacheName,
         tabId,
-        path: uri.path,
+        path: normalizePathname(uri.path),
         query: defu(omitStackTabsReservedQuery(uri.query), { __tab: encodeTabInfo(fullItem) })
       }
       const pages = new Stack<ITabPage>()
@@ -130,98 +173,76 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
             ? 'reload'
             : 'postMessage',
         active: false,
-        pages
+        pages,
+        pinned: options.pinned
       }
 
       addCache(cacheName)
+      return tab
+    }
+
+    if (homeTab) {
+      const home = buildTab(homeTab, { pinned: true, closable: false })
+      homeTabId = home.id
+      newDefaults.push(home)
+      newTabs.push({ ...home })
+    }
+
+    for (const item of staticTabs) {
+      // home 已单独创建；相同 id 的配置跳过，避免出现两个固定首页。
+      if (homeTabId && item.id === homeTabId) {
+        if (!import.meta.env.PROD) {
+          console.warn(
+            '[vue-stack-tabs] defaultTabs contains the same id as homeTab; skipped:',
+            item.id
+          )
+        }
+        continue
+      }
+      const tab = buildTab(item)
       newDefaults.push(tab)
       newTabs.push({ ...tab })
     }
 
     defaultTabs.value = [...defaultTabs.value, ...newDefaults]
-    tabs.value = [...tabs.value, ...newTabs]
+    addTabs(newTabs)
 
     // SSR 环境无 sessionStorage，直接跳过恢复。
     const storedTabJson =
       typeof window !== 'undefined' ? sessionStorage.getItem(getSessionKey()) : null
     const restoredTab = restoreTabFromSession(storedTabJson)
-    if (restoredTab && !tabs.value.some((t) => t.id === restoredTab.id)) {
+    if (restoredTab && !hasTab(restoredTab.id)) {
       if (restoredTab.url) restoredTab.url = toSafeTabUrl(restoredTab.url)
       if (restoredTab.iframe && restoredTab.url && restoredTab.iframeRefreshMode === undefined) {
         restoredTab.iframeRefreshMode = isCrossOriginUrl(restoredTab.url) ? 'reload' : 'postMessage'
       }
 
       if (restoredTab.pages && typeof restoredTab.pages.list === 'function') {
-        const pages = restoredTab.pages.list()
-        pages.forEach((page) => {
+        addTab(restoredTab)
+        for (const page of getPages(restoredTab.id)) {
           if (page && page.id) addCache(page.id)
-        })
+        }
+      } else {
+        addTab(restoredTab)
       }
-
-      tabs.value = [...tabs.value, restoredTab]
     }
     isInitialized.value = true
   }
 
-  const hasTab = (id: string) => tabs.value.some((t) => t.id === id)
-  const canAddTab = () =>
-    runtimeContext.maxTabCount.value <= 0 ||
-    (runtimeContext.maxTabCount.value > 0 && runtimeContext.maxTabCount.value > tabs.value.length)
-
-  const addTab = (tab: ITabItem): void => {
-    tabs.value = [...tabs.value, tab]
-  }
-
-  const getTab = (id: string) => tabs.value.find((t) => t.id === id) ?? null
-
-  /**
-   * 唯一的标签激活状态写入口。即使标签对象保持不变，也替换列表引用，
-   * 让 TabHeader 与 iframe 视图在同一个响应式提交中观察到一致状态。
-   */
-  const setActiveTab = (id: string): ITabItem | null => {
-    let activeTab: ITabItem | null = null
-    tabs.value = tabs.value.map((tab) => {
-      tab.active = tab.id === id
-      if (tab.active) activeTab = tab
-      return tab
-    })
-    return activeTab
-  }
-
   const { resolvePageComponent } = createPageComponentFactory({
     runtimeContext,
-    getTab,
+    consumeBackParams,
+    getComponent,
+    setComponent,
     addCache,
     evictMarkedCaches,
+    clearTabEvictionMarks,
     addPageScroller,
     saveScroller,
     restoreScroller,
     removeScroller
   })
 
-  /**
-   * 将指定标签移动到目标索引。标签对象本身不变，因此其页面栈和缓存关联保持不受影响。
-   * @returns 是否实际调整了顺序
-   */
-  const moveTab = (id: string, targetIndex: number): boolean => {
-    const sourceIndex = tabs.value.findIndex((tab) => tab.id === id)
-    if (
-      sourceIndex < 0 ||
-      targetIndex < 0 ||
-      targetIndex >= tabs.value.length ||
-      sourceIndex === targetIndex
-    ) {
-      return false
-    }
-
-    const reorderedTabs = tabs.value.slice()
-    const [tab] = reorderedTabs.splice(sourceIndex, 1)
-    if (!tab) return false
-    reorderedTabs.splice(targetIndex, 0, tab)
-    tabs.value = reorderedTabs
-    return true
-  }
-
   /** 把已有标签的对外字段提取为 ITabBase（用于让路由归属回该标签） */
   const toTabBase = (tab: ITabItem): ITabBase => ({
     id: tab.id,
@@ -232,21 +253,101 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     iframeRefreshMode: tab.iframeRefreshMode
   })
 
+  /**
+   * 动态更新标签标题。
+   *
+   * 同步 TabRecord、对外视图与 session；激活标签还会把新的 __tab 写回当前 URL，
+   * 避免刷新或分享链接后标题回退。
+   */
+  const updateTabTitle = (tabId: string, title: string): boolean => {
+    if (!updateTabTitleInStore(tabId, title)) return false
+    const tab = getTab(tabId)
+    if (!tab) return false
+
+    if (tab.active) {
+      saveActiveTabToSession(tab)
+      const top = getTopPage(tabId)
+      if (top) {
+        void Promise.resolve(
+          router.replace({
+            path: top.path,
+            query: { ...cloneLocationQuery(top.query), __tab: encodeTabInfo(toTabBase(tab)) },
+            hash: router.currentRoute.value.hash
+          })
+        ).catch((error: unknown) => {
+          if (!import.meta.env.PROD) {
+            console.warn('[vue-stack-tabs] Failed to sync tab title to URL:', error)
+          }
+        })
+      }
+    }
+    return true
+  }
+
+  /** 当前固定首页（homeTab）；未配置时返回 null。 */
+  const getHomeTab = (): ITabItem | null => getTabs().find((tab) => tab.pinned) ?? null
+
+  /**
+   * 无 __tab 且当前路径没有归属标签时，导航到 homeTab 的栈顶页面。
+   * 使用 replace，避免在浏览器历史里留下中间状态。
+   */
+  const redirectToHome = (): boolean => {
+    const home = getHomeTab()
+    const top = home ? getTopPage(home.id) : null
+    if (!home || !top) return false
+
+    const query = {
+      ...cloneLocationQuery(top.query),
+      __tab: encodeTabInfo(toTabBase(home))
+    }
+    void Promise.resolve(
+      router.replace({
+        path: top.path,
+        query,
+        hash: ''
+      })
+    ).catch((error: unknown) => {
+      if (!import.meta.env.PROD) {
+        console.warn('[vue-stack-tabs] Failed to redirect to home tab:', error)
+      }
+    })
+    return true
+  }
+
+  /**
+   * 是否应回落到 homeTab：仅限 URL 没有 __tab，且当前路径没有被任何标签的栈顶承载。
+   * 带 __tab 的地址即使页面不存在也不回落，交给应用自己的 404 路由处理。
+   */
+  const shouldRedirectToHome = (route: RouteLocationNormalizedLoaded): boolean => {
+    if (typeof route.query.__tab === 'string') return false
+
+    const path = normalizePathForCache(route)
+    const activeTab = getActiveTab()
+    if (activeTab && getTopPage(activeTab.id)?.path === path) return false
+    if (findTabByTopPagePath(path)) return false
+
+    const home = getHomeTab()
+    return Boolean(home && getTopPage(home.id))
+  }
+
   /**
    * 从路由解析 tabInfo，若无则创建默认信息，调用方负责把编码信息写入内部 page.query。
    *
    * 首次进入应用时 URL 上通常还没有 __tab：此时优先接管 path 匹配的默认标签（defaultTabs），
-   * 由调用方把 __tab 写回地址，保证「URL 指向默认标签」；确实找不到归属时才新建兜底标签。
+   * 由调用方把 __tab 写回地址，保证「URL 指向默认标签」；确实找不到归属且配置了 homeTab 时
+   * 返回 null，由调用方重定向到首页；未配置 homeTab 时保持原有兜底标签行为。
    */
-  const parseTabInfoFromRoute = (route: RouteLocationNormalizedLoaded): ITabBase => {
-    if (typeof route.query.__tab === 'string') {
-      const tabInfo = decodeTabInfo(route.query.__tab)
+  const parseTabInfoFromRoute = (route: RouteLocationNormalizedLoaded): ITabBase | null => {
+    const encodedTab = route.query.__tab
+    const hasEncodedTab = typeof encodedTab === 'string'
+    if (hasEncodedTab) {
+      const tabInfo = decodeTabInfo(encodedTab)
       if (tabInfo.id) return tabInfo
     }
 
     const path = normalizePathForCache(route)
-    const activeTab = tabs.value.find((tab) => tab.active)
-    const activePage = activeTab?.pages.peek()
+    const activeTab = getActiveTab()
+    const activePage = activeTab ? getTopPage(activeTab.id) : null
     if (activeTab && activePage?.path === path) {
       return toTabBase(activeTab)
     }
@@ -254,11 +355,15 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     // 当前激活标签与路由不一致：首屏 URL 无 __tab，或 session 恢复了上次激活的其它标签
     //（演示应用在 iframe 中重载后 hash 为空即属此类）。此时接管栈顶 path 与当前路由一致的
     // 标签（默认标签或已有标签），避免同一个页面既留下已有标签、又生成一个「未命名」的兜底标签。
-    const pathMatchedTab = tabs.value.find((tab) => tab.pages.peek()?.path === path)
+    const pathMatchedTab = findTabByTopPagePath(path)
     if (pathMatchedTab) return toTabBase(pathMatchedTab)
 
+    // 无 __tab 且无任何标签承载当前路径：配置了 homeTab 时交给调用方重定向。
+    // 注意：__tab 存在但无效时仍保持原行为（新建兜底标签），不把错误地址变成首页。
+    if (!hasEncodedTab && getHomeTab()) return null
+
     return {
-      id: crypto.randomUUID(),
+      id: createId(),
       title: t('VueStackTab.undefined'),
       closable: true,
       refreshable: true,
@@ -291,14 +396,15 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
         url: decodeSafeTabUrl(src),
         active: true,
         pages
-      } as unknown as ITabItem
-      setActiveTab('')
+      }
+      activateTab('')
       addTab(targetTab)
       emitter.emit(TabEventType.TAB_ACTIVE, { id: tabInfo.id!, isRoute: false })
     } else {
-      setActiveTab(targetTab.id)
-      if (targetTab.pages.isEmpty() || targetTab.pages.peek()!.id !== page.id) {
-        targetTab.pages.push(page)
+      activateTab(targetTab.id)
+      const topPage = getTopPage(targetTab.id)
+      if (!topPage || topPage.id !== page.id) {
+        appendPage(targetTab.id, page)
       }
     }
     return targetTab
@@ -317,27 +423,46 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     | { cacheName: string; tabInfo: ITabBase; targetTab: ITabItem }
     | { empty: true }
     | { recovered: DefineComponent; cacheName: string } => {
-    const tabInfo = parseTabInfoFromRoute(route)
-    if (tabIdsToEvict.has(tabInfo.id!)) return { empty: true }
+    const resolvedTabInfo = parseTabInfoFromRoute(route)
+    if (resolvedTabInfo === null) {
+      // 无 __tab 且没有标签承载当前路径：回落到 homeTab。
+      redirectToHome()
+      return { empty: true }
+    }
+    const tabInfo = resolvedTabInfo
+    if (isTabMarkedForEviction(tabInfo.id!)) return { empty: true }
 
     const path = normalizePathForCache(route)
+    const routeQuery = cloneRouteQuery(route, tabInfo)
+    /** path 与业务 query 都一致才算同一个页面（忽略 __tab 等保留参数） */
+    const isSameLocation = (candidate: ITabPage): boolean =>
+      candidate.path === path && isSameQueryIgnoringReserved(routeQuery, candidate.query || {})
 
     let targetTab: ITabItem | null = tabInfo.id ? (getTab(tabInfo.id) as ITabItem | null) : null
     let cacheName: string
     let page: ITabPage | null = null
 
-    if (targetTab && !targetTab.pages.isEmpty()) {
-      const top = targetTab.pages.peek()
+    if (targetTab && getTopPage(targetTab.id)) {
+      const top = getTopPage(targetTab.id)!
       if (!top) throw new Error('[vue-stack-tabs] Stack is not empty but peek() returned undefined')
 
-      if (top.path === path) {
+      if (isSameLocation(top)) {
         cacheName = top.id
+      } else if (top.path === path) {
+        // 同 path、不同 query：按产品语义作为新页面入栈，backward 才能按 query 精确回退。
+        cacheName = createPageId()
+        page = {
+          id: cacheName,
+          tabId: tabInfo.id!,
+          path,
+          query: cloneLocationQuery(routeQuery)
+        }
       } else {
-        const pagesList = targetTab.pages.readonlyList()
+        const pagesList = getPages(targetTab.id)
         let foundIndex = -1
         for (let i = pagesList.length - 2; i >= 0; i--) {
           const pastPage = pagesList[i]
-          if (pastPage && pastPage.path === path) {
+          if (pastPage && isSameLocation(pastPage)) {
             foundIndex = i
             break
           }
@@ -350,21 +475,19 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
             )
           }
           const stepsToPop = pagesList.length - 1 - foundIndex
-          for (let i = 0; i < stepsToPop; i++) {
-            const popped = targetTab.pages.pop()
-            // 仅标记待驱逐，由 onActivated 或下一拍 evictMarkedCaches 统一清理，
-            // 避免 watcher 同步执行与守卫拒绝路由之间产生不一致。
-            if (popped) markCacheForEviction(popped.id)
-          }
-          const newTop = targetTab.pages.peek()
+          const poppedPages = popPages(targetTab.id, stepsToPop)
+          // 仅标记待驱逐，由 onActivated 或下一拍 evictMarkedCaches 统一清理，
+          // 避免 watcher 同步执行与守卫拒绝路由之间产生不一致。
+          for (const popped of poppedPages) markCacheForEviction(popped.id)
+          const newTop = getTopPage(targetTab.id)
           cacheName = newTop ? newTop.id : createPageId()
 
           if (!newTop) {
             page = {
               id: cacheName,
               tabId: tabInfo.id!,
-              path: route.path,
-              query: cloneRouteQuery(route, tabInfo)
+              path,
+              query: cloneLocationQuery(routeQuery)
             }
           }
         } else {
@@ -372,8 +495,8 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
           page = {
             id: cacheName,
             tabId: tabInfo.id!,
-            path: route.path,
-            query: cloneRouteQuery(route, tabInfo)
+            path,
+            query: cloneLocationQuery(routeQuery)
           }
         }
       }
@@ -382,21 +505,21 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
       page = {
         id: cacheName,
         tabId: tabInfo.id!,
-        path: route.path,
-        query: cloneRouteQuery(route, tabInfo)
+        path,
+        query: cloneLocationQuery(routeQuery)
       }
     }
 
-    if (cacheIdsToEvict.has(cacheName)) {
-      cacheIdsToEvict.delete(cacheName)
-      const cached = components.get(cacheName)
+    if (isCacheMarkedForEviction(cacheName)) {
+      unmarkCacheForEviction(cacheName)
+      const cached = getComponent(cacheName)
       if (cached) return { recovered: cached, cacheName }
     }
 
     if (page) {
       targetTab = findOrCreateTargetTab(tabInfo, route, cacheName, page)
     } else {
-      setActiveTab(targetTab!.id)
+      activateTab(targetTab!.id)
     }
 
     // 首屏 URL 往往没有 __tab（用户直接打开默认路由）：把解析出的标签编码写回地址，
@@ -417,8 +540,8 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
   const activeCacheKey = ref<string>('')
   /** 只随当前活动页面刷新变化，避免一个 Tab 刷新导致其他 Tab 的缓存 key 失效。 */
   const activePageRefreshVersion = computed(() => {
-    const activeTab = tabs.value.find((tab) => tab.active)
-    return activeTab?.pages.peek()?.refreshVersion ?? 0
+    const activeTab = getActiveTab()
+    return activeTab ? (getTopPage(activeTab.id)?.refreshVersion ?? 0) : 0
   })
 
   let lastRouteKey = ''
@@ -428,7 +551,12 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     route: RouteLocationNormalizedLoaded,
     component?: VNode | null
   ): DefineComponent => {
-    if (!component) return getEmptyPlaceholderComponent()
+    if (!component) {
+      // 路由没有匹配到组件时不会进入 updatePageState；仍需处理无 __tab 的未知地址回落到首页。
+      // 带 __tab 的未知页面不做重定向，交给应用自己的 404 路由（或空占位）处理。
+      if (shouldRedirectToHome(route)) redirectToHome()
+      return getEmptyPlaceholderComponent()
+    }
 
     const routeKey = route.fullPath + (route.query.__tab || '')
     if (routeKey === lastRouteKey && lastAddPageResult) {
@@ -455,74 +583,45 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     const currentTab = getTab(tab.id!)
     if (!currentTab) return undefined
 
-    const pageSnapshot = currentTab.pages.list().map((p) => clonePage(p))
-    const cacheSnapshot = [...caches.value]
-    const componentSnapshot = new Map(components)
+    const pageSnapshot = getPageSnapshot(currentTab.id)
+    const cacheSnapshot = snapshotCaches()
+    const componentSnapshot = snapshotComponents()
 
     markTabPagesForEvictionOnly(currentTab)
     evictMarkedCaches()
-    currentTab.pages.clear()
+    clearPages(currentTab.id)
 
     return () => {
-      currentTab.pages.clear()
-      for (const page of pageSnapshot) currentTab.pages.push(clonePage(page))
-      caches.value = [...cacheSnapshot]
-      components.clear()
-      for (const [id, component] of componentSnapshot) components.set(id, component)
+      replacePages(currentTab.id, pageSnapshot)
+      restoreCaches(cacheSnapshot)
+      restoreComponents(componentSnapshot)
     }
   }
 
   const removeTab = (id: string): string => {
-    let activeTabId = ''
-    const currentTab = getTab(id)
-    const tabList = tabs.value
-    const i = tabList.findIndex((t) => t?.id === id)
-    if (i < 0) return ''
-
-    const tab = tabList[i]!
-    if (!tab.closable) return id
-
-    markTabPagesForEviction(tab)
-    tab.pages.clear()
-    if (tabList.length > 1 && tab.active) {
-      activeTabId = (i === 0 ? tabList[1] : tabList[i - 1])?.id ?? ''
-    }
-    tabs.value = [...tabList.slice(0, i), ...tabList.slice(i + 1)]
+    const result = removeTabFromStore(id)
+    if (result.status === 'not-found') return ''
+    if (result.status === 'not-closable') return id
 
-    if (activeTabId) {
-      emitter.emit(TabEventType.TAB_ACTIVE, { id: activeTabId })
-    }
-    if (!currentTab?.active) {
-      evictMarkedCaches()
-      tabIdsToEvict.clear()
+    if (result.nextActiveId) {
+      emitter.emit(TabEventType.TAB_ACTIVE, { id: result.nextActiveId })
     }
 
-    return activeTabId
+    return result.nextActiveId
   }
 
   /** 批量关闭满足条件的可关闭标签，并统一标记其页面缓存待驱逐。 */
-  const removeTabs = (shouldRemove: (tab: ITabItem, index: number) => boolean) => {
-    const removed: ITabItem[] = []
-    const remaining = tabs.value.filter((tab, index) => {
-      if (!tab.closable || !shouldRemove(tab, index)) return true
-      markTabPagesForEviction(tab)
-      tab.pages.clear()
-      removed.push(tab)
-      return false
-    })
-    tabs.value = remaining
-    return removed
-  }
+  const removeTabs = (shouldRemove: (tab: ITabItem, index: number) => boolean) =>
+    removeTabsFromStore(shouldRemove)
 
   const removeAllTabs = () => {
     removeTabs(() => true)
-    const hasActive = tabs.value.some((t) => t.active)
-    if (hasActive) {
+    if (getActiveTab()) {
       evictMarkedCaches()
-      tabIdsToEvict.clear()
+      clearTabEvictionMarks()
       return
     }
-    const last = tabs.value.at(-1)
+    const last = getTabs().at(-1)
     if (last) emitter.emit(TabEventType.TAB_ACTIVE, { id: last.id })
   }
 
@@ -533,42 +632,45 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
       emitter.emit(TabEventType.TAB_ACTIVE, { id })
     } else {
       evictMarkedCaches()
-      tabIdsToEvict.clear()
+      clearTabEvictionMarks()
     }
   }
 
   const removeLeftTabs = (id: string) => {
-    const pivot = tabs.value.findIndex((t) => t?.id === id)
+    const pivot = getTabs().findIndex((t) => t?.id === id)
     if (pivot <= 0) return
 
     removeTabs((_, index) => index < pivot)
-    if (tabs.value.some((t) => t.active)) {
+    if (getActiveTab()) {
       evictMarkedCaches()
-      tabIdsToEvict.clear()
+      clearTabEvictionMarks()
       return
     }
-    const first = tabs.value[0]
+    const first = getTabs()[0]
     if (first) emitter.emit(TabEventType.TAB_ACTIVE, { id: first.id })
   }
 
   const removeRightTabs = (id: string) => {
-    const pivot = tabs.value.findIndex((t) => t?.id === id)
-    if (pivot < 0 || pivot >= tabs.value.length - 1) return
+    const tabList = getTabs()
+    const pivot = tabList.findIndex((t) => t?.id === id)
+    if (pivot < 0 || pivot >= tabList.length - 1) return
 
     removeTabs((_, index) => index > pivot)
-    if (tabs.value.some((t) => t.active)) {
+    if (getActiveTab()) {
       evictMarkedCaches()
-      tabIdsToEvict.clear()
+      clearTabEvictionMarks()
       return
     }
-    const last = tabs.value.at(-1)
+    const last = getTabs().at(-1)
     if (last) emitter.emit(TabEventType.TAB_ACTIVE, { id: last.id })
   }
 
   const { refreshTab, refreshAllTabs } = createTabPanelRefresh({
-    tabs,
+    getTabs,
+    getTopPage,
+    updatePage,
+    updatePages,
     iframeRefreshKeys,
-    getTab,
     createPageId,
     addCache,
     evictPageCache,
@@ -576,8 +678,6 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     refreshIframeByPostMessage: (id) => emitter.emit(TabEventType.REFRESH_IFRAME_POSTMESSAGE, id)
   })
 
-  const getComponent = (id: string) => components.get(id)
-
   /**
    * 激活指定标签，更新 active 状态并可选跳转路由
    * @param id - 标签 id
@@ -589,9 +689,9 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     if (!target) return Promise.resolve()
     if (target.active) return Promise.resolve()
 
-    const top = target.pages.peek()
+    const top = getTopPage(id)
     const activateTarget = () => {
-      const activeTab = setActiveTab(id)
+      const activeTab = activateTab(id)
       if (activeTab) saveActiveTabToSession(activeTab)
     }
 
@@ -616,7 +716,7 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
 
     return runNavigationTransaction({
       apply: () => {
-        const prevActiveId = tabs.value.find((tab) => tab.active)?.id
+        const prevActiveId = getActiveTab()?.id
         // SSR 环境无 sessionStorage；快照为 null 时 rollback 视为「无变化」。
         const sessionSnapshot =
           typeof window !== 'undefined' ? window.sessionStorage.getItem(getSessionKey()) : null
@@ -625,7 +725,7 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
       },
       navigate: () => router.push({ path: top.path, query }),
       rollback: (snapshot) => {
-        setActiveTab(snapshot.prevActiveId ?? '')
+        activateTab(snapshot.prevActiveId ?? '')
         restoreActiveTabSession(snapshot.sessionSnapshot)
       },
       isFailureResult: isNavigationFailure,
@@ -636,13 +736,9 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
   const reset = () => removeAllTabs()
 
   const destroy = () => {
-    tabs.value = []
+    resetStore()
     defaultTabs.value = []
-    cacheIdsToEvict.clear()
-    tabIdsToEvict.clear()
     iframeRefreshKeys.value = {}
-    caches.value = []
-    components.clear()
     runtimeContext.scrollPositionsByPageId.clear()
     runtimeContext.isInitialized.value = false
     runtimeContext.refreshKey.value = 0
@@ -663,14 +759,26 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     initialize,
     size,
     active,
+    updateTabTitle,
     getCacheName: createCacheName,
     destroy,
     reset,
     addCache,
     removeCache,
     getTab,
+    getActiveTab,
+    getTopPage,
+    getPages,
+    getPageRefreshVersion,
+    getPageSnapshot,
     moveTab,
     addTab,
+    appendPage,
+    popPages,
+    replacePages,
+    clearPages,
+    updatePage,
+    updatePages,
     removeTab,
     removeAllTabs,
     removeLeftTabs,
@@ -679,12 +787,13 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     hasTab,
     renewTab,
     addPage,
-    addComponent: (id: string, comp: DefineComponent) => components.set(id, comp),
+    addComponent: setComponent,
     getComponent,
-    removeComponent: (id: string) => components.delete(id),
+    removeComponent: deleteComponent,
     markCacheForEviction,
     evictMarkedCaches,
     evictPageCache,
+    clearTabEvictionMarks,
     refreshTab,
     refreshAllTabs,
     iframeRefreshKeys,
@@ -698,3 +807,24 @@ export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
     }
   }
 }
+
+type TabPanelApi = ReturnType<typeof createTabPanelApi>
+
+const panelApiByContext = new WeakMap<StackTabsRuntimeContext, TabPanelApi>()
+
+/**
+ * 同一个运行时上下文复用同一套 panel API。
+ *
+ * StackTabs、StackKeepAlive、StackCacheRenderer、ContextMenu 与页面内的 useTabRouter
+ * 都会调用本 hook；首次调用在 setup 上下文中完成 useRouter/useI18n 注入，
+ * 后续调用直接返回缓存，避免重复创建 scroll/session/refresh 闭包与局部状态。
+ */
+export default (providedRuntimeContext?: StackTabsRuntimeContext): TabPanelApi => {
+  const runtimeContext = providedRuntimeContext ?? resolveStackTabsRuntimeContext()
+  const existing = panelApiByContext.get(runtimeContext)
+  if (existing) return existing
+
+  const panelApi = createTabPanelApi(runtimeContext)
+  panelApiByContext.set(runtimeContext, panelApi)
+  return panelApi
+}