@done-coding/forge-plugin-guide 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,3 @@
+# @done-coding/forge-plugin-guide
+
+内部前端库，内部维护，暂无公开文档。

package/es/index.mjs

@@ -0,0 +1,436 @@
+import { shallowRef as S, readonly as B, computed as A } from "vue";
+import { BADGE_KEY_ATTR as C, BADGE_HOST_ATTR as P, BADGE_MASK_KINDS as O } from "@done-coding/admin-core";
+import { driver as M } from "driver.js";
+import "driver.js/dist/driver.css";
+const N = (e) => {
+  if (!e) return [];
+  try {
+    const r = JSON.parse(e);
+    return Array.isArray(r) ? r.filter((o) => typeof o == "string") : [];
+  } catch {
+    return [];
+  }
+}, L = (e, r) => {
+  const o = S(
+    N(e.getItem(r))
+  ), s = (n) => {
+    o.value = n, e.setItem(r, JSON.stringify(n));
+  }, c = (n) => o.value.includes(n), t = (n) => {
+    c(n) || s([...o.value, n]);
+  }, i = () => {
+    s([]);
+  };
+  return {
+    seen: B(o),
+    isSeen: c,
+    markSeen: t,
+    reset: i
+  };
+}, U = (e) => e.replace(/(["\\])/g, "\\$1"), F = (e) => `[${C}="${U(e)}"]`, j = (e) => {
+  if (typeof document > "u") return;
+  const r = document.querySelector(
+    F(e)
+  );
+  if (!r) return;
+  const o = r.closest(`[${P}]`) ?? r;
+  return Y(o) ? o : void 0;
+}, Y = (e) => e.getClientRects().length > 0, z = "[dc-plugin-guide]", H = O, V = (e, r) => r.startsWith("/") ? r : e ? `${e.replace(/\/$/, "")}/${r}` : `/${r}`, W = (e) => {
+  const r = /* @__PURE__ */ new Map();
+  let o = 0;
+  const s = (c, t) => {
+    c.forEach((i) => {
+      var v;
+      const n = V(t, i.path), l = o++;
+      r.has(n) || r.set(n, l), typeof i.name == "string" && !r.has(i.name) && r.set(i.name, l), (v = i.children) != null && v.length && s(i.children, n);
+    });
+  };
+  return s(e ?? [], ""), r;
+}, J = (e, r) => !!e.expireAt && e.expireAt <= r, y = (e, r, o) => {
+  if (e) {
+    if (e.has(r)) return;
+    e.add(r);
+  }
+  console.warn(`${z} ${o}`);
+}, R = (e, r, o) => {
+  const s = e.key ?? e.badgeKey;
+  if (!s) {
+    y(
+      r.warned,
+      "__nokey__",
+      "步骤既无 key 也无 badgeKey，无从记进度，已丢弃"
+    );
+    return;
+  }
+  const c = e.badgeKey ? r.marks[e.badgeKey] : void 0;
+  if (e.badgeKey && (!c || J(c, o))) return;
+  if (c && H.includes(c.kind)) {
+    y(
+      r.warned,
+      `mask:${s}`,
+      `「${s}」的标是 ${c.kind}，它会遮挡宿主交互（用户点不动），与引导正面冲突，已跳过。[MUST NOT] 把会遮挡的档（${O.join(
+        " / "
+      )}）配进 badgeKinds。`
+    );
+    return;
+  }
+  const t = e.description ?? (c == null ? void 0 : c.description);
+  if (!t) {
+    y(
+      r.warned,
+      `nodesc:${s}`,
+      `「${s}」没有讲解正文（step.description 与 BadgeEntry.description 都为空），已跳过。[MUST NOT] 拿菜单 title 硬凑——没内容的引导步骤是噪音。`
+    );
+    return;
+  }
+  if (e.route && !r.hasRouter) {
+    y(
+      r.warned,
+      `norouter:${s}`,
+      `「${s}」配了 route 但 createGuidePlugin 没拿到 router，无法导航，已跳过。`
+    );
+    return;
+  }
+  const i = e.badgeKey, n = c == null ? void 0 : c.version, l = n === void 0 || n === "" ? s : `${s}@${n}`;
+  return {
+    ...e,
+    key: l,
+    sourceKey: s,
+    description: t,
+    /**
+     * 锚点：显式 `element` 优先，否则由 `badgeKey` 解析。
+     *
+     * 取**函数**而非选择器字符串：解析链最后一跳要 `closest` 到**宿主**
+     * （菜单项 / 按钮），而属性选择器只能选中角标那个十几 px 的 pill ——
+     * 高亮一个小圆点说「看这里」不是想要的。driver.js 的 `element` 支持
+     * `() => Element`，且 `waitForElement` 会反复重算它 ⇒ 跨路由 / 懒挂载也吃得下。
+     */
+    element: e.element ?? (i ? () => j(i) : void 0)
+  };
+}, T = (e) => {
+  var c;
+  const r = e.now ?? Date.now();
+  if ((c = e.steps) != null && c.length)
+    return e.steps.map((t) => R(t, e, r)).filter((t) => !!t);
+  const o = W(e.routes);
+  return Object.keys(e.marks).filter((t) => e.badgeKinds.includes(e.marks[t].kind)).sort((t, i) => {
+    const n = o.get(t), l = o.get(i);
+    return n !== void 0 && l !== void 0 ? n - l : n !== void 0 ? -1 : l !== void 0 ? 1 : t < i ? -1 : t > i ? 1 : 0;
+  }).map((t) => R({ badgeKey: t }, e, r)).filter((t) => !!t);
+}, q = `dc-guide-theme-${Math.random().toString(36).slice(2, 8)}`, X = "data-dc-guide-theme", h = "var(--dc-core-surface, var(--el-bg-color-overlay))", m = "var(--dc-core-primary-color, var(--el-color-primary))", Z = `
+.driver-popover {
+  color: var(--dc-core-base-color, var(--el-text-color-primary));
+  background-color: ${h};
+  border: 1px solid var(--dc-core-border-color, var(--el-border-color));
+  border-radius: var(--dc-core-radius, var(--el-border-radius-base));
+  box-shadow: var(--dc-core-shadow, var(--el-box-shadow));
+}
+.driver-popover-title { color: var(--dc-core-base-color, var(--el-text-color-primary)); }
+.driver-popover-description { color: var(--el-text-color-regular); }
+.driver-popover-progress-text { color: var(--el-text-color-secondary); }
+.driver-popover-close-btn { color: var(--el-text-color-placeholder); }
+.driver-popover-close-btn:hover,
+.driver-popover-close-btn:focus { color: var(--el-text-color-primary); }
+
+/*
+ * 两个按钮对齐 element-plus 的 Button（甲方 2026-09-16）——driver.js 原样式是
+ * all:unset + padding:3px 7px + font-size:12px + border-radius:3px，
+ * 一副"原生按钮"的相，混在本仓界面里很突兀。
+ *
+ * 注意：EP 的 --el-button-* 变量定义在 .el-button 选择器内部（局部作用域），这里够不着，
+ * 必须引它们的源变量（--el-fill-color-blank / --el-border-color / --el-text-color-regular …），
+ * 写 var(--el-button-bg-color) 会取不到值。
+ * 尺寸取 EP default 档实测值：32px 高 / 8px 15px 内距 / 14px 字号。
+ *
+ * ⚠️ 本块在**模板字符串内**，注释里不能出现反引号——会当场终止字符串（已踩）。
+ */
+.driver-popover-footer-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  height: 32px;
+  padding: 8px 15px;
+  font-size: var(--el-font-size-base, 14px);
+  font-weight: var(--el-font-weight-primary, 500);
+  line-height: 1;
+  color: var(--el-text-color-regular);
+  background-color: var(--el-fill-color-blank);
+  border: 1px solid var(--dc-core-border-color, var(--el-border-color));
+  border-radius: var(--dc-core-radius, var(--el-border-radius-base));
+}
+
+/* hover 对齐 EP default 档：用户主动悬停才染主色 */
+.driver-popover-footer-btn:hover {
+  color: ${m};
+  background-color: var(--el-color-primary-light-9);
+  border-color: var(--el-color-primary-light-7);
+}
+
+/*
+ * focus 保持中性（不跟着 EP 把 :focus 与 :hover 同规则处理）：
+ * driver.js 会自动 focus 弹窗里的第一个按钮 —— 那不是用户意图，
+ * 「跳过」会因此常驻高亮 = 在引导用户跳过（甲方两度指出）。
+ * 用 :not(:hover) 让真悬停仍走上面那条。
+ */
+.driver-popover-footer-btn:focus:not(:hover) {
+  color: var(--el-text-color-regular);
+  background-color: var(--el-fill-color-blank);
+  border-color: var(--dc-core-border-color, var(--el-border-color));
+}
+
+/* 主按钮（下一步 / 知道了）——对齐 EP primary 档实心，随主题切换 */
+.driver-popover-next-btn,
+.driver-popover-next-btn:focus:not(:hover) {
+  color: var(--el-color-white, #fff);
+  background-color: ${m};
+  border-color: ${m};
+}
+.driver-popover-next-btn:hover {
+  color: var(--el-color-white, #fff);
+  background-color: var(--el-color-primary-light-3);
+  border-color: var(--el-color-primary-light-3);
+}
+
+/*
+ * 镂空区描边（甲方 2026-09-16）。
+ *
+ * 为什么必须加：driver.js 的遮罩是 #000 + opacity .7。亮色下「遮住 = 白 + 黑半透明 = 灰」，
+ * 与镂空处形成强对比；而暗色下页面本就是 #141414 / #0a0a0a，
+ * 「深色 + 黑半透明 ≈ 还是深色」，镂空与不镂空几乎看不出差别。
+ *
+ * 🔴 描在**遮罩的 path 上**，[MUST NOT] 改用目标元素的 outline / box-shadow ——
+ * 那两者都画在元素**外部空间**，会被祖先的 overflow 裁掉：
+ * 实测菜单项左缘与 .app-sidebar-shim（overflow-x: hidden）的余量是 0px，
+ * outline-offset:3 + width:2 整个被吃掉 ⇒ 只剩上下两条边（甲方截图）；
+ * 弹窗里的表单四周都在滚动容器内，则四条边全没。
+ * 遮罩 SVG 是 fixed 全屏、不受任何祖先裁剪，且它的 path 已经算好了
+ * stagePadding / stageRadius，描边天然与洞严丝合缝。
+ *
+ * 外框那一圈：path 的 d 是「视口矩形 + 洞」两段
+ * （M1280,0L0,0L0,800L1280,800L1280,0Z 之后才是 M3,432 h309 a5,5…），
+ * stroke 会一并描到视口矩形 —— 但它正好落在视口四边上，stroke 居中对齐后
+ * 有一半在视口外、另一半被窗口裁掉，实测不可见，故无需为它做任何规避。
+ */
+svg.driver-overlay path {
+  stroke: ${m};
+  stroke-width: 2;
+}
+
+/* 箭头：用 border 画的三角，四个方向各自只有一条边可见，逐条跟面色 */
+.driver-popover-arrow-side-left { border-left-color: ${h}; }
+.driver-popover-arrow-side-right { border-right-color: ${h}; }
+.driver-popover-arrow-side-top { border-top-color: ${h}; }
+.driver-popover-arrow-side-bottom { border-bottom-color: ${h}; }
+`;
+let K = !1;
+const Q = () => {
+  if (K || typeof document > "u") return;
+  K = !0;
+  const e = document.createElement("style");
+  e.id = q, e.setAttribute(X, ""), e.textContent = Z, document.head.appendChild(e);
+}, ee = {
+  showProgress: !0,
+  progressText: "{{current}} / {{total}}",
+  /**
+   * 两个按钮：「跳过」+「下一步 / 知道了」（甲方 2026-09-16）。
+   *
+   * 🔴 driver.js 的 `"close"` 按钮是**右上角那个 ×**（无文案配置项），做不出带文字的
+   * 「跳过」⇒ 复用 `previous` 位并把它的行为改写成销毁（见下方 `onPrevClick`）。
+   * 同时不放 `"close"`：既然有了显式的「跳过」，右上角 × 就是语义重复的第二出口。
+   */
+  showButtons: ["previous", "next"],
+  nextBtnText: "下一步",
+  prevBtnText: "跳过",
+  doneBtnText: "知道了",
+  /**
+   * 🔴 **点蒙层 / 按 ESC 都不退出**（甲方 2026-09-16）：引导是一条有始有终的链路，
+   * 误触蒙层就整条消失、且进度已按「露过面」记下 ⇒ 用户再也等不到它。
+   * 要退出 [MUST] 显式点「跳过」。
+   */
+  allowClose: !1,
+  /**
+   * 等锚点挂载（ms）。跨路由 / 懒加载页的锚点不会立刻在 DOM 里，driver.js 自带
+   * MutationObserver 等它出现 ⇒ [MUST NOT] 自己写轮询。
+   */
+  waitForElement: 3e3,
+  /** 等超时仍没有 → 跳过该步继续，[MUST NOT] 让它退化成「屏幕中央的空高亮」 */
+  skipMissingElement: !0
+}, re = (e) => {
+  var r, o;
+  return {
+    element: e.element,
+    advanceOnClick: e.advanceOnClick,
+    disableActiveInteraction: e.disableActiveInteraction,
+    waitForElement: e.waitForElement,
+    popover: {
+      title: e.title,
+      description: e.description,
+      side: (r = e.popover) == null ? void 0 : r.side,
+      align: (o = e.popover) == null ? void 0 : o.align,
+      /**
+       * 🔴 **[MUST] 显式清空**：driver.js 在**首步硬编码禁用 `previous`**
+       * （源码 `disableButtons:[...isFirst?[]:["previous"]]`），而本包把那一位复用成了
+       * 「跳过」⇒ 不覆盖的话，第一步的「跳过」是灰的、点不动 —— 偏偏第一步最需要它。
+       *
+       * 覆盖点 [MUST] 在 **step 级**：driver.js 取值是
+       * `step.disableButtons || globalConfig.disableButtons || []`，
+       * step 级的首步默认值 `["previous"]` 非空、会把全局配置整个吃掉。
+       * 传空数组即可（`[]` 是 truthy，取得到）。
+       */
+      disableButtons: [],
+      /**
+       * 「点目标才前进」的步**隐去「下一步」**：推进方式已经换成点高亮元素，
+       * 再留一个能绕过去的按钮，这一步的引导就白做了。「跳过」保留 —— 用户随时可退。
+       * （driver.js 的 `previous` 位在本包是「跳过」，见 DEFAULT_DRIVER_CONFIG。）
+       */
+      showButtons: e.advanceOnClick ? ["previous"] : void 0
+    },
+    data: { guideKey: e.key, guideRoute: e.route }
+  };
+}, oe = (e) => {
+  var r;
+  return (r = e == null ? void 0 : e.data) == null ? void 0 : r.guideRoute;
+}, te = (e) => {
+  var r;
+  return (r = e == null ? void 0 : e.data) == null ? void 0 : r.guideKey;
+}, ne = (e, r) => {
+  if (!e || typeof MutationObserver > "u") return () => {
+  };
+  const o = () => e.getClientRects().length === 0;
+  if (o()) return () => {
+  };
+  const s = new MutationObserver(() => {
+    o() && (s.disconnect(), r());
+  });
+  return s.observe(document.body, {
+    childList: !0,
+    subtree: !0,
+    attributes: !0,
+    attributeFilter: ["style", "class", "hidden"]
+  }), () => s.disconnect();
+}, ie = (e) => {
+  const { steps: r, router: o, driverConfig: s, onStepSeen: c } = e;
+  Q();
+  const t = r.map(re), i = (v, g) => {
+    const u = oe(v);
+    if (!u || !o || o.currentRoute.value.path === u) {
+      g();
+      return;
+    }
+    o.push(u).catch(() => {
+    }).then(g, g);
+  };
+  let n = () => {
+  };
+  const l = M({
+    ...ee,
+    ...s,
+    steps: t,
+    onNextClick: (v, g, u) => {
+      const x = u.index ?? 0;
+      i(t[x + 1], () => u.driver.moveNext());
+    },
+    // 「上一步」位已复用为「跳过」⇒ 点它即销毁整条导览，[MUST NOT] 再 movePrevious
+    onPrevClick: (v, g, u) => {
+      u.driver.destroy();
+    },
+    onHighlighted: (v, g) => {
+      const u = te(g);
+      u && c(u), n(), n = ne(v, () => {
+        l.isActive() && (l.hasPreviousStep() ? l.movePrevious() : l.destroy());
+      });
+    }
+  });
+  return i(t[0], () => l.drive()), {
+    destroy: () => {
+      n(), l.isActive() && l.destroy();
+    }
+  };
+}, I = "dc-plugin-guide", se = ["new", "updated"], ce = "guide/seen", de = (e) => {
+  const r = e == null ? void 0 : e.bridge;
+  if (!(r != null && r.badge) || typeof r.getStorage != "function")
+    throw new Error(
+      `${I}: 安装面是 core bridge 的插件面，请用 coreBridge.use(guide)，[MUST NOT] 用 app.use(guide)（两者 install 签名不同）`
+    );
+  return r;
+}, ge = (e = {}) => {
+  const r = e.badgeKinds ?? se, o = e.storageKey ?? ce, s = e.name ?? I, c = /* @__PURE__ */ new Set(), t = S(), i = S();
+  let n;
+  const l = A(
+    () => {
+      var d, a;
+      return T({
+        marks: ((d = t.value) == null ? void 0 : d.badge.marks.value) ?? {},
+        badgeKinds: r,
+        steps: e.steps,
+        routes: (a = t.value) == null ? void 0 : a.getRoutes(),
+        hasRouter: !!e.router,
+        warned: c
+      });
+    }
+  ), v = A(() => {
+    const d = i.value;
+    if (!d) return l.value;
+    const a = d.seen.value;
+    return l.value.filter((f) => !a.includes(f.key));
+  }), g = (d) => {
+    var w, E, _, $;
+    const a = d.keys && Array.from(new Set(d.keys));
+    if (!a)
+      return d.force ? l.value : v.value;
+    const f = (b) => a.map((k) => b.find((G) => G.sourceKey === k)).filter((k) => !!k);
+    if ((w = e.steps) != null && w.length)
+      return f(d.force ? l.value : v.value);
+    const p = T({
+      marks: ((E = t.value) == null ? void 0 : E.badge.marks.value) ?? {},
+      badgeKinds: r,
+      steps: a.map((b) => ({ badgeKey: b })),
+      routes: (_ = t.value) == null ? void 0 : _.getRoutes(),
+      hasRouter: !!e.router,
+      warned: c
+    });
+    if (d.force) return p;
+    const D = (($ = i.value) == null ? void 0 : $.seen.value) ?? [];
+    return p.filter((b) => !D.includes(b.key));
+  }, u = () => {
+    n == null || n.destroy(), n = void 0;
+  };
+  return {
+    name: s,
+    install: (d) => {
+      const a = de(d);
+      t.value = a, i.value = L(a.getStorage(), o);
+    },
+    pendingSteps: v,
+    start: (d = {}) => {
+      const a = g(d);
+      return a.length ? (u(), n = ie({
+        steps: a,
+        router: e.router,
+        driverConfig: e.driverConfig,
+        onStepSeen: (f) => {
+          var p;
+          return (p = i.value) == null ? void 0 : p.markSeen(f);
+        }
+      }), !0) : !1;
+    },
+    stop: u,
+    isSeen: (d) => {
+      var a;
+      return ((a = i.value) == null ? void 0 : a.isSeen(d)) ?? !1;
+    },
+    markSeen: (d) => {
+      var a;
+      return (a = i.value) == null ? void 0 : a.markSeen(d);
+    },
+    reset: () => {
+      var d;
+      return (d = i.value) == null ? void 0 : d.reset();
+    }
+  };
+};
+export {
+  I as GUIDE_PLUGIN_NAME,
+  ge as createGuidePlugin,
+  F as guideBadgeAnchorSelector,
+  j as guideResolveBadgeAnchor
+};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@done-coding/forge-plugin-guide",
+  "version": "0.0.1-alpha.0",
+  "description": "内部前端库",
+  "private": false,
+  "main": "es/index.mjs",
+  "module": "es/index.mjs",
+  "types": "types/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./es/index.mjs",
+      "types": "./types/index.d.ts"
+    },
+    "./style.css": "./es/style.css"
+  },
+  "files": [
+    "es",
+    "types"
+  ],
+  "scripts": {
+    "serve": "vite",
+    "predev": "dc-inject",
+    "dev": "vite --config vite.demo.config.ts",
+    "prehotBuild": "dc-inject",
+    "hotBuild": "vite build -w",
+    "prebuild": "rimraf types && dc-inject",
+    "build": "vue-tsc && vite build",
+    "prepack": "pnpm build",
+    "test": "vitest --config vite.demo.config.ts",
+    "coverage": "vitest run --coverage --config vite.demo.config.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/done-coding/done-coding-admin.git",
+    "directory": "packages/plugin-guide"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": "JustSoSu",
+  "license": "MIT",
+  "sideEffects": [
+    "**/*.css",
+    "**/*.less"
+  ],
+  "devDependencies": {
+    "@done-coding/admin-core": "^0.28.1-alpha.0",
+    "@done-coding/cli-inject": "0.6.3",
+    "@types/node": "^18.0.0",
+    "@vitejs/plugin-vue": "^5.0.4",
+    "@vitejs/plugin-vue-jsx": "^4.1.2",
+    "@vitest/coverage-istanbul": "^1.6.1",
+    "happy-dom": "^14.12.3",
+    "rimraf": "^5.0.1",
+    "typescript": "^5.8.3",
+    "vite": "^5.2.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^1.6.1",
+    "vue-router": "^4.3.0",
+    "vue-tsc": "^2.2.12"
+  },
+  "peerDependencies": {
+    "@done-coding/admin-core": "workspace:^",
+    "vue": "^3.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "dependencies": {
+    "driver.js": "^1.8.0"
+  },
+  "gitHead": "89cee2eb458d349b9a6f2f1acb6088f811cd5e8d"
+}

