vue-stack-tabs 1.3.1 → 1.4.2

package/src/lib/components/ContextMenu/index.vue

@@ -13,7 +13,7 @@
     :style="{
       left: `${menuPosition.left}px`,
       top: `${menuPosition.top}px`,
-      'z-index': getMaxZIndex('.stack-tab,.stack-tab *')
+      'z-index': menuZIndex()
     }"
     @keydown="handleMenuKeydown"
   >
@@ -84,7 +84,7 @@
 import { ref, onMounted, reactive, nextTick } from 'vue'
 import type { ITabItem, IContextMenu } from '../../model/TabModel'
 import { useI18n } from 'vue-i18n-lite'
-import { getMaxZIndex } from '../../utils/scrollUtils'
+import { getMaxZIndex, invalidateZIndexCache } from '../../utils/scrollUtils'
 import useTabActions from '../../hooks/useTabActions'
 import useTabPanel from '../../hooks/useTabPanel'
 import ContextMenuItem from './ContextMenuItem.vue'
@@ -115,6 +115,14 @@ const menuPosition = reactive({ left: props.left, top: props.top })
 const { closeTab, closeAllTabs, refreshTab, refreshAllTabs, openInNewWindow } = useTabActions()
 const { removeLeftTabs, removeRightTabs, removeOtherTabs } = useTabPanel()
 
+/**
+ * 菜单挂载时 z-index 必须重新计算（DOM 层叠已变化），先用 invalidateZIndexCache 失效再读取。
+ */
+const menuZIndex = () => {
+  invalidateZIndexCache('.stack-tab,.stack-tab *')
+  return getMaxZIndex('.stack-tab,.stack-tab *')
+}
+
 const focusActiveTabFallback = () => {
   const activeTab = document.querySelector<HTMLElement>('[role="tab"][aria-selected="true"]')
   activeTab?.focus()
@@ -193,7 +201,8 @@ const handleMenuKeydown = (event: KeyboardEvent) => {
   }
 }
 
