vue-stack-tabs 1.3.1 → 1.4.1

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "vue-stack-tabs",
-  "version": "1.3.1",
-  "packageManager": "pnpm@11.21.0+sha512.521705bce689924eac72f5a3587122f362689ef6571e55ba80076fd637c11132ecffada26fad4ea79c485bfddbfd3d5a2a5b05805a77e893de71ec8a6cca3bb1",
+  "version": "1.4.1",
   "private": false,
   "type": "module",
+  "description": "Vue 3 multi-tab manager built on Vue Router with iframe-like tab isolation: per-tab component scope, stack-based forward/backward navigation, keep-alive page caching, scroll position memory, i18n and a Nuxt 3/4 module.",
   "files": [
     "src/lib",
     "dist"
   ],
+  "sideEffects": [
+    "**/*.css",
+    "**/*.scss"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -25,7 +29,9 @@
     "./dist/vue-stack-tabs.css": "./dist/vue-stack-tabs.css"
   },
   "peerDependencies": {
-    "nuxt": "^3.0.0 || ^4.0.0"
+    "nuxt": "^3.0.0 || ^4.0.0",
+    "vue": "^3.5.43",
+    "vue-router": "^5.4.0"
   },
   "peerDependenciesMeta": {
     "nuxt": {
@@ -34,6 +40,7 @@
   },
   "main": "./dist/vue-stack-tabs.es.js",
   "module": "./dist/vue-stack-tabs.es.js",
+  "types": "./dist/index.d.ts",
   "typings": "./dist/index.d.ts",
   "repository": {
     "type": "git",
@@ -41,20 +48,39 @@
   },
   "keywords": [
     "vue",
-    "vue router",
+    "vue3",
+    "vue-router",
+    "router",
     "tabs",
-    "nuxt"
+    "tab",
+    "tab-panel",
+    "multi-tab",
+    "tabs-router",
+    "keep-alive",
+    "cache",
+    "iframe",
+    "nuxt",
+    "nuxt3",
+    "nuxt-module",
+    "navigation",
+    "vue-component",
+    "typescript"
   ],
   "author": "tantan",
-  "license": "Apache License, Version 2.0",
+  "license": "Apache-2.0",
   "bugs": {
     "url": "https://github.com/jktantan/vue-stack-tabs/issues"
   },
-  "homepage": "https://github.com/jktantan/vue-stack-tabs.git",
+  "homepage": "https://jktantan.github.io/vue-stack-tabs/",
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "clean:ports": "node -e \"const { execSync } = require('child_process'); try { if (process.platform === 'win32') { execSync('netstat -ano | findstr \":5173\" | findstr \"LISTENING\"').toString().split('\\n').forEach(line => { const pid = line.trim().split(/\\s+/)[4]; if (pid) try { execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore' }); } catch(e) {} }); execSync('netstat -ano | findstr \":5174\" | findstr \"LISTENING\"').toString().split('\\n').forEach(line => { const pid = line.trim().split(/\\s+/)[4]; if (pid) try { execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore' }); } catch(e) {} }); } else { execSync('lsof -ti:5173 | xargs kill -9 || true', { shell: '/bin/bash' }); execSync('lsof -ti:5174 | xargs kill -9 || true', { shell: '/bin/bash' }); } console.log('✅ 端口清理完成'); } catch(e) { console.log('✅ 端口已经空闲或清理完成'); }\"",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs && vite build --config vite.config.docs-demo.ts && node -e \"const fs=require('fs');const p='docs/.vitepress/dist/demo';fs.mkdirSync(p+'/demo',{recursive:true});fs.copyFileSync(p+'/index.html',p+'/demo/index.html');\"",
+    "docs:dev": "run-p docs:dev:docs docs:dev:demo",
+    "docs:dev:docs": "vitepress dev docs",
+    "docs:dev:demo": "vite --config vite.config.docs-demo.ts",
+    "docs:build": "vitepress build docs && vite build --config vite.config.docs-demo.ts",
     "dev": "vite  --host ",
     "build": "run-p type-check \"build-only {@}\" --",
     "preview": "vite preview",
@@ -64,64 +90,60 @@
     "lint:check": "eslint .",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "lib:build": "vite --config vite.config.lib.ts build && vite --config vite.config.iframe-bridge.ts build && vite --config vite.config.nuxt.ts build && node -e \"const fs=require('fs');fs.copyFileSync('dist/vue-stack-tabs.css','dist/style.css');fs.copyFileSync('dist/src/lib/iframe-bridge.d.ts','dist/iframe-bridge.d.ts');fs.mkdirSync('dist/utils',{recursive:true});fs.copyFileSync('dist/src/lib/utils/iframeBridge.d.ts','dist/utils/iframeBridge.d.ts');fs.mkdirSync('dist/nuxt',{recursive:true});fs.copyFileSync('dist/src/lib/nuxt/module.d.ts','dist/nuxt/module.d.ts');fs.mkdirSync('dist/nuxt/runtime',{recursive:true});fs.copyFileSync('dist/src/lib/nuxt/runtime/plugin.d.ts','dist/nuxt/runtime/plugin.d.ts');fs.copyFileSync('dist/nuxt/plugin.mjs','dist/nuxt/runtime/plugin.mjs')\"",
+    "lib:build": "vite --config vite.config.lib.ts build && vite --config vite.config.iframe-bridge.ts build && vite --config vite.config.nuxt.ts build && node -e \"const fs=require('fs');fs.copyFileSync('dist/vue-stack-tabs.css','dist/style.css');fs.rmSync('dist/src',{recursive:true,force:true});\"",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:prepack": "node scripts/verify-prepack.mjs",
-    "test:packaged": "pnpm run lib:build && node scripts/verify-packaged.mjs"
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "defu": "^6.1.7",
     "mitt": "^3.0.1",
-    "nostics": "^1.2.0",
+    "nostics": "^1.3.0",
     "throttle-debounce": "^5.0.2",
-    "vue": "^3.5.42",
-    "vue-i18n-lite": "^1.0.2",
-    "vue-router": "^5.3.0"
+    "vue-i18n-lite": "^1.0.2"
   },
   "devDependencies": {
-    "@ctrl/tinycolor": "^4.2.0",
+    "@ctrl/tinycolor": "^4.2.1",
     "@element-plus/icons-vue": "^2.3.2",
     "@eslint/js": "^10.0.1",
     "@floating-ui/core": "^1.8.0",
     "@floating-ui/dom": "^1.8.0",
     "@floating-ui/utils": "^0.2.12",
-    "@mdit/plugin-tasklist": "^1.1.0",
+    "@mdit/plugin-tasklist": "^1.1.3",
     "@popperjs/core": "^2.11.8",
     "@rushstack/eslint-patch": "^1.16.1",
     "@tsconfig/node26": "^26.0.1",
     "@types/lodash-es": "^4.17.12",
-    "@types/node": "^26.4.0",
+    "@types/node": "^26.6.5",
     "@types/throttle-debounce": "^5.0.2",
-    "@vitejs/plugin-vue": "^6.0.8",
+    "@vitejs/plugin-vue": "^6.0.10",
     "@vitejs/plugin-vue-jsx": "^5.1.6",
     "@vitest/coverage-v8": "4.1.10",
-    "@vue/compiler-core": "^3.5.42",
-    "@vue/compiler-dom": "^3.5.42",
+    "@vue/compiler-core": "^3.5.43",
+    "@vue/compiler-dom": "^3.5.43",
     "@vue/devtools-api": "^8.2.1",
     "@vue/devtools-kit": "^8.2.1",
     "@vue/devtools-shared": "^8.2.1",
     "@vue/eslint-config-prettier": "^10.2.0",
     "@vue/eslint-config-typescript": "^14.9.0",
-    "@vue/reactivity": "^3.5.42",
-    "@vue/runtime-core": "^3.5.42",
-    "@vue/runtime-dom": "^3.5.42",
-    "@vue/shared": "^3.5.42",
-    "@vue/test-utils": "^2.5.0",
+    "@vue/reactivity": "^3.5.43",
+    "@vue/runtime-core": "^3.5.43",
+    "@vue/runtime-dom": "^3.5.43",
+    "@vue/shared": "^3.5.43",
+    "@vue/test-utils": "^2.5.1",
     "@vue/tsconfig": "^0.9.1",
     "@vueuse/core": "^14.4.0",
     "@vueuse/shared": "^14.4.0",
     "async-validator": "^4.2.5",
     "birpc": "^4.2.0",
     "dayjs": "^1.11.23",
-    "element-plus": "^2.14.5",
-    "eslint": "^10.9.1",
+    "element-plus": "^2.14.7",
+    "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-vue": "^10.10.0",
-    "globals": "^17.11.0",
-    "happy-dom": "^20.12.0",
-    "hookable": "^6.1.1",
+    "eslint-plugin-vue": "^10.11.1",
+    "globals": "^17.13.0",
+    "happy-dom": "^20.14.6",
+    "hookable": "^6.1.2",
     "lodash-es": "^4.18.1",
     "lodash-unified": "^1.0.3",
     "memoize-one": "^6.0.0",
@@ -129,18 +151,20 @@
     "normalize.css": "^8.0.1",
     "npm-run-all2": "^9.0.3",
     "perfect-debounce": "^2.1.0",
-    "prettier": "^3.9.6",
-    "sass-embedded": "^1.103.1",
+    "prettier": "^3.9.10",
+    "sass-embedded": "^1.105.1",
     "terser": "^5.51.2",
-    "typescript": "~7.0.2",
-    "typescript-eslint": "^8.69.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.1",
     "unplugin-auto-import": "^21.1.0",
     "unplugin-vue-components": "^32.1.0",
-    "vite": "^8.2.2",
+    "vite": "^8.3.4",
     "vite-plugin-dts": "5.0.3",
     "vite-plugin-package-version": "^1.1.0",
     "vitepress": "^1.6.4",
     "vitest": "^4.1.11",
-    "vue-tsc": "^3.3.11"
+    "vue": "^3.5.43",
+    "vue-router": "^5.4.0",
+    "vue-tsc": "^3.3.13"
   }
 }