package/types/anchor.d.ts

@@ -0,0 +1,12 @@
+/** 徽标 key 对应的角标元素选择器（driver.js 的 `element` 吃字符串选择器，故独立导出） */
+export declare const guideBadgeAnchorSelector: (badgeKey: string) => string;
+/**
+ * 解析徽标 key 的高亮锚点。
+ *
+ * `[data-dc-badge-key="K"]` → 向上 `closest` 到宿主 → **够不到就用角标元素自身**。
+ *
+ * 取宿主而非角标：角标只是个十几 px 的 pill，高亮它等于指着一个小圆点说「看这里」；
+ * 宿主才是用户真正要点的那个东西（菜单项 / 按钮 / 卡片）。宿主够不到时降级用角标，
+ * [MUST NOT] 返回 `undefined` —— 有个偏小的高亮也远好过整步消失。
+ */
+export declare const guideResolveBadgeAnchor: (badgeKey: string) => HTMLElement | undefined;

package/types/index.d.ts

@@ -0,0 +1,3 @@
+export { createGuidePlugin, GUIDE_PLUGIN_NAME } from './plugin';
+export { guideBadgeAnchorSelector, guideResolveBadgeAnchor } from './anchor';
+export type { GuideBadgeKind, GuidePlugin, GuidePluginOptions, GuideResolvedStep, GuideRouterLike, GuideStartOptions, GuideStep, } from './types';