-const getCustomMenuKey = (item: IContextMenu): string => item.key ?? `${item.title}-${item.icon ?? ''}`
+const getCustomMenuKey = (item: IContextMenu): string =>
+  item.key ?? `${item.title}-${item.icon ?? ''}`
 
 /** 挂载后修正菜单位置，避免超出右边界 */
 onMounted(() => {

package/src/lib/components/PageLoading.vue

@@ -11,7 +11,7 @@
     role="status"
     aria-live="polite"
     :aria-label="t('VueStackTab.loading')"
-    :style="{ zIndex: getMaxZIndex('.cache-page-wrapper *') }"
+    :style="{ zIndex: loadingZIndex() }"
   >
     <div class="stack-tab-loading--spin turn" aria-hidden="true" />
   </div>
@@ -20,7 +20,15 @@
 import { ref, onUnmounted } from 'vue'
 import { useI18n } from 'vue-i18n-lite'
 import { TabEventType, useTabEmitter } from '../hooks/useTabEventBus'
-import { getMaxZIndex } from '../utils/scrollUtils'
+import { getMaxZIndex, invalidateZIndexCache } from '../utils/scrollUtils'
+
+/**
+ * loading 遮罩每次显隐都会改变 .cache-page-wrapper 子树层叠，先失效缓存再读取避免旧值。
+ */
+const loadingZIndex = () => {
+  invalidateZIndexCache('.cache-page-wrapper *')
+  return getMaxZIndex('.cache-page-wrapper *')
+}
 const props = defineProps<{
   /** 当前标签 id，用于过滤 PAGE_LOADING 事件 */
   tabId: string

package/src/lib/components/StackKeepAlive/StackCacheRenderer.vue

@@ -11,10 +11,11 @@
   - 不负责 transition、keep-alive、TabHeader、iframe 或 session 初始化
 -->
 <script lang="ts" setup>
-import { defineComponent, shallowRef, watch } from 'vue'
+import { shallowRef, watch } from 'vue'
 import type { DefineComponent, VNode } from 'vue'
 import type { RouteLocationNormalizedLoaded } from 'vue-router'
 import useTabPanel from '../../hooks/useTabPanel'
+import { getEmptyPlaceholderComponent } from './emptyPlaceholder'
 
 interface StackCacheRendererProps {
   route: RouteLocationNormalizedLoaded
@@ -37,14 +38,7 @@ defineSlots<{
 
 const { refreshKey, activeCacheKey, activePageRefreshVersion, addPage } = useTabPanel()
 
-const EmptyRendererComponent = defineComponent({
-  name: 'StackCacheRendererEmpty',
-  setup() {
-    return () => null
-  }
-}) as DefineComponent
-
-const wrappedComponent = shallowRef<DefineComponent>(EmptyRendererComponent)
+const wrappedComponent = shallowRef<DefineComponent>(getEmptyPlaceholderComponent())
 
 const getComponentIdentity = (component?: VNode | null): unknown => {
   return component?.type ?? component

package/src/lib/components/StackKeepAlive/emptyPlaceholder.tsx

@@ -0,0 +1,18 @@
+/**
+ * 共享的 Empty 占位组件。
+ *
+ * useTabPanel 在「empty」/「recovered」分支会返回一个不渲染任何内容的占位组件。
+ * 原先在 pageComponentFactory.tsx 和 StackCacheRenderer.vue 各自定义了一份，
+ * 这里抽出唯一来源，避免两份略有差异的副本带来维护负担。
+ */
+import { defineComponent } from 'vue'
+import type { DefineComponent } from 'vue'
+
+export const EmptyPlaceholderComponent = defineComponent({
+  name: 'StackTabEmptyPlaceholder',
+  setup() {
+    return () => null
+  }
+}) as DefineComponent
+
+export const getEmptyPlaceholderComponent = (): DefineComponent => EmptyPlaceholderComponent

package/src/lib/components/TabHeader/index.vue

@@ -243,17 +243,18 @@ const handleTabListKeydown = (event: KeyboardEvent) => {
   if (count <= 0) return
 
   const currentIndex = getActiveTabIndex()
-  const safeIndex = currentIndex >= 0 ? currentIndex : 0
 
   if (event.key === 'ArrowRight') {
     event.preventDefault()
-    activateTabByIndex((safeIndex + 1) % count)
+    // 无 active 标签时从 -1 起步，按右方向键跳到第 0 个；正常情况环绕到下一个。
+    activateTabByIndex(currentIndex === -1 ? 0 : (currentIndex + 1) % count)
     return
   }
 
   if (event.key === 'ArrowLeft') {
     event.preventDefault()
-    activateTabByIndex((safeIndex - 1 + count) % count)
+    // 无 active 标签时按左方向键跳到最后一个；正常情况环绕到上一个。
+    activateTabByIndex(currentIndex === -1 ? count - 1 : (currentIndex - 1 + count) % count)
     return
   }
 

package/src/lib/hooks/stackTabsContext.ts

@@ -1,8 +1,9 @@
 /**
  * VueStackTabs 全局运行时上下文管理。
  *
- * 负责创建、注册、解析全局唯一的 StackTabsRuntimeContext，
- * 支持通过 Vue provide/inject 或模块级单例两种方式访问。
+ * 负责创建、注册、解析 StackTabsRuntimeContext。
+ * 业务运行时通过 Vue provide/inject 隔离；模块级回退仅保留给没有 App
+ * 容器的兼容调用（例如旧的单元测试），绝不能承载某个 Vue App 的状态。
  * 每个 Vue app 只允许注册一个 <VueStackTabs> 实例。
  */
 import type { App, DefineComponent, InjectionKey, Ref, ShallowRef } from 'vue'
@@ -77,7 +78,10 @@ export const createStackTabsRuntimeContext = (
   }
 }
 
-/** 获取当前活跃的运行时上下文（模块级单例） */
+/**
+ * 获取非 App 容器下注册的兼容上下文。
+ * @deprecated App 内的 composable 必须依赖 provide/inject，不应使用这个回退。
+ */
 export const getActiveStackTabsRuntimeContext = (): StackTabsRuntimeContext | null =>
   activeRuntimeContext
 
@@ -86,22 +90,21 @@ export const registerStackTabsRuntimeContext = (
   context: StackTabsRuntimeContext,
   options: RegisterStackTabsRuntimeContextOptions = {}
 ): boolean => {
-  if (!activeRuntimeContext) {
-    activeRuntimeContext = context
-  }
-
   if (options.app && !runtimeContextOwnersByApp.has(options.app)) {
     runtimeContextOwnersByApp.add(options.app)
     return true
   }
 
-  if (
-    !options.app &&
-    activeRuntimeContext === context &&
-    !isFallbackRuntimeContextOwnerRegistered
-  ) {
-    isFallbackRuntimeContextOwnerRegistered = true
-    return true
+  if (!options.app) {
+    if (!activeRuntimeContext) {
+      activeRuntimeContext = context
+      isFallbackRuntimeContextOwnerRegistered = true
+      return true
+    }
+    if (activeRuntimeContext === context && !isFallbackRuntimeContextOwnerRegistered) {
+      isFallbackRuntimeContextOwnerRegistered = true
+      return true
+    }
   }
 
   const isProduction = options.isProduction ?? import.meta.env.PROD
@@ -118,13 +121,15 @@ export const unregisterStackTabsRuntimeContext = (
   context: StackTabsRuntimeContext,
   options: UnregisterStackTabsRuntimeContextOptions = {}
 ): void => {
-  if (options.app) runtimeContextOwnersByApp.delete(options.app)
-  if (!options.app && activeRuntimeContext === context)
-    isFallbackRuntimeContextOwnerRegistered = false
+  if (options.app) {
+    runtimeContextOwnersByApp.delete(options.app)
+    return
+  }
+  if (activeRuntimeContext === context) isFallbackRuntimeContextOwnerRegistered = false
   if (activeRuntimeContext === context) activeRuntimeContext = null
 }
 
-/** 解析当前可用的运行时上下文，优先使用 inject，回退到模块单例 */
+/** 解析当前可用的运行时上下文，优先使用 inject，兼容回退仅限非 App 容器。 */
 export const resolveStackTabsRuntimeContext = (): StackTabsRuntimeContext => {
   const injected = hasInjectionContext() ? inject(stackTabsContextKey, null) : null
   const context = injected ?? activeRuntimeContext

package/src/lib/hooks/tabPanel/pageComponentFactory.tsx

@@ -0,0 +1,136 @@
+/**
+ * 页面缓存组件工厂。
+ *
+ * 将 keep-alive 包装、VNode 注入和页面激活生命周期从 tab 状态编排中隔离，
+ * 使 useTabPanel 只负责领域状态与路由协调。
+ */
+import {
+  cloneVNode,
+  defineComponent,
+  onActivated,
+  onDeactivated,
+  onMounted,
+  onUnmounted,
+  ref,
+  shallowRef
+} from 'vue'
+import type { DefineComponent, PropType, VNode } from 'vue'
+import type { ITabBase } from '../../model/TabModel'
+import PageLoading from '../../components/PageLoading.vue'
+import type { StackTabsRuntimeContext } from '../stackTabsContext'
+import { useScrollShadow } from '../useScrollShadow'
+
+interface PageComponentFactoryOptions {
+  runtimeContext: StackTabsRuntimeContext
+  consumeBackParams: (tabId: string, pageId: string) => Record<string, unknown> | null
+  getComponent: (id: string) => DefineComponent | undefined
+  setComponent: (id: string, component: DefineComponent) => void
+  addCache: (cacheName: string) => void
+  evictMarkedCaches: () => void
+  clearTabEvictionMarks: () => void
+  addPageScroller: (pageId: string, ...selectors: string[]) => void
+  saveScroller: (pageId: string) => void
+  restoreScroller: (pageId: string) => void
+  removeScroller: (pageId: string) => void
+}
+
+export const createPageComponentFactory = (options: PageComponentFactoryOptions) => {
+  const {
+    runtimeContext,
+    consumeBackParams,
+    getComponent,
+    setComponent,
+    addCache,
+    evictMarkedCaches,
+    clearTabEvictionMarks,
+    addPageScroller,
+    saveScroller,
+    restoreScroller,
+    removeScroller
+  } = options
+
+  const resolvePageComponent = (ctx: { cacheName: string; tabInfo: ITabBase }): DefineComponent => {
+    const { cacheName, tabInfo } = ctx
+    const existing = getComponent(cacheName)
+    if (existing) {
+      addCache(cacheName)
+      return existing
+    }
+
+    const cacheComponent = defineComponent<{ vnode?: VNode }>({
+      name: cacheName,
+      props: {
+        vnode: {
+          type: Object as PropType<VNode>,
+          required: false,
+          default: undefined
+        }
+      },
+      emits: ['onLoaded'],
+      setup(props, context) {
+        const localBackParams = ref<Record<string, unknown> | null>(null)
+        const lastVnode = shallowRef<VNode | null | undefined>(null)
+        const lastCloned = shallowRef<VNode | null>(null)
+        const lastBackParams = shallowRef<Record<string, unknown> | null>(null)
+        const pageRoot = ref<HTMLElement | null>(null)
+
+        const checkAndConsumeBackParams = () => {
+          localBackParams.value = consumeBackParams(tabInfo.id!, cacheName)
+        }
+
+        onMounted(() => {
+          context.emit('onLoaded')
+          addPageScroller(cacheName, `#W-${cacheName}`)
+          checkAndConsumeBackParams()
+        })
+        onDeactivated(() => saveScroller(cacheName))
+        onActivated(() => {
+          context.emit('onLoaded')
+          restoreScroller(cacheName)
+          evictMarkedCaches()
+          clearTabEvictionMarks()
+          checkAndConsumeBackParams()
+        })
+        onUnmounted(() => removeScroller(cacheName))
+
+        // 给 .cache-page-wrapper 挂滚动阴影，确保 keep-alive 的 suspended/deactivated 生命周期下表现一致
+        useScrollShadow({ target: pageRoot })
+
+        return () => {
+          const vnode = props.vnode
+          const backParams = localBackParams.value
+          if (vnode !== lastVnode.value || backParams !== lastBackParams.value) {
+            lastCloned.value = vnode
+              ? cloneVNode(vnode, {
+                  tId: tabInfo.id,
+                  pId: cacheName,
+                  ...(backParams ? { _back: backParams } : {})
+                })
+              : null
+            lastVnode.value = vnode
+            lastBackParams.value = backParams
+          }
+          return (
+            <div
+              ref={pageRoot}
+              class="cache-page-wrapper"
+              id={`W-${cacheName}`}
+              style={[
+                runtimeContext.useGlobalScroll.value ? 'overflow:auto' : 'overflow:hidden',
+                'height: 100%'
+              ]}
+            >
+              {lastCloned.value}
+              <PageLoading tabId={tabInfo.id!} />
+            </div>
+          )
+        }
+      }
+    }) as DefineComponent
+    setComponent(cacheName, cacheComponent)
+    addCache(cacheName)
+    return cacheComponent
+  }
+
+  return { resolvePageComponent }
+}

package/src/lib/hooks/tabPanel/refresh.ts

@@ -4,7 +4,8 @@
  * 活动普通页面保持 cache id 稳定，只递增页面级刷新版本；非活动页面可直接替换缓存。
  */
 import type { Ref } from 'vue'
-import type { ITabItem } from '../../model/TabModel'
+import type { ITabItem, ITabPage } from '../../model/TabModel'
+import type { PagePatch } from './tabStore'
 
 export interface TabPanelRefreshApi {
   refreshTab: (id: string) => void
@@ -12,9 +13,11 @@ export interface TabPanelRefreshApi {
 }
 
 export interface CreateTabPanelRefreshOptions {
-  tabs: Ref<ITabItem[]>
+  getTabs: () => readonly ITabItem[]
+  getTopPage: (tabId: string) => ITabPage | null
+  /** 修改页面字段（刷新版本 / 页面 id）并触发 tabs 更新 */
+  updatePage: (tabId: string, pageId: string, patch: PagePatch) => boolean
   iframeRefreshKeys: Ref<Record<string, number>>
-  getTab: (id: string) => ITabItem | null
   createPageId: () => string
   addCache: (cacheName: string) => void
   evictPageCache: (cacheName: string) => void
@@ -29,9 +32,10 @@ export const createTabPanelRefresh = (
   options: CreateTabPanelRefreshOptions
 ): TabPanelRefreshApi => {
   const {
-    tabs,
+    getTabs,
+    getTopPage,
+    updatePage,
     iframeRefreshKeys,
-    getTab,
     createPageId,
     addCache,
     evictPageCache,
@@ -51,28 +55,31 @@ export const createTabPanelRefresh = (
   }
 
   const refreshPage = (tab: ITabItem, cacheNamesToEvict?: string[], cacheNamesToAdd?: string[]) => {
-    const currentPage = tab.pages.peek()
+    const currentPage = getTopPage(tab.id)
     if (!currentPage) return
 
     if (tab.active) {
-      currentPage.refreshVersion = (currentPage.refreshVersion ?? 0) + 1
+      // updatePage 内部会触发 tabs 更新，activePageRefreshVersion 随之重新求值。
+      updatePage(tab.id, currentPage.id, {
+        refreshVersion: (currentPage.refreshVersion ?? 0) + 1
+      })
       return
     }
 
     const oldCacheName = currentPage.id
-    currentPage.id = createPageId()
-    currentPage.refreshVersion = 0
+    const nextPageId = createPageId()
+    updatePage(tab.id, oldCacheName, { id: nextPageId, refreshVersion: 0 })
     if (cacheNamesToEvict && cacheNamesToAdd) {
       cacheNamesToEvict.push(oldCacheName)
-      cacheNamesToAdd.push(currentPage.id)
+      cacheNamesToAdd.push(nextPageId)
       return
     }
     evictPageCache(oldCacheName)
-    addCache(currentPage.id)
+    addCache(nextPageId)
   }
 
   const refreshTab = (id: string) => {
-    const tab = getTab(id)
+    const tab = getTabs().find((item) => item.id === id)
     if (!tab?.refreshable) return
     if (tab.iframe) {
       refreshIframe(tab)
@@ -87,7 +94,7 @@ export const createTabPanelRefresh = (
     const iframeKeysUpdate = { ...iframeRefreshKeys.value }
     let iframeKeysChanged = false
 
-    for (const tab of tabs.value) {
+    for (const tab of getTabs()) {
       if (!tab.refreshable) continue
       if (tab.iframe) {
         if (tab.iframeRefreshMode === 'reload') {

package/src/lib/hooks/tabPanel/scroll.ts

@@ -2,6 +2,8 @@
  * tabPanel/scroll - 滚动位置保存与恢复
  *
  * 职责：基于当前 StackTabsRuntimeContext 在切出/切入页面时保存和恢复滚动位置。
+ * 优化：用 MutationObserver 缓存 [data-stack-tab-scroll] 元素列表，
+ *       避免每次 deactivate 都全量 querySelectorAll。
  */
 import type { StackTabsRuntimeContext } from '../stackTabsContext'
 
@@ -10,6 +12,8 @@ export interface TabPanelScrollApi {
   saveScroller: (pageCacheId: string) => void
   removeScroller: (pageCacheId: string) => void
   addPageScroller: (pageCacheId: string, ...selectorIds: string[]) => void
+  /** 主动失效某页面的滚动元素缓存，例如外部强制刷新缓存页时 */
+  invalidateAutoScrollCache: (pageCacheId: string) => void
 }
 
 const resolveScrollElement = (selector: string): HTMLElement | null =>
@@ -17,6 +21,73 @@ const resolveScrollElement = (selector: string): HTMLElement | null =>
     ? document.getElementById(selector.slice(1))
     : (document.querySelector(selector) as HTMLElement | null)
 
+const AUTO_SCROLLER_PREFIX = '__stack-tab-auto-scroll__:'
+
+interface AutoScrollCache {
+  elements: HTMLElement[]
+  observer: MutationObserver | null
+}
+
+/**
+ * 在 pageRoot 上挂一个 MutationObserver，自动维护 [data-stack-tab-scroll] 元素列表；
+ * 列表变化时无需上层主动失效，下次读到的就是最新值。
+ */
+const createAutoScrollCache = (pageRoot: HTMLElement): AutoScrollCache => {
+  const collect = (): HTMLElement[] =>
+    Array.from(pageRoot.querySelectorAll<HTMLElement>('[data-stack-tab-scroll]'))
+
+  const cache: AutoScrollCache = {
+    elements: collect(),
+    observer: null
+  }
+
+  if (typeof MutationObserver !== 'undefined') {
+    cache.observer = new MutationObserver(() => {
+      cache.elements = collect()
+    })
+    // 仅监听子树增删与属性变化，不监听字符数据，减少开销。
+    cache.observer.observe(pageRoot, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['data-stack-tab-scroll']
+    })
+  }
+
+  return cache
+}
+
+const autoScrollCaches = new Map<string, AutoScrollCache>()
+
+const getAutoScrollCache = (pageCacheId: string): AutoScrollCache | null => {
+  const pageRoot = document.getElementById(`W-${pageCacheId}`)
+  if (!pageRoot) {
+    autoScrollCaches.delete(pageCacheId)
+    return null
+  }
+
+  let cache = autoScrollCaches.get(pageCacheId)
+  if (!cache) {
+    cache = createAutoScrollCache(pageRoot)
+    autoScrollCaches.set(pageCacheId, cache)
+  } else {
+    // 防御：检查 pageRoot 是否已被替换（极端情况：同一 pageCacheId 重新挂载）
+    if (cache.elements.length === 0 && cache.observer) {
+      cache.elements = Array.from(pageRoot.querySelectorAll<HTMLElement>('[data-stack-tab-scroll]'))
+    }
+  }
+  return cache
+}
+
+const getAutoScrollerKey = (index: number): string => `${AUTO_SCROLLER_PREFIX}${index}`
+
+const resolveAutoScrollElement = (pageCacheId: string, key: string): HTMLElement | null => {
+  const index = Number(key.slice(AUTO_SCROLLER_PREFIX.length))
+  if (!Number.isInteger(index)) return null
+  const cache = getAutoScrollCache(pageCacheId)
+  return cache?.elements[index] ?? null
+}
+
 export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanelScrollApi => {
   const { scrollPositionsByPageId } = context
 
@@ -25,7 +96,9 @@ export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanel
     if (!positions) return
 
     for (const [selector, position] of positions) {
-      const element = resolveScrollElement(selector)
+      const element = selector.startsWith(AUTO_SCROLLER_PREFIX)
+        ? resolveAutoScrollElement(pageCacheId, selector)
+        : resolveScrollElement(selector)
       if (element) {
         element.scrollTop = position.top
         element.scrollLeft = position.left
@@ -37,8 +110,23 @@ export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanel
     const positions = scrollPositionsByPageId.get(pageCacheId)
     if (!positions) return
 
+    // 与当前页面 DOM 同步自动标记的容器；移除的元素不保留过期位置。
+    for (const key of positions.keys()) {
+      if (key.startsWith(AUTO_SCROLLER_PREFIX)) positions.delete(key)
+    }
+    const cache = getAutoScrollCache(pageCacheId)
+    const elements = cache?.elements ?? []
+    elements.forEach((element, index) => {
+      positions.set(getAutoScrollerKey(index), {
+        top: element.scrollTop,
+        left: element.scrollLeft
+      })
+    })
+
     for (const selector of positions.keys()) {
-      const element = resolveScrollElement(selector)
+      const element = selector.startsWith(AUTO_SCROLLER_PREFIX)
+        ? resolveAutoScrollElement(pageCacheId, selector)
+        : resolveScrollElement(selector)
       positions.set(selector, {
         top: element?.scrollTop ?? 0,
         left: element?.scrollLeft ?? 0
@@ -48,10 +136,16 @@ export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanel
 
   const removeScroller = (pageCacheId: string): void => {
     const positions = scrollPositionsByPageId.get(pageCacheId)
-    if (!positions) return
-
-    positions.clear()
-    scrollPositionsByPageId.delete(pageCacheId)
+    if (positions) {
+      positions.clear()
+      scrollPositionsByPageId.delete(pageCacheId)
+    }
+    // 同步卸载 MutationObserver，避免页面被驱逐后 observer 仍持有 DOM 引用。
+    const cache = autoScrollCaches.get(pageCacheId)
+    if (cache) {
+      cache.observer?.disconnect()
+      autoScrollCaches.delete(pageCacheId)
+    }
   }
 
   const addPageScroller = (pageCacheId: string, ...selectorIds: string[]): void => {
@@ -64,10 +158,19 @@ export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanel
     }
   }
 
+  const invalidateAutoScrollCache = (pageCacheId: string): void => {
+    const cache = autoScrollCaches.get(pageCacheId)
+    if (!cache) return
+    cache.elements = []
+    cache.observer?.disconnect()
+    autoScrollCaches.delete(pageCacheId)
+  }
+
   return {
     restoreScroller,
     saveScroller,
     removeScroller,
-    addPageScroller
+    addPageScroller,
+    invalidateAutoScrollCache
   }
 }

package/src/lib/hooks/tabPanel/session.ts

@@ -33,12 +33,38 @@ export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPane
   let writeVersion = 0
   let writeScheduled = false
 
+  /**
+   * 写入 sessionStorage，捕获隐私模式（QuotaExceededError）等异常，
+   * 避免在受限浏览器环境下抛出未处理错误。SSR 环境无 window 时直接跳过。
+   */
+  const safeSetItem = (key: string, value: string): void => {
+    if (typeof window === 'undefined') return
+    try {
+      window.sessionStorage.setItem(key, value)
+    } catch (error) {
+      if (!import.meta.env.PROD) {
+        console.warn('[vue-stack-tabs] Failed to write sessionStorage:', error)
+      }
+    }
+  }
+
+  const safeRemoveItem = (key: string): void => {
+    if (typeof window === 'undefined') return
+    try {
+      window.sessionStorage.removeItem(key)
+    } catch (error) {
+      if (!import.meta.env.PROD) {
+        console.warn('[vue-stack-tabs] Failed to clear sessionStorage:', error)
+      }
+    }
+  }
+
   const flushPendingWrite = () => {
     writeScheduled = false
     const write = pendingWrite
     pendingWrite = null
     if (!write || write.version !== writeVersion) return
-    window.sessionStorage.setItem(getSessionKey(), JSON.stringify(write.tab))
+    safeSetItem(getSessionKey(), JSON.stringify(write.tab))
   }
 
   const invalidatePendingWrite = () => {
@@ -56,7 +82,7 @@ export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPane
 
   const clearSession = (): void => {
     invalidatePendingWrite()
-    window.sessionStorage.removeItem(getSessionKey())
+    safeRemoveItem(getSessionKey())
   }
 
   const restoreActiveTabSession = (storedJson: string | null): void => {
@@ -65,7 +91,7 @@ export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPane
       return
     }
     invalidatePendingWrite()
-    window.sessionStorage.setItem(getSessionKey(), storedJson)
+    safeSetItem(getSessionKey(), storedJson)
   }
 
   const restoreTabFromSession = (storedJson: string | null): ITabItem | null => {