package/src/lib/StackTabs.vue

@@ -22,7 +22,7 @@ import {
   watch
 } from 'vue'
 import type { TransitionProps } from 'vue'
-import { getMaxZIndex } from './utils/scrollUtils'
+import { getMaxZIndex, invalidateZIndexCache } from './utils/scrollUtils'
 import { isAllowedTabUrl } from './utils/urlParser'
 import { applyStackTabsLocale } from './i18n/stackTabsLocale'
 import { type ITabData, TabScrollMode } from './model/TabModel'
@@ -96,6 +96,17 @@ const props = withDefaults(
     iframeLoadTimeout: 15000
   }
 )
+
+// iframePath 必填：用于 iframe 占位页（StackTabs 把 iframe 标签路由到这个 path 渲染）。
+// 这里在开发期给出明确错误，避免空字符串导致 router.push({ path: '' }) 跳到首页的隐式行为。
+if (typeof props.iframePath !== 'string' || props.iframePath.trim() === '') {
+  const message = '[vue-stack-tabs] <VueStackTabs> requires the "iframePath" prop (e.g. "/iframe").'
+  if (!import.meta.env.PROD) {
+    throw new Error(message)
+  }
+  console.error(message)
+}
+
 const { changeLocale, t } = useI18n()
 const runtimeContext =
   inject(stackTabsContextKey, null) ??