package/types/plugin.d.ts

@@ -0,0 +1,19 @@
+import { GuidePlugin, GuidePluginOptions } from './types';
+/** 插件名（bridge 插件宿主按它做跨对象实例的幂等安装） */
+export declare const GUIDE_PLUGIN_NAME = "dc-plugin-guide";
+/**
+ * 引导插件工厂。
+ *
+ * 返回的对象**同时是 core bridge 插件**（`name` + `install`）**和控制器**
+ * （`start` / `stop` / 进度读写）——应用层自己持这个引用，本插件不做 provide/inject。
+ *
+ * 实例状态全在本次调用的闭包里，零模块级单例（守实例隔离，与 core bridge 同规矩）。
+ *
+ * @example
+ * ```ts
+ * const guide = createGuidePlugin({ badgeKinds: ["new", "updated"], router });
+ * appCoreBridge.use(guide);
+ * if (!guide.start()) ElMessage.info("暂无新功能");
+ * ```
+ */
+export declare const createGuidePlugin: (options?: GuidePluginOptions) => GuidePlugin;

package/types/progress.d.ts

@@ -0,0 +1,24 @@
+import { ShallowRef } from 'vue';
+import { StorageLike } from '@done-coding/admin-core';
+/**
+ * 导览进度（「走到第几步 / 看过没」）。
+ *
+ * 🔴 **[MUST NOT] 写回 `bridge.badge`** —— 那是**展示表**（谁该显示什么标），
+ * 不是用户状态表。把「这个用户看过了」写进去，会让一个人的浏览行为改掉全表的显示，
+ * 且轮询 `setAll` 一来就被冲掉。
+ *
+ * 存储走 **core bridge 的 `getStorage()`**（已按 app 的 namespace 派生 key 前缀），
+ * [MUST NOT] 自带一套 storage —— 会和 app 的命名空间分家，清缓存时清不干净。
+ *
+ * 每次 `createGuidePlugin` 在闭包内构造一份，零模块级单例（守实例隔离）。
+ */
+/** 进度模块 */
+export interface GuideProgress {
+    /** 已看过的 step key（响应式只读；`pendingSteps` 依赖它重算） */
+    readonly seen: Readonly<ShallowRef<readonly string[]>>;
+    isSeen: (key: string) => boolean;
+    markSeen: (key: string) => void;
+    reset: () => void;
+}
+/** 进度模块工厂 */
+export declare const createGuideProgress: (storage: StorageLike, storageKey: string) => GuideProgress;

