tour-guide-coach 1.0.0

package/src/TourOverlay.vue

@@ -0,0 +1,239 @@
+<!--
+  漫游式引导 · 全局蒙版组件（零 UI 库依赖）
+  -----------------------------------------------------------------
+  样式沿用 Element Plus 设计语言（色彩、圆角、字号），但不依赖任何组件库。
+  原生 <button> + 内联 SVG + CSS 变量（--tg-* 前缀，自动 fallback --el-*）。
+-->
+<template>
+  <Teleport to="body">
+    <div v-if="store.active" class="tour-root">
+      <!-- 4 块遮罩矩形 -->
+      <div class="tour-mask" :style="maskTop" @click="onBlockedClick" />
+      <div class="tour-mask" :style="maskBottom" @click="onBlockedClick" />
+      <div class="tour-mask" :style="maskLeft" @click="onBlockedClick" />
+      <div class="tour-mask" :style="maskRight" @click="onBlockedClick" />
+      <!-- 高亮边框 -->
+      <div v-if="rect" class="tour-highlight" :style="highlightStyle" />
+      <!-- 提示气泡 -->
+      <div v-if="step && !store.waitingTarget" class="tour-popover" :style="popoverStyle">
+        <div class="tp-head">
+          <span class="tp-step-no" :style="{ background: accentColor }">{{ store.stepIndex + 1 }}</span>
+          <span v-if="step.gate" class="tp-required">*</span>
+          <span class="tp-title">{{ step.title }}</span>
+          <span class="tp-of">第 {{ store.stepIndex + 1 }} / {{ store.totalSteps }} 步</span>
+        </div>
+        <p class="tp-content">{{ step.content }}</p>
+        <div v-if="step.tip" class="tp-tip">💡 {{ step.tip }}</div>
+        <div v-if="step.warn" class="tp-warn">⚠️ {{ step.warn }}</div>
+        <div class="tp-foot">
+          <button class="tg-btn tg-btn--link tg-btn--sm" @click="abort()">退出引导</button>
+          <!-- trigger=click：只显示提示文字 -->
+          <span v-if="step.trigger === 'click'" class="tp-click-hint">
+            👆 请点击高亮区域
+          </span>
+          <!-- 其他步骤：跳过/下一步 -->
+          <span v-else-if="store.gatePass" class="tp-btns">
+            <button v-if="canSkip" class="tg-btn tg-btn--sm" @click="skip()">跳过此步</button>
+            <button class="tg-btn tg-btn--primary tg-btn--sm" :style="{ background: accentColor, borderColor: accentColor }" @click="next()">
+              {{ isLast ? '完成' : '下一步' }}
+            </button>
+          </span>
+          <span v-else class="tp-gate">
+            <svg class="tp-gate-icon" viewBox="0 0 1024 1024" width="14" height="14" fill="currentColor"><path d="M512 160a96 96 0 0 1 96 96v64H416v-64a96 96 0 0 1 96-96zm0-64a160 160 0 0 0-160 160v64h-32a64 64 0 0 0-64 64v384a64 64 0 0 0 64 64h384a64 64 0 0 0 64-64V384a64 64 0 0 0-64-64h-32v-64A160 160 0 0 0 512 96zM320 448h384v320H320V448z"/></svg>
+            {{ step.gateHint || '请先完成本步操作' }}
+          </span>
+        </div>
+      </div>
+      <!-- 等待目标 -->
+      <div v-if="store.waitingTarget" class="tour-waiting">
+        <svg v-if="!store.waitTimedOut" class="tg-spin" viewBox="0 0 1024 1024" width="28" height="28" fill="currentColor"><path d="M512 64a448 448 0 1 1 0 896 448 448 0 0 1 0-896zm0 64a384 384 0 1 0 0 768 384 384 0 0 0 0-768z" opacity=".25"/><path d="M512 64a448 448 0 0 1 448 448h-64A384 384 0 0 0 512 128V64z"/></svg>
+        <svg v-else viewBox="0 0 1024 1024" width="28" height="28" fill="#e6a23c"><path d="M512 64L64 896h896L512 64zm0 192l288 576H224l288-576zm-32 224v128h64V480h-64zm0 160v64h64v-64h-64z"/></svg>
+        <p>{{ store.waitTimedOut ? '未找到目标元素，可能是页面状态不符' : (step?.content ?? '等待页面加载...') }}</p>
+        <button v-if="store.waitTimedOut" class="tg-btn tg-btn--warning tg-btn--sm" @click="next()">跳过此步</button>
+        <button class="tg-btn tg-btn--sm" @click="abort()">退出引导</button>
+      </div>
+    </div>
+  </Teleport>
+</template>
+
+<script setup lang="ts">
+import { computed, watch, onBeforeUnmount } from 'vue'
+import { tourState, abort, next, skip, currentStep } from './store'
+import type { CSSProperties } from 'vue'
+
+const store = tourState
+
+/** ESC 退出引导 */
+function onKeydown(e: KeyboardEvent): void {
+  if (e.key === 'Escape' && store.active) abort()
+}
+watch(() => store.active, (isActive) => {
+  if (isActive) window.addEventListener('keydown', onKeydown)
+  else window.removeEventListener('keydown', onKeydown)
+})
+onBeforeUnmount(() => window.removeEventListener('keydown', onKeydown))
+
+const step = computed(() => currentStep())
+const rect = computed(() => store.highlightRect)
+const accentColor = computed(() => step.value?.accent ?? store.config?.accent ?? '#409eff')
+const isLast = computed(() => store.stepIndex >= store.totalSteps - 1)
+const canSkip = computed(() => {
+  const s = step.value
+  if (!s) return false
+  return !s.gate && s.trigger === 'manual'
+})
+
+// ---------- 蒙版 4 块定位 ----------
+function calcMasks() {
+  const r = rect.value
+  if (!r) return null
+  return {
+    top: { left: 0, top: 0, width: '100vw', height: `${Math.max(r.top, 0)}px` },
+    bottom: { left: 0, top: `${r.top + r.height}px`, width: '100vw', height: `calc(100vh - ${r.top + r.height}px)` },
+    left: { left: 0, top: `${r.top}px`, width: `${Math.max(r.left, 0)}px`, height: `${r.height}px` },
+    right: { left: `${r.left + r.width}px`, top: `${r.top}px`, width: `calc(100vw - ${r.left + r.width}px)`, height: `${r.height}px` }
+  }
+}
+const masks = computed(calcMasks)
+const maskTop = computed<CSSProperties>(() => masks.value?.top ?? { display: 'none' })
+const maskBottom = computed<CSSProperties>(() => masks.value?.bottom ?? { display: 'none' })
+const maskLeft = computed<CSSProperties>(() => masks.value?.left ?? { display: 'none' })
+const maskRight = computed<CSSProperties>(() => masks.value?.right ?? { display: 'none' })
+
+// ---------- 高亮框 ----------
+const highlightStyle = computed<CSSProperties>(() => {
+  const r = rect.value
+  if (!r) return { display: 'none' }
+  return {
+    position: 'fixed', top: `${r.top}px`, left: `${r.left}px`,
+    width: `${r.width}px`, height: `${r.height}px`,
+    borderRadius: '8px', border: `2px solid ${accentColor.value}`,
+    boxShadow: `0 0 0 3px ${accentColor.value}33, 0 0 20px ${accentColor.value}44`,
+    pointerEvents: 'none', transition: 'all 0.35s cubic-bezier(0.4,0,0.2,1)'
+  }
+})
+
+// ---------- Popover 定位 ----------
+const popoverStyle = computed<CSSProperties>(() => {
+  const r = rect.value
+  if (!r) return { position: 'fixed', top: '50%', left: '50%', transform: 'translate(-50%,-50%)' }
+  const placement = step.value?.placement ?? 'bottom'
+  const gap = 14
+  const base: CSSProperties = { position: 'fixed', zIndex: 100002 }
+  switch (placement) {
+    case 'top': return { ...base, left: `${r.left}px`, bottom: `calc(100vh - ${r.top - gap}px)`, maxWidth: '420px' }
+    case 'bottom': return { ...base, left: `${r.left}px`, top: `${r.top + r.height + gap}px`, maxWidth: '420px' }
+    case 'left': return { ...base, right: `calc(100vw - ${r.left - gap}px)`, top: `${r.top}px`, maxWidth: '360px' }
+    case 'right': return { ...base, left: `${r.left + r.width + gap}px`, top: `${r.top}px`, maxWidth: '360px' }
+    default: return { ...base, top: '50%', left: '50%', transform: 'translate(-50%,-50%)', maxWidth: '480px' }
+  }
+})
+
+function onBlockedClick(): void { /* 静默拦截 */ }
+</script>
+
+<style scoped>
+/* ---------- CSS 变量：自动 fallback 到 --el-*（兼容 EP 项目） ---------- */
+.tour-root {
+  --tg-primary: var(--el-color-primary, #409eff);
+  --tg-success: var(--el-color-success, #67c23a);
+  --tg-warning: var(--el-color-warning, #e6a23c);
+  --tg-danger: var(--el-color-danger, #f56c6c);
+  --tg-text-1: var(--el-text-color-primary, #303133);
+  --tg-text-2: var(--el-text-color-regular, #606266);
+  --tg-text-3: var(--el-text-color-secondary, #909399);
+  --tg-border: var(--el-border-color-lighter, #ebeef5);
+  --tg-fill-light: var(--el-fill-color-light, #f5f7fa);
+  --tg-radius: var(--el-border-radius-base, 4px);
+
+  position: fixed; inset: 0; z-index: 100000;
+  pointer-events: none;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', sans-serif;
+}
+
+/* ---------- 遮罩 ---------- */
+.tour-mask {
+  position: fixed; background: rgba(0,0,0,0.55);
+  transition: all 0.35s cubic-bezier(0.4,0,0.2,1);
+  cursor: not-allowed; pointer-events: auto;
+}
+
+/* ---------- 高亮框 ---------- */
+.tour-highlight { z-index: 100001; }
+
+/* ---------- 按钮（EP 风格） ---------- */
+.tg-btn {
+  display: inline-flex; align-items: center; justify-content: center;
+  border: 1px solid var(--tg-border); border-radius: var(--tg-radius);
+  background: #fff; color: var(--tg-text-2);
+  font-size: 14px; font-weight: 500; line-height: 1;
+  padding: 8px 15px; cursor: pointer;
+  transition: color .2s, border-color .2s, background .2s;
+  outline: none; white-space: nowrap; user-select: none;
+}
+.tg-btn:hover { color: var(--tg-primary); border-color: var(--tg-primary); background: #ecf5ff; }
+.tg-btn--sm { padding: 5px 11px; font-size: 12px; }
+.tg-btn--primary {
+  background: var(--tg-primary); border-color: var(--tg-primary); color: #fff;
+}
+.tg-btn--primary:hover { opacity: .85; background: var(--tg-primary); color: #fff; }
+.tg-btn--warning {
+  background: var(--tg-warning); border-color: var(--tg-warning); color: #fff;
+}
+.tg-btn--warning:hover { opacity: .85; background: var(--tg-warning); color: #fff; }
+.tg-btn--link {
+  border: none; background: none; padding: 4px 6px;
+  color: var(--tg-text-3);
+}
+.tg-btn--link:hover { color: var(--tg-primary); background: none; }
+
+/* ---------- 气泡 ---------- */
+.tour-popover {
+  z-index: 100002; background: #fff; border-radius: 12px;
+  padding: 20px 24px; box-shadow: 0 8px 40px rgba(0,0,0,0.12), 0 2px 8px rgba(0,0,0,0.06);
+  animation: tp-in 0.3s ease; pointer-events: auto;
+  min-width: 280px; max-width: 420px;
+}
+@keyframes tp-in {
+  from { opacity: 0; transform: translateY(6px) scale(0.97); }
+  to { opacity: 1; transform: translateY(0) scale(1); }
+}
+.tp-head { display: flex; align-items: center; gap: 10px; margin-bottom: 12px; }
+.tp-step-no {
+  display: inline-flex; align-items: center; justify-content: center;
+  width: 28px; height: 28px; border-radius: 50%;
+  color: #fff; font-size: 14px; font-weight: 700; flex-shrink: 0;
+}
+.tp-required { color: var(--tg-danger); font-size: 20px; font-weight: 700; line-height: 1; }
+.tp-title { font-size: 16px; font-weight: 700; color: var(--tg-text-1); }
+.tp-of { font-size: 13px; color: var(--tg-text-3); margin-left: auto; font-variant-numeric: tabular-nums; }
+.tp-content { margin: 0 0 14px; font-size: 14px; line-height: 1.8; color: var(--tg-text-2); white-space: pre-line; }
+.tp-tip {
+  font-size: 13px; color: #529b2e; background: #f0f9eb;
+  padding: 8px 12px; border-radius: 6px; margin-bottom: 10px;
+  border-left: 3px solid #67c23a;
+}
+.tp-warn {
+  font-size: 13px; color: #b88230; background: #fdf6ec;
+  padding: 8px 12px; border-radius: 6px; margin-bottom: 10px;
+  border-left: 3px solid #e6a23c;
+}
+.tp-foot { display: flex; align-items: center; justify-content: space-between; padding-top: 14px; border-top: 1px solid var(--tg-border); }
+.tp-btns { display: flex; gap: 10px; }
+.tp-gate { display: inline-flex; align-items: center; gap: 5px; font-size: 13px; color: var(--tg-warning); font-weight: 500; }
+.tp-gate-icon { flex-shrink: 0; }
+.tp-click-hint { font-size: 14px; color: var(--tg-primary); font-weight: 500; animation: pulse-hint 1.5s ease-in-out infinite; }
+@keyframes pulse-hint { 0%,100%{opacity:1} 50%{opacity:.5} }
+
+/* ---------- 等待态 ---------- */
+.tour-waiting {
+  position: fixed; top: 50%; left: 50%; transform: translate(-50%,-50%);
+  z-index: 100002; background: #fff; padding: 32px 40px;
+  border-radius: 12px; box-shadow: 0 8px 32px rgba(0,0,0,0.15);
+  text-align: center; pointer-events: auto;
+  display: flex; flex-direction: column; align-items: center; gap: 8px;
+}
+.tour-waiting p { margin: 4px 0 8px; font-size: 14px; color: var(--tg-text-2); }
+.tg-spin { animation: tg-rotate 1s linear infinite; }
+@keyframes tg-rotate { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
+</style>

package/src/configs/demo-form.ts

@@ -0,0 +1,82 @@
+/**
+ * 示例引导配置 · 表单创建流程
+ * -----------------------------------------------------------------
+ * 演示 trigger 类型、gate 门控、expandSelector 动态高亮的完整用法。
+ * 对应 demo 页面的表单弹窗。
+ */
+import type { TourConfig } from '../types'
+
+export const demoFormTour: TourConfig = {
+  key: 'demo-form',
+  name: '新建表单引导',
+  accent: '#409eff',
+  steps: [
+    {
+      id: 'open-btn',
+      target: '#demo-create-btn',
+      placement: 'bottom',
+      title: '点击「新建」',
+      content: '点击这个按钮打开表单弹窗。',
+      trigger: 'click',
+      afterClickWait: '.el-dialog__body .el-form-item:nth-child(1)',
+      clickDelay: 500
+    },
+    {
+      id: 'name-field',
+      target: '.el-dialog__body .el-form-item:nth-child(1) .el-input',
+      placement: 'right',
+      title: '填写名称',
+      content: '输入名称（必填）。',
+      trigger: 'input',
+      gate: (resolve) => {
+        const el = resolve('.el-dialog__body .el-form-item:nth-child(1) input')
+        return !!(el as HTMLInputElement | null)?.value?.trim()
+      },
+      gateHint: '请先输入名称',
+      tip: '名称是唯一必填字段。'
+    },
+    {
+      id: 'category-select',
+      target: '.el-dialog__body .el-form-item:nth-child(2) .el-select',
+      expandSelector: '.el-select-dropdown',
+      placement: 'right',
+      title: '选择分类',
+      content: '从下拉中选择分类（必填）。\n注意下拉面板也被高亮区域包含。',
+      trigger: 'change',
+      gate: (resolve) => {
+        const el = resolve('.el-dialog__body .el-form-item:nth-child(2) .el-select')
+        if (!el) return false
+        const ph = el.querySelector('.el-select__placeholder')
+        if (!ph) return true
+        return !ph.classList.contains('is-transparent')
+      },
+      gateHint: '请选择一个分类'
+    },
+    {
+      id: 'date-field',
+      target: '.el-dialog__body .el-form-item:nth-child(3) .el-input',
+      expandSelector: '.el-picker-panel',
+      placement: 'right',
+      title: '选择日期',
+      content: '选择日期（选填）。\n日历面板同样使用动态高亮扩展。',
+      trigger: 'manual'
+    },
+    {
+      id: 'remark-field',
+      target: '.el-dialog__body .el-form-item:nth-child(4) .el-textarea',
+      placement: 'right',
+      title: '备注',
+      content: '填写备注（选填），可以直接点「下一步」跳过。',
+      trigger: 'manual'
+    },
+    {
+      id: 'submit-btn',
+      target: '.el-dialog__footer .el-button--primary',
+      placement: 'top',
+      title: '提交表单',
+      content: '点击「确定」提交，引导结束。',
+      trigger: 'click',
+      clickDelay: 500
+    }
+  ]
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * vue-tour-guide · 公共入口
+ * -----------------------------------------------------------------
+ * 零外部依赖（仅需 Vue 3），全局单例模式。
+ *
+ * 使用方式：
+ *   import { tourState, startTour, abort, TourOverlay } from 'vue-tour-guide'
+ *   // 在 layout 中挂 <TourOverlay />
+ *   // 业务页调用 startTour(config)
+ */
+export { tourState, startTour, abort, next, skip, complete } from './store'
+export type { TargetResolver } from './store'
+export { default as TourOverlay } from './TourOverlay.vue'
+export type { TourConfig, TourStep, StepTrigger, PopPlacement, HighlightRect } from './types'

package/src/store.ts

@@ -0,0 +1,270 @@
+/**
+ * 漫游式引导引擎 · 状态机（模块级单例，零外部依赖）
+ * -----------------------------------------------------------------
+ * 用 Vue 3 的 reactive + ref 替代 Pinia。
+ * 全局单例——同一时间只允许一个 tour 播放。
+ *
+ * 生命周期：
+ *   startTour(config, resolver) → 逐步 enterStep → resolveTarget
+ *   → 绑定 trigger 监听 → 用户操作满足条件 → next() → complete/abort
+ */
+import { ref, shallowReactive } from 'vue'
+import type { TourConfig, TourStep, HighlightRect } from './types'
+
+/** 元素解析器：宿主页面提供，把 target 名解析为 DOM 元素 */
+export type TargetResolver = (target: string) => HTMLElement | null
+
+const GATE_POLL_INTERVAL = 150
+const ELEMENT_WAIT_TIMEOUT = 12000
+
+// ---------- 响应式状态（模块级单例） ----------
+export const tourState = shallowReactive({
+  active: false,
+  config: null as TourConfig | null,
+  stepIndex: 0,
+  totalSteps: 0,
+  highlightRect: null as HighlightRect | null,
+  targetEl: null as HTMLElement | null,
+  gatePass: true,
+  waitingTarget: false,
+  waitTimedOut: false
+})
+
+// ---------- 内部状态（非响应式） ----------
+let onComplete: (() => void) | null = null
+let _resolver: TargetResolver | null = null
+let _gateTimer: ReturnType<typeof setInterval> | null = null
+let _waitObserver: MutationObserver | null = null
+let _waitTimer: ReturnType<typeof setTimeout> | null = null
+let _clickDelayTimer: ReturnType<typeof setTimeout> | null = null
+let _resizeObs: ResizeObserver | null = null
+let _scrollHandler: (() => void) | null = null
+let _expandObs: MutationObserver | null = null
+let _currentStep: TourStep | null = null
+
+function _currentStepFn(): TourStep | null {
+  return tourState.config?.steps[tourState.stepIndex] ?? null
+}
+
+/** 获取当前步骤（供组件使用） */
+export function currentStep(): TourStep | null {
+  return _currentStepFn()
+}
+
+// ---------- 启动引导 ----------
+export function startTour(tour: TourConfig, resolver?: TargetResolver, done?: () => void): void {
+  if (tourState.active) abort()
+  tourState.config = tour
+  tourState.stepIndex = 0
+  tourState.totalSteps = tour.steps.length
+  tourState.gatePass = true
+  onComplete = done ?? null
+  _resolver = resolver ?? null
+  tourState.active = true
+  _enterStep()
+}
+
+export function abort(): void {
+  _cleanup()
+  tourState.active = false
+  tourState.config = null
+  tourState.highlightRect = null
+  tourState.targetEl = null
+  _resolver = null
+  onComplete = null
+}
+
+export function complete(): void {
+  _cleanup()
+  tourState.active = false
+  tourState.highlightRect = null
+  tourState.targetEl = null
+  const cb = onComplete
+  _resolver = null
+  onComplete = null
+  cb?.()
+}
+
+// ---------- 步骤推进 ----------
+export function next(): void {
+  _cleanup()
+  const cfg = tourState.config
+  if (!cfg) return
+  if (tourState.stepIndex >= cfg.steps.length - 1) { complete(); return }
+  tourState.stepIndex += 1
+  _enterStep()
+}
+
+export function skip(): void { next() }
+
+// ---------- 进入当前步 ----------
+function _enterStep(): void {
+  const step = _currentStepFn()
+  if (!step) { complete(); return }
+  _currentStep = step
+  tourState.gatePass = step.gate ? false : true
+  tourState.waitingTarget = true
+  tourState.waitTimedOut = false
+  tourState.highlightRect = null
+  tourState.targetEl = null
+
+  const enterResult = step.beforeEnter?.()
+  if (enterResult instanceof Promise) {
+    enterResult.then(() => _resolveTarget(step))
+  } else {
+    requestAnimationFrame(() => _resolveTarget(step))
+  }
+}
+
+// ---------- 解析目标元素 ----------
+function _resolveTarget(step: TourStep): void {
+  if (step.trigger === 'auto') {
+    tourState.waitingTarget = false
+    _autoAdvance(step)
+    return
+  }
+  if (step.trigger === 'wait-dom') {
+    _waitForDom(step)
+    return
+  }
+  const el = _findTarget(step.target)
+  if (el) { _onTargetReady(el, step); return }
+  _startWaitForElement(step.target, () => {
+    const el2 = _findTarget(step.target)
+    _onTargetReady(el2, step)
+  })
+}
+
+function _findTarget(target: string): HTMLElement | null {
+  if (_resolver) {
+    const el = _resolver(target)
+    if (el) return el
+  }
+  try { return document.querySelector(target) } catch { return null }
+}
+
+function _onTargetReady(el: HTMLElement | null, step: TourStep): void {
+  if (!el) { tourState.waitTimedOut = true; return }
+  tourState.waitingTarget = false
+  tourState.waitTimedOut = false
+  tourState.targetEl = el
+  _updateRect(el)
+  _bindTrigger(el, step)
+  _startGate(step)
+  _startTrackingRect(el)
+}
+
+// ---------- 高亮矩形跟踪 ----------
+function _updateRect(el: HTMLElement): void {
+  const r = el.getBoundingClientRect()
+  const pad = 6
+  let rect: HighlightRect = {
+    top: r.top - pad, left: r.left - pad,
+    width: r.width + pad * 2, height: r.height + pad * 2
+  }
+  const expandSel = _currentStep?.expandSelector
+  if (expandSel) {
+    const candidates = document.querySelectorAll(expandSel)
+    let expandEl: HTMLElement | null = null
+    for (const c of candidates) {
+      if ((c as HTMLElement).offsetHeight > 0) { expandEl = c as HTMLElement; break }
+    }
+    if (expandEl) {
+      const er = expandEl.getBoundingClientRect()
+      const top = Math.min(rect.top, er.top - pad)
+      const left = Math.min(rect.left, er.left - pad)
+      const right = Math.max(rect.left + rect.width, er.right + pad)
+      const bottom = Math.max(rect.top + rect.height, er.bottom + pad)
+      rect = { top, left, width: right - left, height: bottom - top }
+    }
+  }
+  tourState.highlightRect = rect
+}
+
+function _startTrackingRect(el: HTMLElement): void {
+  _stopTrackingRect()
+  _scrollHandler = () => _updateRect(el)
+  window.addEventListener('scroll', _scrollHandler, true)
+  window.addEventListener('resize', _scrollHandler)
+  _resizeObs = new ResizeObserver(() => _updateRect(el))
+  _resizeObs.observe(el)
+  const expandSel = _currentStep?.expandSelector
+  if (expandSel) {
+    _expandObs = new MutationObserver(() => _updateRect(el))
+    _expandObs.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] })
+  }
+}
+
+function _stopTrackingRect(): void {
+  if (_scrollHandler) {
+    window.removeEventListener('scroll', _scrollHandler, true)
+    window.removeEventListener('resize', _scrollHandler)
+  }
+  _scrollHandler = null
+  _resizeObs?.disconnect(); _resizeObs = null
+  _expandObs?.disconnect(); _expandObs = null
+}
+
+// ---------- 事件绑定 ----------
+function _bindTrigger(el: HTMLElement, step: TourStep): void {
+  if (step.trigger === 'click') {
+    const handler = () => {
+      el.removeEventListener('click', handler)
+      const delay = step.clickDelay ?? 350
+      if (step.afterClickWait) {
+        _waitForDom({ waitForElement: step.afterClickWait, clickDelay: delay } as TourStep)
+      } else {
+        _clickDelayTimer = setTimeout(() => next(), delay)
+      }
+    }
+    el.addEventListener('click', handler)
+  }
+}
+
+// ---------- Gate 轮询 ----------
+function _startGate(step: TourStep): void {
+  if (!step.gate) { tourState.gatePass = true; return }
+  const resolve = (t: string) => _findTarget(t)
+  tourState.gatePass = step.gate(resolve)
+  if (tourState.gatePass) return
+  _gateTimer = setInterval(() => {
+    if (step.gate!(resolve)) {
+      tourState.gatePass = true
+      if (_gateTimer) { clearInterval(_gateTimer); _gateTimer = null }
+    }
+  }, GATE_POLL_INTERVAL)
+}
+
+// ---------- 等待 DOM ----------
+function _waitForDom(step: TourStep): void {
+  const sel = step.waitForElement
+  if (!sel) { next(); return }
+  if (_findTarget(sel)) {
+    _clickDelayTimer = setTimeout(() => next(), step.clickDelay ?? 300)
+    return
+  }
+  _startWaitForElement(sel, () => {
+    _clickDelayTimer = setTimeout(() => next(), step.clickDelay ?? 300)
+  })
+}
+
+function _startWaitForElement(target: string, cb: () => void): void {
+  let resolved = false
+  const finish = () => { if (!resolved) { resolved = true; _waitObserver?.disconnect(); _waitObserver = null; cb() } }
+  _waitObserver = new MutationObserver(() => { if (_findTarget(target)) finish() })
+  _waitObserver.observe(document.body, { childList: true, subtree: true })
+  _waitTimer = setTimeout(finish, ELEMENT_WAIT_TIMEOUT)
+}
+
+function _autoAdvance(step: TourStep): void {
+  _clickDelayTimer = setTimeout(() => next(), step.autoDelay ?? 600)
+}
+
+// ---------- 清理 ----------
+function _cleanup(): void {
+  _stopTrackingRect()
+  if (_gateTimer) { clearInterval(_gateTimer); _gateTimer = null }
+  if (_waitObserver) { _waitObserver.disconnect(); _waitObserver = null }
+  if (_waitTimer) { clearTimeout(_waitTimer); _waitTimer = null }
+  if (_clickDelayTimer) { clearTimeout(_clickDelayTimer); _clickDelayTimer = null }
+}

package/src/types.ts

@@ -0,0 +1,79 @@
+/**
+ * 漫游式引导引擎 · 类型定义
+ * -----------------------------------------------------------------
+ * 交互式引导：蒙版 + 元素高亮 + 事件驱动推步（用户真实操作才推进）。
+ *
+ * StepTrigger 语义：
+ *   click       — 用户点击高亮元素后自动前进
+ *   input       — 高亮的输入框值满足 condition 后前进（如非空）
+ *   change      — 高亮元素的值变化后前进（select / tree-select）
+ *   wait-dom    — 等待 waitForElement 选择器匹配到 DOM 节点（弹窗出现、路由切换）
+ *   auto        — 自动前进（延时后，用于页面跳转/加载过渡）
+ *   manual      — 显示"下一步"按钮，用户手动推进（信息展示步骤）
+ */
+
+/** 弹窗提示框相对高亮区域的弹出方位 */
+export type PopPlacement = 'top' | 'bottom' | 'left' | 'right' | 'center'
+
+/** 引导步骤 */
+export interface TourStep {
+  /** 步骤唯一 ID（config 内不重复） */
+  id: string
+  /** 高亮目标 CSS 选择器（`[data-tour="xxx"]`、`#tab-tasks` 等） */
+  target: string
+  /** 动态扩展选择器：当该选择器匹配的元素可见时，高亮区域扩展为 target + expand 联合矩形。
+   *  典型场景：el-select 展开后 popper teleport 到 body，需要把下拉面板纳入可交互区域。 */
+  expandSelector?: string
+  /** 弹窗提示框弹出方位 */
+  placement?: PopPlacement
+  /** 步骤标题 */
+  title: string
+  /** 步骤正文（支持 \n 换行） */
+  content: string
+  /** 推进触发方式 */
+  trigger: StepTrigger
+  /** 推进门控条件（trigger=input/change 时，引擎轮询检查；返回 true 才解锁"下一步"）。
+   *  参数 resolve 是宿主提供的元素解析器，gate 内可调用 resolve('nameRef:input') 取 DOM */
+  gate?: (resolve: (target: string) => HTMLElement | null) => boolean
+  /** 门控未通过时"下一步"按钮下方提示文案 */
+  gateHint?: string
+  /** trigger=wait-dom 时，等待该选择器出现在 DOM */
+  waitForElement?: string
+  /** trigger=auto 时，自动前进延时（ms），默认 600 */
+  autoDelay?: number
+  /** trigger=click 时，前进延时（ms），等 click 引起的 DOM 变化完成，默认 350 */
+  clickDelay?: number
+  /** 额外等待：click 后等该选择器出现才推下一步（如"点了新建 → 等弹窗"） */
+  afterClickWait?: string
+  /** 小贴士（可选，绿色块） */
+  tip?: string
+  /** 注意事项（可选，橙色块） */
+  warn?: string
+  /** 本步的强调色覆盖（默认用 tour 全局色） */
+  accent?: string
+  /** 是否在进入本步前执行导航（如 router.push） */
+  beforeEnter?: () => void | Promise<void>
+}
+
+/** 步骤触发方式 */
+export type StepTrigger = 'click' | 'input' | 'change' | 'wait-dom' | 'auto' | 'manual'
+
+/** 一个完整引导 */
+export interface TourConfig {
+  /** 引导唯一 key */
+  key: string
+  /** 引导名（如「新建任务引导」） */
+  name: string
+  /** 全局强调色 */
+  accent: string
+  /** 引导步骤列表（按序播放） */
+  steps: TourStep[]
+}
+
+/** 高亮矩形（viewport 坐标系，引擎每帧更新） */
+export interface HighlightRect {
+  top: number
+  left: number
+  width: number
+  height: number
+}