@@ -120,10 +131,12 @@ if (isRuntimeContextOwner) {
   provide(maximumKey, maximum)
 }
 watch(maximum, (isMaximum) => {
+  // 最大化切换会显著改变 body 下元素层叠顺序，先失效缓存再读取避免过期结果。
+  invalidateZIndexCache()
   maximumZIndex.value = isMaximum ? getMaxZIndex('body *:not(.stack-tab,.stack-tab *)') : undefined
 })
 const panelApi = isRuntimeContextOwner
-  ? useTabPanel()
+  ? useTabPanel(runtimeContext)
   : {
       tabs: runtimeContext.tabs,
       iframeRefreshKeys: runtimeContext.iframeRefreshKeys,
@@ -143,7 +156,7 @@ const {
   setSessionPrefix
 } = panelApi
 const tabActions = isRuntimeContextOwner
-  ? useTabActions()
+  ? useTabActions(runtimeContext)
   : {
       setIFramePath: () => undefined,
       openTab: () => Promise.resolve(undefined),

package/src/lib/assets/style/common/var.scss

@@ -63,4 +63,6 @@ $stack-tab-shadow-left: -5px 0 5px -5px rgb(0 0 0 / 60%); //#ccc;
 $stack-tab-shadow-right: 5px 0 5px -5px rgb(0 0 0 / 60%); //#ccc;
 $stack-tab-shadow-right-inset: inset -5px 0 5px -5px rgb(0 0 0 / 60%); //#ccc;
 $stack-tab-shadow-left-inset: inset 5px 0 5px -5px rgb(0 0 0 / 60%); //#ccc;
+$stack-tab-shadow-top-inset: inset 0 5px 5px -5px rgb(0 0 0 / 60%); //#ccc;
+$stack-tab-shadow-bottom-inset: inset 0 -5px 5px -5px rgb(0 0 0 / 60%); //#ccc;
 $stack-tab-shadow-context-menu: 5px 5px 5px rgb(0 0 0 / 10%);

package/src/lib/assets/style/stackTab.scss

@@ -443,7 +443,6 @@
     border-radius: 10px 0;
     box-shadow: $stack-tab-shadow-context-menu;
     transform-origin: left top;
-    transition: all 0.25s ease-in;
 
     &-item {
       display: flex;
@@ -464,7 +463,10 @@
       background: transparent;
       border: 0;
       border-radius: 10px 0;
-      transition: all 0.2s ease-in-out;
+      // 仅过渡悬停态实际会改变的颜色，避免触发菜单布局与合成层的无关动画。
+      transition:
+        color 0.2s ease-in-out,
+        background-color 0.2s ease-in-out;
       user-select: none;
 
       &:hover,
@@ -497,7 +499,7 @@
     &-icon {
       width: $stack-tab-font-size;
       height: $stack-tab-font-size;
-      transition: all 0.2s ease-in-out;
+      transition: background-color 0.2s ease-in-out;
 
       &.svg-mask {
         width: $stack-tab-font-size;
@@ -532,4 +534,16 @@
     @include mixins.insetShadow();
     box-shadow: $stack-tab-shadow-left-inset, $stack-tab-shadow-right-inset;
   }
+  &-top::after {
+    @include mixins.insetShadow();
+    box-shadow: $stack-tab-shadow-top-inset;
+  }
+  &-bottom::after {
+    @include mixins.insetShadow();
+    box-shadow: $stack-tab-shadow-bottom-inset;
+  }
+  &-vertical::after {
+    @include mixins.insetShadow();
+    box-shadow: $stack-tab-shadow-top-inset, $stack-tab-shadow-bottom-inset;
+  }
 }

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,142 @@
+/**
+ * 页面缓存组件工厂。
+ *
+ * 将 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, ITabItem } from '../../model/TabModel'
+import PageLoading from '../../components/PageLoading.vue'
+import type { StackTabsRuntimeContext } from '../stackTabsContext'
+import { useScrollShadow } from '../useScrollShadow'
+
+interface PageComponentFactoryOptions {
+  runtimeContext: StackTabsRuntimeContext
+  getTab: (id: string) => ITabItem | null
+  addCache: (cacheName: string) => void
+  evictMarkedCaches: () => 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,
+    getTab,
+    addCache,
+    evictMarkedCaches,
+    addPageScroller,
+    saveScroller,
+    restoreScroller,
+    removeScroller
+  } = options
+  const { components, tabIdsToEvict } = runtimeContext
+
+  const resolvePageComponent = (ctx: { cacheName: string; tabInfo: ITabBase }): DefineComponent => {
+    const { cacheName, tabInfo } = ctx
+    const existing = components.get(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 = () => {
+          try {
+            const tab = getTab(tabInfo.id!)
+            const top = tab?.pages.peek()
+            if (top && top.id === cacheName && top._backParams) {
+              localBackParams.value = { ...top._backParams }
+              delete top._backParams
+            } else {
+              localBackParams.value = null
+            }
+          } catch {
+            localBackParams.value = null
+          }
+        }
+
+        onMounted(() => {
+          context.emit('onLoaded')
+          addPageScroller(cacheName, `#W-${cacheName}`)
+          checkAndConsumeBackParams()
+        })
+        onDeactivated(() => saveScroller(cacheName))
+        onActivated(() => {
+          context.emit('onLoaded')
+          restoreScroller(cacheName)
+          evictMarkedCaches()
+          tabIdsToEvict.clear()
+          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
+    components.set(cacheName, cacheComponent)
+    addCache(cacheName)
+    return cacheComponent
+  }
+
+  return { resolvePageComponent }
+}