package/types/runner.d.ts

@@ -0,0 +1,15 @@
+import { Config as DriverConfig } from 'driver.js';
+import { GuideResolvedStep, GuideRouterLike } from './types';
+/** runner 入参 */
+export interface GuideRunnerParams {
+    steps: readonly GuideResolvedStep[];
+    router?: GuideRouterLike;
+    driverConfig?: DriverConfig;
+    /** 某步被高亮 = 用户看到了它 */
+    onStepSeen: (key: string) => void;
+}
+/** 正在跑的一次导览 */
+export interface GuideRunner {
+    destroy: () => void;
+}
+export declare const guideStartRunner: (params: GuideRunnerParams) => GuideRunner;

package/types/steps.d.ts

@@ -0,0 +1,48 @@
+import { BadgeMarkMap } from '@done-coding/admin-core';
+import { GuideBadgeKind, GuideResolvedStep, GuideStep } from './types';
+/** 路由树最小结构面（`bridge.getRoutes()` 的返回结构上满足它，不焊 vue-router 类型） */
+interface GuideRouteLike {
+    path: string;
+    /** vue-router 允许 symbol；非字符串的忽略（当不了徽标 key） */
+    name?: string | symbol;
+    children?: readonly GuideRouteLike[];
+}
+/**
+ * 路由树 → `key → 次序` 表（深度优先）。
+ *
+ * 🔴 排序基准取路由树而非对象 key 顺序 / 注册顺序：菜单侧的 badge key 就是路由标识，
+ * 路由树次序 = 菜单次序 = 用户心智次序，且**稳定可复现**；
+ * 对象 key 顺序会随「谁先写进表里」漂移，加一条标就换序。
+ *
+ * **`path` 与 `name` 都登记到同一张表、共享同一个序号**：core 的菜单徽标是
+ * 「`name` 优先、`path` 兜底」两套 key 并存，只登记 path 会让以 name 注册的标
+ * 全部落进「非路由 key」那档、被排到末尾按字典序 —— 不报错，只是顺序悄悄不对了。
+ */
+export declare const guideBuildRouteOrder: (routes: readonly GuideRouteLike[] | undefined) => Map<string, number>;
+/** 解析入参 */
+export interface GuideResolveStepsParams {
+    /** 徽标表快照（`bridge.badge.marks.value`） */
+    marks: BadgeMarkMap;
+    /** 进导览的 kind */
+    badgeKinds: readonly GuideBadgeKind[];
+    /** 显式编排；传了就以它为准 */
+    steps?: readonly GuideStep[];
+    /** 路由树（排序基准） */
+    routes?: readonly GuideRouteLike[];
+    /** 是否配了 router（没配则带 `route` 的步骤跳过 + 警告） */
+    hasRouter: boolean;
+    /** 当前时刻（可注入，便于测过期判定） */
+    now?: number;
+    /** 一次性警告去重（同一实例同一 key 只吵一次） */
+    warned?: Set<string>;
+}
+/**
+ * 解析出**有序**的引导步骤。
+ *
+ * - 传了 `steps` → **以它为准**（数组顺序即步序）；
+ * - 没传 → 由 badge 表自动串：筛 `badgeKinds` → 按路由树次序排 → 成步。
+ *
+ * [MUST NOT] 做「显式 + 自动」拼接：那会让顺序落在两套规则的交界上，正是要避的坑。
+ */
+export declare const guideResolveSteps: (params: GuideResolveStepsParams) => GuideResolvedStep[];
+export {};

package/types/theme.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 把 driver.js 的弹窗接进本仓主题（本包「长得像不像自家组件」那一半）。
+ *
+ * 🔴 **为什么必须自己写**：driver.js 只暴露两个 CSS 变量（`--driver-animation-duration`
+ * / `--driver-popover-font-family`），**颜色全是写死的**——`.driver-popover` 是
+ * `#fff` 底 `#2d2d2d` 字、按钮 `#ccc` 边。暗色主题下就是一块白底黑字的弹窗浮在深色页面上。
+ *
+ * 🔴 **为什么是运行时注入而不是 `.less` 文件**：driver.js 的弹窗 teleport 到 `body`，
+ * scoped 样式够不着；而本包的 `driver.css` 是走 **external**（`driver.js/` 前缀命中
+ * vite external 规则）由消费方打包器解析的，本包自身**没有 style.css 产物**。
+ * 若为这段样式新开一个 css 入口，消费方就得多 `import` 一次样式文件（硬规则 6 那个坑）
+ * ⇒ 改用运行时注入，零接入成本，且 `var()` 让它随主题切换自动跟。
+ *
+ * 颜色一律走 `--dc-core-*` 优先、`--el-*` 兜底的双源（规则 14），[MUST NOT] 写死色值。
+ */
+/**
+ * 确保主题样式已注入（幂等；SSR / 无 document 环境静默跳过）。
+ *
+ * 在 runner 启动时调用而非模块期——模块期副作用会让 SSR 导入即写 DOM，
+ * 且妨碍 tree-shaking。
+ */
+export declare const guideEnsureTheme: () => void;

package/types/types.d.ts

@@ -0,0 +1,192 @@
+import { BadgeEntry } from '@done-coding/admin-core';
+import { Config as DriverConfig, DriveStep, Popover } from 'driver.js';
+import { ComputedRef } from 'vue';
+/**
+ * 进导览的徽标类型。
+ *
+ * 取 `BadgeEntry["kind"]`（对「交叉 + 联合」做索引访问即得全集）——
+ * [MUST NOT] 为此在 core 新增 kind 全集类型，也 [MUST NOT] 用 `BadgeBuiltinKind`
+ * （它不含 `count` / `custom`，会让应用层配不了自定义标）。
+ */
+export type GuideBadgeKind = BadgeEntry["kind"];
+/**
+ * 路由器最小结构面。
+ *
+ * 只取本插件真正用到的两件事，[MUST NOT] 把 vue-router 的 `Router` 焊进对外类型——
+ * 那会让本包的 `types` 强依赖 vue-router（消费方未必装，也未必是同一大版本）。
+ * vue-router 的 `Router` 结构上满足本接口，直接传即可。
+ */
+export interface GuideRouterLike {
+    /** 当前路由（只读 path，用于判断「是不是已经在那一页了」） */
+    currentRoute: {
+        value: {
+            path: string;
+        };
+    };
+    /**
+     * 跳转。
+     *
+     * 写成函数属性（而非方法简写）仍吃得下 vue-router 的 `Router.push` ——
+     * 它的入参 `RouteLocationRaw` 比 `string` 宽，函数属性在 `strictFunctionTypes`
+     * 下按逆变判定，宽入参赋给窄入参是合法的。
+     */
+    push: (to: string) => Promise<unknown>;
+}
+/** 单个引导步骤（显式编排用；不传 `steps` 时由 badge 表自动串出同型对象） */
+export interface GuideStep {
+    /**
+     * 步骤 key —— **进度表以它记「看过没」**。
+     * 缺省取 `badgeKey`；两者都没有则该步被丢弃（无从记进度）。
+     */
+    key?: string;
+    /**
+     * 引用 badge 表里的一条：继承它的 `description`（讲解正文）与锚点。
+     * 这是本插件的杠杆点——**[MUST NOT] 让业务再埋一套 `data-tour-step`**。
+     */
+    badgeKey?: string;
+    /** 显式锚点（CSS 选择器 / 元素 / 取元素的函数，透传 driver.js），覆盖 `badgeKey` 的解析结果 */
+    element?: DriveStep["element"];
+    /**
+     * **点高亮元素即进下一步**（默认 `false` = 点「下一步」才走）。
+     *
+     * 交互式引导用它串真实操作链：点菜单 → 跳页 → 点「创建」→ 弹窗出现 → 填表 → 提交。
+     * 每一步的锚点由**用户的真实点击**推进，而不是照着念。
+     *
+     * 配套：声明了本项的步会**自动隐去「下一步」**（推进方式已经变成「点目标」，
+     * 再留一个能绕过去的按钮，引导就白做了）；「跳过」仍在，用户随时可退。
+     * 要覆盖这个配套就显式传 `showButtons`。
+     *
+     * ⚠️ 本步之后的导航由**用户的操作自然完成**（点菜单本来就会跳页），
+     * [MUST NOT] 再给下一步配 `route` 指望插件替他跳 —— 那会跳两次。
+     * 下一步的锚点没那么快出现是正常的，交给 {@link waitForElement} 等。
+     */
+    advanceOnClick?: boolean;
+    /**
+     * **禁止**用户与高亮元素交互（默认 `false` = 镂空区**可以点**）。
+     *
+     * 纯讲解、又怕用户误触时才打开。与 {@link advanceOnClick} 互斥——
+     * 禁了交互就点不动，也就无从「点了才前进」。
+     */
+    disableActiveInteraction?: boolean;
+    /**
+     * 该步等锚点挂载的超时（ms），覆盖全局默认 3000。
+     *
+     * 交互式链路里调大它：点「创建」到弹窗渲染完、或跨路由页面加载，都可能超过默认值。
+     * 等超时仍没有 → 按 `skipMissingElement` 跳过该步继续。
+     */
+    waitForElement?: number;
+    /** 气泡标题 */
+    title?: string;
+    /** 气泡正文；缺省取 `badgeKey` 对应标的 `description` */
+    description?: string;
+    /**
+     * 锚点所在路由 —— 不在当前页时先 `router.push(route)` 再等元素挂载。
+     * 菜单项角标恒在侧边栏、一般不需要本字段；「锚点长在某页内部」才用。
+     */
+    route?: string;
+    /** 透传 driver.js 气泡的方位（其余 popover 能力走 `driverConfig`，不在此重复开洞） */
+    popover?: Pick<Popover, "side" | "align">;
+}
+/** 解析后的步骤（已定序、已补齐正文与锚点，内部形态） */
+export interface GuideResolvedStep extends GuideStep {
+    /**
+     * 进度 key —— 已确保存在；标配了 `version` 时形如 `原key@版本`。
+     * 🔴 按模块筛选 [MUST NOT] 拿它比对（版本一改就对不上），用 {@link sourceKey}。
+     */
+    key: string;
+    /**
+     * 配置里写的那个 key（`step.key ?? step.badgeKey`，**未拼版本**）。
+     *
+     * 专供「按模块筛选」用（`start({ keys })`）：应用层手上只有自己配的 key，
+     * 不知道也不该关心当前版本号。与 {@link key} 的分工——`key` 记进度、`sourceKey` 做引用。
+     */
+    sourceKey: string;
+    /** 已确保非空（无正文的步骤在解析期就被剔除了） */
+    description: string;
+}
+/** `createGuidePlugin` 入参 */
+export interface GuidePluginOptions {
+    /**
+     * 进导览的徽标类型，默认 `["new", "updated"]`。
+     *
+     * 默认只收「资讯档」两项：`beta` 语义是「不稳定需谨慎」、`wip` 是「还不能用」、`locked` 会遮挡宿主交互、
+     * `deprecated` 是待下线、`count` 是待办数、`custom` 语义 core 不知道 —— 都不该主动导览。
+     *
+     * `anchor`（纯锚点伪标）同样**不进默认值**：它本就没有「新功能」语义，
+     * 只提供 DOM 挂点，[MUST] 由显式 `steps` 用 `badgeKey` 引用。
+     */
+    badgeKinds?: GuideBadgeKind[];
+    /**
+     * 显式编排。**传了就以它为准**（数组顺序即步序），不传才由 badge 表自动串。
+     * [MUST NOT] 期望「显式 + 自动」拼接——那会让顺序落在两套规则的交界上。
+     */
+    steps?: GuideStep[];
+    /** 路由器（只有带 `route` 的步骤才需要；缺它时那些步骤会被跳过 + dev 警告） */
+    router?: GuideRouterLike;
+    /** 进度在 bridge storage 里的 key，默认 `"guide/seen"` */
+    storageKey?: string;
+    /**
+     * 插件名，默认 `"dc-plugin-guide"`。
+     *
+     * bridge 插件宿主**按名幂等**——同名的第二个实例会被静默跳过。要在同一个 app 里
+     * 装多份导览（如「新手上路」与「本期新功能」各一份），[MUST] 给它们不同的 `name`
+     * **和不同的 `storageKey`**（否则两份进度会互相污染）。
+     */
+    name?: string;
+    /** 透传 driver.js 全局配置（本包只预设少数几项，其余原样交给 driver.js） */
+    driverConfig?: DriverConfig;
+}
+/** `start()` 入参 */
+export interface GuideStartOptions {
+    /** 忽略进度、把所有入选步骤重跑一遍 */
+    force?: boolean;
+    /**
+     * **只跑这几个 key，且步序就是本数组的顺序**（不传 = 全部、按自动串的次序）——
+     * 模块化导览：a 模块 `start({ keys: [...] })` 只讲自己那几步，b 模块讲另外几步。
+     *
+     * 🔴 **顺序以本数组为准**，[MUST NOT] 指望它还按路由树次序排：显式传 keys 的调用方
+     * 知道自己要按什么次序讲。数组内重复的 key 会先去重（同一步讲两遍是噪音）；
+     * 指向「没打标 / 已看过 / 已过期」的 key 会被静默略过（不报错，也不占位）。
+     *
+     * 比对的是 {@link GuideResolvedStep.sourceKey}（配置里写的 key，**不带版本号**）
+     * ⇒ 应用层照自己配的那个 key 传即可，[MUST NOT] 自己去拼 `key@version`。
+     *
+     * 🔴 **共用同一份进度表**（同一实例）：同一个人在 a 模块看过的那步，
+     * b 模块再调也不会重复讲 —— 这正是「筛选」相对「每模块各建一个实例」的好处，
+     * 后者会让进度按实例分家、同一步被讲两遍。
+     */
+    keys?: readonly string[];
+}
+/**
+ * 引导控制器 —— `createGuidePlugin` 的返回值。
+ *
+ * 它**同时是 core bridge 插件对象**（`name` + `install`），经
+ * `coreBridge.use(guide)` 安装；应用层自己持这个引用调 `start` / `reset`
+ * （本插件不做 provide/inject —— 应用层本就在自己的模块里持有它，YAGNI）。
+ */
+export interface GuidePlugin {
+    /** 插件名（bridge 插件宿主按它做跨对象实例的幂等安装） */
+    name: string;
+    /**
+     * bridge 插件安装函数 —— 由 `coreBridge.use(guide)` 调用。
+     *
+     * ⚠️ [MUST NOT] 自己调，也 [MUST NOT] `app.use(guide)`：那会把 Vue 的 `app`
+     * 当 `ctx` 传进来（同名不同签名），本函数有守卫会抛出带指引的错误。
+     */
+    install: (ctx: unknown) => void;
+    /** 待导览步骤（响应式只读；未入选 / 已看过的已剔除。未安装前恒为空） */
+    readonly pendingSteps: ComputedRef<GuideResolvedStep[]>;
+    /**
+     * 启动导览。返回**是否真的启动**——没有可跑的步骤时返回 `false`
+     * （应用层据此决定要不要提示「暂无新功能」，[MUST NOT] 让它弹一个空导览）。
+     */
+    start: (options?: GuideStartOptions) => boolean;
+    /** 停止并销毁 driver 实例（幂等） */
+    stop: () => void;
+    /** 该步骤是否已看过 */
+    isSeen: (key: string) => boolean;
+    /** 标记看过（随手持久化） */
+    markSeen: (key: string) => void;
+    /** 清空进度 */
+    reset: () => void;
+}