dsh-milestone 0.6.3 → 0.6.5

package/README.md

@@ -68,6 +68,7 @@ npx @deepseek-ai/dsh web    # → http://127.0.0.1:3080
 | 个性化与效率 | 个性化外观：强调色 / 图标圆点大小 / 距侧边距离 / 位置左右（设置内即调即存） | |
 | 个性化与效率 | 语言切换：跟随系统 / 中文 / English，设置内一键切换 | |
 | 个性化与效率 | 点击外部关闭：搜索 / 列表等浮层自动收起 | |
+| 个性化与效率 | 新手教程：首次使用教练气泡引导，锚定真实组件（点击真实推进），设置内可重看 | |
 | 发布运维 | 更新检测：6h 缓存自动检查，新版徽章，一键去 npm | |
 | 发布运维 | 设置推广区：GitHub / Star / Issue / npm 四入口 | |
 
@@ -164,7 +165,22 @@ shell.overlay (root scope)
 ## 更新日志
 
 <details>
-<summary>v0.6.3 / v0.6.2 / v0.6.1 / v0.6.0（点击展开）</summary>
+<summary>v0.6.5 / v0.6.4 / v0.6.3 / v0.6.2 / v0.6.1 / v0.6.0（点击展开）</summary>
+
+**v0.6.5** · 真实组件教练教程 + 设置对比度修复 · 386 项测试
+
+- **新手教程改为教练气泡（coach-mark）**：气泡锚定真实组件——欢迎 → 点展开箭头（真实点击自动推进）→ 点设置齿轮（真实打开自动推进，设置开着气泡挂起）→ 圆点 → 完成；目标高亮环 + 就近气泡 + 进度点 + 随时跳过，全部双语。
+- **设置模态白色背景修复**：UA 默认按钮底色漏出导致浅底浅字不可读，基础态补透明规则（Playwright 计算色实测验证）。
+
+> [GitHub Release v0.6.5](https://github.com/SnowCrescenter-tech/dsh-milestone/releases/tag/v0.6.5)
+
+**v0.6.4** · 新手教程 · 385 项测试
+
+- **首次使用引导**：第一次安装后进入首个可用会话时弹出教程（全局持久化，**印象即写**——欢迎页一显示即记录，关页/刷新不重弹；想再看走设置里的「重新查看教程」）。
+- 4 步教学 + 内置演示：迷你圆点条 hover/点击、玩具搜索与收藏、个性化与设置图例、更新检测与支持；进度点 + 上一步/下一步 + 随时跳过，全部双语。
+- 设置与教程模态视觉共用 `modal-tokens.ts` 单一来源。
+
+> [GitHub Release v0.6.4](https://github.com/SnowCrescenter-tech/dsh-milestone/releases/tag/v0.6.4)
 
 **v0.6.3** · 聚焦高级设置 + 设置模态重设计 · 363 项测试
 

package/lib/client.js

@@ -795,7 +795,41 @@ window.__ModuleLoader__.load({
 			/** Language option: force Chinese copy. */
 			"settings.lang.zh": "中文",
 			/** Language option: force English copy. */
-			"settings.lang.en": "English"
+			"settings.lang.en": "English",
+			/** 0.6.5 tour: bubble 0 title (also the bubble's aria-label). */
+			"tour.welcome.title": "欢迎使用 dsh-milestone",
+			/** 0.6.5 tour: bubble 0 description — the REAL rail list anchor. */
+			"tour.welcome.desc": "这是你的会话导航条：每条提问一个圆点，点击跳转，悬停查看元信息。",
+			/** 0.6.5 tour: bubble 1 title — the expand arrow. */
+			"tour.step1.title": "展开工具栏",
+			/** 0.6.5 tour: bubble 1 description — what clicking REALLY does (auto-advance on the real click). */
+			"tour.step1.desc": "点这里展开全部功能键：搜索、列表、收藏、聚焦、更新检测与设置都在里面。",
+			/** 0.6.5 tour: bubble 2 title — the settings gear. */
+			"tour.step2.title": "打开设置",
+			/** 0.6.5 tour: bubble 2 description — what opening settings contains (auto-advance on the real open). */
+			"tour.step2.desc": "打开设置：钉住常用键、个性化外观、切换语言、搭配「聚焦」。",
+			/** 0.6.5 tour: bubble 3 title — the dots (real hover/click behavior). */
+			"tour.step3.title": "圆点导航",
+			/** 0.6.5 tour: bubble 3 description. */
+			"tour.step3.desc": "每个圆点 = 一条提问——点击跳转，悬停查看时间、模型与用量。",
+			/** 0.6.5 tour: bubble 4 title — done. */
+			"tour.step4.title": "开始使用",
+			/** 0.6.5 tour: bubble 4 description — finish line. */
+			"tour.step4.desc": "去试试吧；有问题欢迎到 GitHub 提 Issue。",
+			/** 0.6.5 tour: primary action on bubble 0 (begin) and bubble 4 (finish). */
+			"tour.start": "开始使用",
+			/** 0.6.5 tour: forward navigation (bubbles 1–3; the real-click auto-advance comes first). */
+			"tour.next": "下一步",
+			/** 0.6.5 tour: back navigation (bubbles 1–4). */
+			"tour.prev": "上一步",
+			/** 0.6.5 tour: corner skip — every bubble, persists the flag. */
+			"tour.skip": "跳过",
+			/** 0.6.5 tour: progress text `第 n / 5 步`. */
+			"tour.step.label": "第 {n} / 5 步",
+			/** 0.6.5 tour: aria-label on one progress dot. */
+			"tour.step.short": "第 {n} 步",
+			/** 0.6.5 settings footer action: replay the tour (data-onboarding-reopen kept). */
+			"tour.reopen": "重新查看教程"
 		};
 		const en = {
 			"jump.to": "Jump to message {n}",
@@ -900,7 +934,24 @@ window.__ModuleLoader__.load({
 			"settings.language": "Language",
 			"settings.lang.system": "Follow system",
 			"settings.lang.zh": "Chinese",
-			"settings.lang.en": "English"
+			"settings.lang.en": "English",
+			"tour.welcome.title": "Welcome to dsh-milestone",
+			"tour.welcome.desc": "This is your session milestone rail: every prompt is a dot — click to jump, hover for metadata.",
+			"tour.step1.title": "Expand the toolbar",
+			"tour.step1.desc": "Click to reveal every function key: search, list, bookmarks, focus, update check, and settings.",
+			"tour.step2.title": "Open settings",
+			"tour.step2.desc": "Open settings: pin your favorite keys, personalize the look, switch language, and tune focus.",
+			"tour.step3.title": "Dot navigation",
+			"tour.step3.desc": "Each dot is one prompt — click to jump, hover for time, model, and usage.",
+			"tour.step4.title": "Get started",
+			"tour.step4.desc": "Go try it — questions and issues are welcome on GitHub.",
+			"tour.start": "Get started",
+			"tour.next": "Next",
+			"tour.prev": "Back",
+			"tour.skip": "Skip",
+			"tour.step.label": "Step {n} of 5",
+			"tour.step.short": "Step {n}",
+			"tour.reopen": "Replay the tour"
 		};
 		/**
 		* Interpolate `{name}` placeholders with params, matching the harness t seat's
@@ -1328,6 +1379,414 @@ window.__ModuleLoader__.load({
 				]
 			});
 		}
+		const MODAL_FG = "#e6e8ee";
+		const MODAL_TITLE = "#c7cede";
+		const MODAL_TEXT = "#b9c2d4";
+		const MODAL_HINT = "#8b96ab";
+		const MODAL_BORDER = "rgba(255, 255, 255, 0.14)";
+		const MODAL_TIP_BG = "#222834";
+		//#endregion
+		//#region src/client/onboarding-store.ts
+		/**
+		* onboarding-store: the persistence layer for the 0.6.4 first-run tutorial —
+		* a single "has the user seen it" flag with NO payload.
+		*
+		* Storage contract: one localStorage key (`dsh-milestone.onboarded`) whose
+		* VALUE is exactly the string `'1'` when the tutorial was completed or
+		* skipped. Anything else (absent key, `'0'`, `'true'`, garbage) means "never
+		* shown" and re-triggers the tutorial.
+		*
+		* Both accessors swallow storage failures silently (SSR, sandboxed iframe,
+		* quota): the tutorial is a best-effort enhancement — a broken storage must
+		* never crash the rail, and a user in that environment simply sees the
+		* tutorial once per page load instead of once ever.
+		*/
+		/** The single localStorage key holding the onboarding "seen" flag. */
+		const ONBOARDED_KEY = "dsh-milestone.onboarded";
+		/**
+		* True when the user already completed or skipped the tutorial (the stored
+		* value is exactly `'1'`). Storage unavailability degrades to `false`.
+		*/
+		function readOnboardedFlag() {
+			try {
+				return localStorage.getItem(ONBOARDED_KEY) === "1";
+			} catch {
+				return false;
+			}
+		}
+		/**
+		* Persist the tutorial as seen/completed by writing the literal string `'1'`.
+		* Storage failures are swallowed — the flag simply will not survive a reload.
+		*/
+		function writeOnboardedFlag() {
+			try {
+				localStorage.setItem(ONBOARDED_KEY, "1");
+			} catch {}
+		}
+		//#endregion
+		//#region src/client/MilestoneTour.tsx
+		/**
+		* MilestoneTour: the 0.6.5 first-run coach-bubble tutorial.
+		*
+		* Unlike the deleted 0.6.4 MilestoneOnboarding modal (built-in toy demos on a
+		* fake overlay), this tour never fakes anything. Each of the 5 bubbles anchors
+		* a REAL rail element (`data-rail-list`, `data-toolbar-expand`,
+		* `data-toolbar-settings`, the first `data-rail-dot`, the rail root), explains
+		* what clicking that control ACTUALLY does, and auto-advances by OBSERVING the
+		* live state the rail already owns:
+		*   - bubble 1 (expand arrow) waits for `toolbarExpanded` → true — the user
+		*     really clicked the arrow (「下一步」 remains a fallback);
+		*   - bubble 2 (settings gear) waits for `settingsOpen` → true — the settings
+		*     panel appearing IS the proof — and SUSPENDS while the modal is open
+		*     (state is kept; closing settings resumes the bubble at the current step);
+		*   - bubble 3 (dots) needs no interaction — hover/click are explained.
+		*
+		* Trigger/ownership lives in MilestoneRail (mount timer + settings reopen);
+		* this component is presentation + state machine only. It persists the
+		* `dsh-milestone.onboarded` flag itself via onboarding-store on IMPRESSION
+		* (showing bubble 0 is enough) and on every close path (skip / Esc / finish).
+		*
+		* Positioning: `position: fixed`, opened on the target's FREE side (rail on
+		* the right → bubble left of the target; rail on the left → bubble right of
+		* it), measured with getBoundingClientRect and clamped to the viewport.
+		* Re-measured on step changes, whenever the anchor may have (un)mounted (the
+		* forced toolbar expansion), and on window resize. There is NO overlay and the
+		* bubble never covers its own target — the user is supposed to CLICK the real
+		* controls, so pointer-events live only on the bubble box itself.
+		*
+		* Anchor guarantee: entering any step ≥ 2 calls `onSetToolbarExpanded(true)`
+		* because `data-toolbar-settings` renders only while the toolbar is expanded
+		* (or the gear pinned) — the 「下一步」 fallback path lands there un-expanded.
+		*
+		* Visual language reuses modal-tokens (MODAL_TIP_BG panel, one border tone,
+		* the 12/8px radius scale, three text tiers) and the rail root's inherited
+		* `--ms-accent*` CSS variables. The highlight ring is zero-asset: a
+		* `data-tour-highlight` attribute + one injected CSS rule.
+		*/
+		/** The tour bubble floats above every other rail layer (settings overlay 105). */
+		const TOUR_Z = 106;
+		/** Gap between the target element and the bubble (px). */
+		const TOUR_GAP = 12;
+		/** Bubble width (px) — the left-edge positioning math clamps against it. */
+		const TOUR_WIDTH = 280;
+		/** Minimum padding between the bubble and the viewport edges (px). */
+		const VIEWPORT_PAD = 8;
+		/** Fallback bubble height used when the layout has not settled (px). */
+		const TOUR_HEIGHT_FALLBACK = 120;
+		/** Progress-dot count — the 5 bubble steps (0 = welcome … 4 = done). */
+		const STEP_COUNT = [
+			0,
+			1,
+			2,
+			3,
+			4
+		];
+		/**
+		* Static tour styling that `:hover`/`:focus-visible`/reduced-motion need (the
+		* `:focus-visible` ring and the base-state backgrounds inline styles cannot
+		* duplicate). BASE-states first — the UA default button face must never flood
+		* through on the dark bubble (that exact bug already shipped once).
+		*/
+		const TOUR_CSS = `
+@keyframes ms-tour-fade { from { opacity: 0; transform: translateY(4px); } to { opacity: 1; transform: none; } }
+[data-tour-bubble] { animation: ms-tour-fade 160ms ease; }
+/* BASE-state backgrounds for every bubble control (transparent or themed). */
+[data-tour-skip] { background: transparent; }
+[data-tour-prev] { background: rgba(255, 255, 255, 0.06); }
+[data-tour-primary] { background: var(--ms-accent-bg); color: var(--ms-accent-soft); }
+/* Hover washes on top of the explicit base states. */
+[data-tour-skip]:hover { background: rgba(255, 255, 255, 0.08); }
+[data-tour-prev]:hover:not(:disabled) { background: rgba(255, 255, 255, 0.12); }
+[data-tour-primary]:hover { background: rgba(255, 255, 255, 0.14); }
+/* ONE accent focus ring for keyboard use. */
+[data-tour-skip]:focus-visible, [data-tour-prev]:focus-visible, [data-tour-primary]:focus-visible {
+  box-shadow: 0 0 0 2px var(--ms-accent-soft);
+}
+/* The real-target highlight ring: accent halo + a subtle scale hint. */
+[data-tour-highlight] {
+  box-shadow: 0 0 0 2px var(--ms-accent-soft), 0 0 0 4px var(--ms-accent);
+  transform: scale(1.04);
+  transition: box-shadow 140ms ease, transform 140ms ease;
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-tour-bubble] { animation: none; }
+  [data-tour-highlight] { transform: none; transition: none; }
+  [data-tour-skip], [data-tour-prev], [data-tour-primary] { transition: none; }
+}
+`;
+		/** Rail root — every step's fallback anchor and bubble 4's target. */
+		function railRoot() {
+			return document.querySelector("[data-side]");
+		}
+		const STEP_DEFS = [
+			{
+				titleKey: "tour.welcome.title",
+				descKey: "tour.welcome.desc",
+				anchor: () => document.querySelector("[data-rail-list]")
+			},
+			{
+				titleKey: "tour.step1.title",
+				descKey: "tour.step1.desc",
+				anchor: () => document.querySelector("[data-toolbar-expand]")
+			},
+			{
+				titleKey: "tour.step2.title",
+				descKey: "tour.step2.desc",
+				anchor: () => document.querySelector("[data-toolbar-settings]")
+			},
+			{
+				titleKey: "tour.step3.title",
+				descKey: "tour.step3.desc",
+				anchor: () => document.querySelector("[data-rail-dot]") ?? railRoot()
+			},
+			{
+				titleKey: "tour.step4.title",
+				descKey: "tour.step4.desc",
+				anchor: () => railRoot()
+			}
+		];
+		/** Clamp `value` into [min, max], never letting min exceed max. */
+		function clamp(value, min, max) {
+			return Math.min(Math.max(value, min), Math.max(min, max));
+		}
+		function MilestoneTour({ t, side, toolbarExpanded, settingsOpen, onSetToolbarExpanded, onClose }) {
+			const [step, setStep] = (0, react.useState)(0);
+			const [pos, setPos] = (0, react.useState)(null);
+			const bubbleRef = (0, react.useRef)(null);
+			const primaryRef = (0, react.useRef)(null);
+			const stepDef = STEP_DEFS[step];
+			(0, react.useEffect)(() => {
+				writeOnboardedFlag();
+			}, []);
+			/** Skip / finish / Escape converge here: persist, then close. */
+			const finish = (0, react.useCallback)(() => {
+				writeOnboardedFlag();
+				onClose();
+			}, [onClose]);
+			(0, react.useEffect)(() => {
+				if (settingsOpen) return;
+				const onKey = (e) => {
+					if (e.key !== "Escape") return;
+					finish();
+				};
+				window.addEventListener("keydown", onKey);
+				return () => window.removeEventListener("keydown", onKey);
+			}, [finish, settingsOpen]);
+			(0, react.useEffect)(() => {
+				if (step === 1 && toolbarExpanded) setStep(2);
+			}, [step, toolbarExpanded]);
+			(0, react.useEffect)(() => {
+				if (step === 2 && settingsOpen) setStep(3);
+			}, [step, settingsOpen]);
+			(0, react.useEffect)(() => {
+				if (step >= 2 && !toolbarExpanded) onSetToolbarExpanded(true);
+			}, [
+				step,
+				toolbarExpanded,
+				onSetToolbarExpanded
+			]);
+			/** Measure the current anchor and place the bubble on its free side. */
+			const measure = (0, react.useCallback)(() => {
+				const anchor = STEP_DEFS[step].anchor();
+				const bubble = bubbleRef.current;
+				if (anchor === null || bubble === null) {
+					setPos(null);
+					return;
+				}
+				const rect = anchor.getBoundingClientRect();
+				const bw = bubble.offsetWidth || TOUR_WIDTH;
+				const bh = bubble.offsetHeight || TOUR_HEIGHT_FALLBACK;
+				const left = clamp(side === "left" ? rect.right + TOUR_GAP : rect.left - TOUR_GAP - bw, VIEWPORT_PAD, window.innerWidth - bw - VIEWPORT_PAD);
+				const top = clamp(rect.top + rect.height / 2 - bh / 2, VIEWPORT_PAD, window.innerHeight - bh - VIEWPORT_PAD);
+				setPos({
+					left,
+					top
+				});
+			}, [step, side]);
+			(0, react.useLayoutEffect)(() => {
+				measure();
+				window.addEventListener("resize", measure);
+				return () => window.removeEventListener("resize", measure);
+			}, [
+				measure,
+				toolbarExpanded,
+				settingsOpen
+			]);
+			(0, react.useEffect)(() => {
+				document.querySelectorAll("[data-tour-highlight]").forEach((el) => el.removeAttribute("data-tour-highlight"));
+				const anchor = STEP_DEFS[step].anchor();
+				if (anchor !== null) anchor.setAttribute("data-tour-highlight", "");
+				return () => {
+					document.querySelectorAll("[data-tour-highlight]").forEach((el) => el.removeAttribute("data-tour-highlight"));
+				};
+			}, [
+				step,
+				toolbarExpanded,
+				settingsOpen
+			]);
+			(0, react.useEffect)(() => {
+				if (settingsOpen) return;
+				primaryRef.current?.focus();
+			}, [step, settingsOpen]);
+			const goNext = () => setStep((s) => Math.min(STEP_COUNT.length - 1, s + 1));
+			const goPrev = () => setStep((s) => Math.max(0, s - 1));
+			if (settingsOpen) return null;
+			const isLast = step === STEP_COUNT.length - 1;
+			const primaryLabel = step === 0 || isLast ? t("tour.start") : t("tour.next");
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				ref: bubbleRef,
+				"data-tour-bubble": true,
+				"data-tour-step": step,
+				role: "dialog",
+				"aria-label": t(stepDef.titleKey),
+				style: {
+					position: "fixed",
+					left: pos?.left,
+					top: pos?.top,
+					width: TOUR_WIDTH,
+					maxWidth: "calc(100vw - 24px)",
+					boxSizing: "border-box",
+					zIndex: TOUR_Z,
+					padding: 14,
+					background: MODAL_TIP_BG,
+					color: MODAL_FG,
+					borderRadius: 12,
+					border: `1px solid ${MODAL_BORDER}`,
+					boxShadow: "0 12px 36px rgba(0, 0, 0, 0.45)"
+				},
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("style", { children: TOUR_CSS }),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						style: {
+							display: "flex",
+							alignItems: "flex-start",
+							justifyContent: "space-between",
+							gap: 8
+						},
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+							"data-tour-title": true,
+							style: {
+								fontSize: 14,
+								fontWeight: 700,
+								color: MODAL_FG,
+								lineHeight: 1.35
+							},
+							children: t(stepDef.titleKey)
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							type: "button",
+							"data-tour-skip": true,
+							onClick: finish,
+							style: {
+								flexShrink: 0,
+								background: "transparent",
+								border: "none",
+								padding: "2px 6px",
+								borderRadius: 8,
+								cursor: "pointer",
+								color: MODAL_HINT,
+								fontSize: 12,
+								lineHeight: 1.4
+							},
+							children: t("tour.skip")
+						})]
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						"data-tour-desc": true,
+						style: {
+							marginTop: 6,
+							fontSize: 12.5,
+							lineHeight: 1.5,
+							color: MODAL_TEXT
+						},
+						children: t(stepDef.descKey)
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("footer", {
+						style: {
+							display: "flex",
+							alignItems: "center",
+							justifyContent: "space-between",
+							gap: 10,
+							marginTop: 12
+						},
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								"data-tour-prev": true,
+								disabled: step === 0,
+								onClick: goPrev,
+								style: {
+									flexShrink: 0,
+									background: "rgba(255, 255, 255, 0.06)",
+									border: `1px solid ${MODAL_BORDER}`,
+									borderRadius: 8,
+									padding: "5px 12px",
+									cursor: step === 0 ? "default" : "pointer",
+									color: step === 0 ? MODAL_HINT : MODAL_TEXT,
+									fontSize: 12,
+									lineHeight: 1.4,
+									opacity: step === 0 ? .55 : 1
+								},
+								children: t("tour.prev")
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								style: {
+									display: "flex",
+									flexDirection: "column",
+									alignItems: "center",
+									gap: 5,
+									minWidth: 74
+								},
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+									"data-tour-progress": true,
+									style: {
+										fontSize: 11.5,
+										color: MODAL_HINT,
+										lineHeight: 1.2
+									},
+									children: t("tour.step.label", { n: step + 1 })
+								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+									style: {
+										display: "flex",
+										gap: 4
+									},
+									children: STEP_COUNT.map((n) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+										"data-tour-progress-dot": true,
+										"data-active": step === n ? "true" : void 0,
+										"aria-label": t("tour.step.short", { n: n + 1 }),
+										"aria-current": step === n ? "step" : void 0,
+										style: {
+											width: 14,
+											height: 4,
+											borderRadius: 2,
+											background: step === n ? "var(--ms-accent)" : "rgba(255, 255, 255, 0.18)"
+										}
+									}, n))
+								})]
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								ref: primaryRef,
+								"data-tour-primary": true,
+								onClick: isLast ? finish : goNext,
+								style: {
+									flexShrink: 0,
+									background: "var(--ms-accent-bg)",
+									color: "var(--ms-accent-soft)",
+									border: "1px solid var(--ms-accent)",
+									borderRadius: 8,
+									padding: "5px 14px",
+									cursor: "pointer",
+									fontSize: 12.5,
+									fontWeight: 600,
+									lineHeight: 1.4
+								},
+								children: primaryLabel
+							})
+						]
+					})
+				]
+			});
+		}
 		//#endregion
 		//#region src/client/MilestoneRailTooltip.tsx
 		/**
@@ -2279,7 +2738,7 @@ window.__ModuleLoader__.load({
 		* Installed plugin version. Injected at build time as
 		* `__DSH_MILESTONE_VERSION__`; falls back to `0.0.0-dev` when unbuilt.
 		*/
-		const PLUGIN_VERSION = "0.6.3";
+		const PLUGIN_VERSION = "0.6.5";
 		//#endregion
 		//#region src/client/MilestoneRail.tsx
 		/**
@@ -2324,6 +2783,13 @@ window.__ModuleLoader__.load({
 		* hover descriptions, the personalization controls, and the support-us card
 		* grid); everything the modal changes persists under `dsh-milestone.toolbar`.
 		*/
+		/**
+		* Settings modal shared palette + geometry — ONE source in modal-tokens.ts,
+		* also consumed by the 0.6.4 onboarding tutorial modal so the two dialogs
+		* cannot drift. Dark panel on a dark host, three text tiers (primary /
+		* section title / hint + muted), one border tone, a 12px panel / 8px control
+		* radius scale and a 4-unit spacing scale (4 / 8 / 12 / 16 / 20).
+		*/
 		/** Minimum user messages before the rail adds value. */
 		const MIN_MARKS = 2;
 		const PREVIEW_LENGTH = 80;
@@ -2422,22 +2888,6 @@ window.__ModuleLoader__.load({
 			}
 			return rules.join("\n");
 		}
-		/**
-		* Settings modal shared palette + geometry — one source for the inline
-		* styles AND the static MODAL_CSS block below so they cannot drift. Dark
-		* panel on a dark host, three text tiers (primary / section title / hint +
-		* muted), one border tone, a 12px panel / 8px control radius scale and a
-		* 4-unit spacing scale (4 / 8 / 12 / 16 / 20).
-		*/
-		const MODAL_BG = "rgba(20, 24, 32, 0.98)";
-		const MODAL_FG = "#e6e8ee";
-		const MODAL_TITLE = "#c7cede";
-		const MODAL_TEXT = "#b9c2d4";
-		const MODAL_HINT = "#8b96ab";
-		const MODAL_BORDER = "rgba(255, 255, 255, 0.14)";
-		const MODAL_TIP_BG = "#222834";
-		const MODAL_RADIUS_PANEL = 12;
-		const MODAL_RADIUS_CONTROL = 8;
 		/** Near-row description tip: how far its right edge sits from the row's right
 		* edge — clears the 32px switch + its 10px padding. */
 		const MODAL_TIP_RIGHT = 54;
@@ -2470,12 +2920,21 @@ window.__ModuleLoader__.load({
 [data-personal-toggle]:hover, [data-focus-toggle-settings]:hover { background: rgba(255, 255, 255, 0.05); }
 [data-focus-option]:hover { background: rgba(255, 255, 255, 0.04); }
 [data-toolbar-settings-close]:hover { background: rgba(255, 255, 255, 0.08); }
-[data-toolbar-settings-reset] { background: rgba(255, 255, 255, 0.06); }
-[data-toolbar-settings-reset]:hover { background: rgba(255, 255, 255, 0.1); }
+[data-toolbar-settings-reset], [data-onboarding-reopen] { background: rgba(255, 255, 255, 0.06); }
+[data-toolbar-settings-reset]:hover, [data-onboarding-reopen]:hover { background: rgba(255, 255, 255, 0.1); }
+/* BASE state reset: every modal surface must sit transparent on the dark
+   panel — without it the UA default button face (light gray) floods through
+   and rows become unreadable light-on-light. Hover washes above take over
+   on interaction. */
+[data-toolbar-pin-toggle], [data-personal-toggle], [data-focus-toggle-settings],
+[data-toolbar-settings-close], [data-focus-option] {
+  background: transparent;
+}
 /* ONE accent ring for keyboard focus on every modal control. */
 [data-toolbar-pin-toggle]:focus-visible, [data-personal-toggle]:focus-visible,
 [data-focus-toggle-settings]:focus-visible,
-[data-toolbar-settings-close]:focus-visible, [data-toolbar-settings-reset]:focus-visible {
+[data-toolbar-settings-close]:focus-visible, [data-toolbar-settings-reset]:focus-visible,
+[data-onboarding-reopen]:focus-visible {
   box-shadow: 0 0 0 2px var(--ms-accent-soft);
 }
 /* Near-row description tip: a rotated square peeks out of the LEFT edge so
@@ -2518,7 +2977,7 @@ window.__ModuleLoader__.load({
 			width: "100%",
 			padding: "8px 10px",
 			border: "none",
-			borderRadius: MODAL_RADIUS_CONTROL,
+			borderRadius: 8,
 			cursor: "pointer",
 			color: MODAL_TITLE,
 			fontSize: 13,
@@ -2551,6 +3010,9 @@ window.__ModuleLoader__.load({
 		/** B4 update-check: mount-time silent check delay (ms) — give the harness
 		* time to settle before hitting the registry. */
 		const UPDATE_CHECK_MOUNT_DELAY = 1500;
+		/** 0.6.5 first-run coach tour: mount-time show delay (ms) — let the rail settle
+		* before the first bubble pops. */
+		const ONBOARDING_MOUNT_DELAY = 800;
 		/** Initial state: no check has completed yet, nothing to show. */
 		const NO_UPDATE_CHECK = {
 			phase: "idle",
@@ -2778,6 +3240,8 @@ window.__ModuleLoader__.load({
 			const [expandHovered, setExpandHovered] = (0, react.useState)(false);
 			const [settingsHovered, setSettingsHovered] = (0, react.useState)(false);
 			const [settingsOpen, setSettingsOpen] = (0, react.useState)(false);
+			const [tourOpen, setTourOpen] = (0, react.useState)(false);
+			const [tourRun, setTourRun] = (0, react.useState)(0);
 			/** The feature whose near-row description tip is currently visible
 			* (`null` = none — tips only appear on hover/focus of their own row). */
 			const [descFeature, setDescFeature] = (0, react.useState)(null);
@@ -2857,6 +3321,12 @@ window.__ModuleLoader__.load({
 				const timer = window.setTimeout(runUpdateCheck, UPDATE_CHECK_MOUNT_DELAY);
 				return () => window.clearTimeout(timer);
 			}, []);
+			(0, react.useEffect)(() => {
+				const timer = window.setTimeout(() => {
+					if (!readOnboardedFlag()) setTourOpen(true);
+				}, ONBOARDING_MOUNT_DELAY);
+				return () => window.clearTimeout(timer);
+			}, []);
 			useOutsideDismiss(updatePanelRef, updateOpen, () => {
 				setUpdateOpen(false);
 				updateBtnRef.current?.focus();
@@ -3020,6 +3490,15 @@ window.__ModuleLoader__.load({
 				setSettingsOpen(false);
 				settingsBtnRef.current?.focus();
 			};
+			/** 0.6.5: settings → 重新查看教程 — close settings and replay the coach
+			* tour immediately (the flag may or may not be set; skipping/completing it
+			* re-persists the flag anyway). The `tourRun` bump remounts the tour so the
+			* replay always restarts from bubble 0. */
+			const reopenTour = () => {
+				setSettingsOpen(false);
+				setTourRun((n) => n + 1);
+				setTourOpen(true);
+			};
 			/** B1: a feature renders while the toolbar is EXPANDED or while it is pinned. */
 			const featureVisible = (id) => toolbarExpanded || pinned.includes(id);
 			/** Base chrome-button style: accent-defined active tint, scaled hit area. */
@@ -3503,9 +3982,9 @@ window.__ModuleLoader__.load({
 								maxHeight: "78vh",
 								overflowY: "auto",
 								padding: 20,
-								background: MODAL_BG,
-								color: MODAL_FG,
-								borderRadius: MODAL_RADIUS_PANEL,
+								background: "rgba(20, 24, 32, 0.98)",
+								color: "#e6e8ee",
+								borderRadius: 12,
 								boxShadow: "0 24px 64px rgba(0, 0, 0, 0.55)",
 								scrollbarWidth: "thin",
 								scrollbarColor: "rgba(255, 255, 255, 0.2) transparent"
@@ -3524,7 +4003,7 @@ window.__ModuleLoader__.load({
 										style: {
 											fontSize: 15,
 											fontWeight: 600,
-											color: MODAL_FG
+											color: "#e6e8ee"
 										},
 										children: t("settings.title")
 									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
@@ -3543,8 +4022,8 @@ window.__ModuleLoader__.load({
 											border: "none",
 											padding: 0,
 											cursor: "pointer",
-											color: MODAL_HINT,
-											borderRadius: MODAL_RADIUS_CONTROL,
+											color: "#8b96ab",
+											borderRadius: 8,
 											lineHeight: 1
 										},
 										children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("svg", {
@@ -3569,7 +4048,7 @@ window.__ModuleLoader__.load({
 											style: {
 												fontSize: 13,
 												fontWeight: 600,
-												color: MODAL_TITLE,
+												color: "#c7cede",
 												marginBottom: 4
 											},
 											children: t("settings.section.features")
@@ -3578,7 +4057,7 @@ window.__ModuleLoader__.load({
 											"data-settings-pin-hint": true,
 											style: {
 												fontSize: 12,
-												color: MODAL_HINT,
+												color: "#8b96ab",
 												lineHeight: 1.5,
 												marginBottom: 10
 											},
@@ -3619,9 +4098,9 @@ window.__ModuleLoader__.load({
 															width: "100%",
 															padding: "8px 10px",
 															border: "none",
-															borderRadius: MODAL_RADIUS_CONTROL,
+															borderRadius: 8,
 															cursor: "pointer",
-															color: MODAL_FG,
+															color: "#e6e8ee",
 															fontSize: 13,
 															textAlign: "left"
 														},
@@ -3667,11 +4146,11 @@ window.__ModuleLoader__.load({
 															maxWidth: "55%",
 															transform: `translateY(-50%) translateX(${active ? 0 : 4}px)`,
 															padding: "5px 10px",
-															borderRadius: MODAL_RADIUS_CONTROL,
-															background: MODAL_TIP_BG,
-															border: `1px solid ${MODAL_BORDER}`,
+															borderRadius: 8,
+															background: "#222834",
+															border: `1px solid rgba(255, 255, 255, 0.14)`,
 															boxShadow: "0 8px 24px rgba(0, 0, 0, 0.35)",
-															color: MODAL_TEXT,
+															color: "#b9c2d4",
 															fontSize: 12,
 															lineHeight: 1.45,
 															opacity: active ? 1 : 0,
@@ -3743,7 +4222,7 @@ window.__ModuleLoader__.load({
 												"data-settings-personal-hint": true,
 												style: {
 													fontSize: 12,
-													color: MODAL_HINT,
+													color: "#8b96ab",
 													lineHeight: 1.5,
 													padding: "0 6px"
 												},
@@ -3759,7 +4238,7 @@ window.__ModuleLoader__.load({
 												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 													style: {
 														fontSize: 12.5,
-														color: MODAL_HINT,
+														color: "#8b96ab",
 														width: 90,
 														flexShrink: 0
 													},
@@ -3797,7 +4276,7 @@ window.__ModuleLoader__.load({
 															alignItems: "center",
 															gap: 6,
 															fontSize: 12.5,
-															color: MODAL_TEXT,
+															color: "#b9c2d4",
 															cursor: "pointer"
 														},
 														children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
@@ -3828,7 +4307,7 @@ window.__ModuleLoader__.load({
 													/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 														style: {
 															fontSize: 12.5,
-															color: MODAL_HINT,
+															color: "#8b96ab",
 															width: 90,
 															flexShrink: 0
 														},
@@ -3852,7 +4331,7 @@ window.__ModuleLoader__.load({
 														"data-icon-size-value": true,
 														style: {
 															fontSize: 12.5,
-															color: MODAL_TEXT,
+															color: "#b9c2d4",
 															width: 40
 														},
 														children: [iconSize, "px"]
@@ -3870,7 +4349,7 @@ window.__ModuleLoader__.load({
 													/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 														style: {
 															fontSize: 12.5,
-															color: MODAL_HINT,
+															color: "#8b96ab",
 															width: 90,
 															flexShrink: 0
 														},
@@ -3894,7 +4373,7 @@ window.__ModuleLoader__.load({
 														"data-inset-value": true,
 														style: {
 															fontSize: 12.5,
-															color: MODAL_TEXT,
+															color: "#b9c2d4",
 															width: 40
 														},
 														children: [inset, "px"]
@@ -3914,7 +4393,7 @@ window.__ModuleLoader__.load({
 													/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 														style: {
 															fontSize: 12.5,
-															color: MODAL_HINT,
+															color: "#8b96ab",
 															width: 90,
 															flexShrink: 0
 														},
@@ -3926,7 +4405,7 @@ window.__ModuleLoader__.load({
 															alignItems: "center",
 															gap: 5,
 															fontSize: 13,
-															color: MODAL_FG,
+															color: "#e6e8ee",
 															cursor: "pointer"
 														},
 														children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
@@ -3944,7 +4423,7 @@ window.__ModuleLoader__.load({
 															alignItems: "center",
 															gap: 5,
 															fontSize: 13,
-															color: MODAL_FG,
+															color: "#e6e8ee",
 															cursor: "pointer"
 														},
 														children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
@@ -4014,7 +4493,7 @@ window.__ModuleLoader__.load({
 												"data-settings-focus-hint": true,
 												style: {
 													fontSize: 12,
-													color: MODAL_HINT,
+													color: "#8b96ab",
 													lineHeight: 1.5,
 													padding: "0 6px"
 												},
@@ -4027,9 +4506,9 @@ window.__ModuleLoader__.load({
 													alignItems: "center",
 													gap: 8,
 													padding: "6px 8px",
-													borderRadius: MODAL_RADIUS_CONTROL,
+													borderRadius: 8,
 													fontSize: 13,
-													color: MODAL_FG,
+													color: "#e6e8ee",
 													cursor: "pointer"
 												},
 												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
@@ -4046,9 +4525,9 @@ window.__ModuleLoader__.load({
 													alignItems: "center",
 													gap: 8,
 													padding: "6px 8px",
-													borderRadius: MODAL_RADIUS_CONTROL,
+													borderRadius: 8,
 													fontSize: 13,
-													color: MODAL_FG,
+													color: "#e6e8ee",
 													cursor: "pointer"
 												},
 												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
@@ -4065,9 +4544,9 @@ window.__ModuleLoader__.load({
 													alignItems: "center",
 													gap: 8,
 													padding: "6px 8px",
-													borderRadius: MODAL_RADIUS_CONTROL,
+													borderRadius: 8,
 													fontSize: 13,
-													color: MODAL_FG,
+													color: "#e6e8ee",
 													cursor: "pointer"
 												},
 												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
@@ -4088,7 +4567,7 @@ window.__ModuleLoader__.load({
 													/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 														style: {
 															fontSize: 12.5,
-															color: MODAL_HINT,
+															color: "#8b96ab",
 															width: 90,
 															flexShrink: 0
 														},
@@ -4112,7 +4591,7 @@ window.__ModuleLoader__.load({
 														"data-focus-opacity-value": true,
 														style: {
 															fontSize: 12.5,
-															color: MODAL_TEXT,
+															color: "#b9c2d4",
 															width: 44
 														},
 														children: [Math.round(prefs.focus.opacity * 100), "%"]
@@ -4131,7 +4610,7 @@ window.__ModuleLoader__.load({
 										style: {
 											fontSize: 13,
 											fontWeight: 600,
-											color: MODAL_TITLE,
+											color: "#c7cede",
 											marginBottom: 8
 										},
 										children: t("settings.language")
@@ -4154,7 +4633,7 @@ window.__ModuleLoader__.load({
 												alignItems: "center",
 												gap: 5,
 												fontSize: 13,
-												color: MODAL_FG,
+												color: "#e6e8ee",
 												cursor: "pointer"
 											},
 											children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
@@ -4174,7 +4653,7 @@ window.__ModuleLoader__.load({
 									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 										style: {
 											fontSize: 12,
-											color: MODAL_HINT,
+											color: "#8b96ab",
 											marginBottom: 10
 										},
 										children: t("settings.support")
@@ -4275,25 +4754,54 @@ window.__ModuleLoader__.load({
 										]
 									})]
 								}),
-								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-									type: "button",
-									"data-toolbar-settings-reset": true,
-									onClick: onResetAll,
+								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+									"data-toolbar-settings-actions": true,
 									style: {
-										display: "block",
-										margin: "16px auto 2px",
-										padding: "7px 16px",
-										border: `1px solid ${MODAL_BORDER}`,
-										borderRadius: MODAL_RADIUS_CONTROL,
-										cursor: "pointer",
-										color: MODAL_TEXT,
-										fontSize: 12.5
+										display: "flex",
+										alignItems: "center",
+										justifyContent: "center",
+										gap: 10,
+										margin: "16px auto 2px"
 									},
-									children: t("settings.reset")
+									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+										type: "button",
+										"data-toolbar-settings-reset": true,
+										onClick: onResetAll,
+										style: {
+											padding: "7px 16px",
+											border: `1px solid rgba(255, 255, 255, 0.14)`,
+											borderRadius: 8,
+											cursor: "pointer",
+											color: "#b9c2d4",
+											fontSize: 12.5
+										},
+										children: t("settings.reset")
+									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+										type: "button",
+										"data-onboarding-reopen": true,
+										onClick: reopenTour,
+										style: {
+											padding: "7px 16px",
+											border: `1px solid rgba(255, 255, 255, 0.14)`,
+											borderRadius: 8,
+											cursor: "pointer",
+											color: "#b9c2d4",
+											fontSize: 12.5
+										},
+										children: t("tour.reopen")
+									})]
 								})
 							]
 						})
 					}),
+					tourOpen && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(MilestoneTour, {
+						t,
+						side,
+						toolbarExpanded,
+						settingsOpen,
+						onSetToolbarExpanded: setToolbarExpanded,
+						onClose: () => setTourOpen(false)
+					}, tourRun),
 					updateOpen && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 						ref: updatePanelRef,
 						"data-update-panel": true,
@@ -4330,7 +4838,7 @@ window.__ModuleLoader__.load({
 								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
 									style: { color: "#8b96ab" },
 									children: [t("update.current"), ": "]
-								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: "0.6.3" })] }),
+								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: "0.6.5" })] }),
 								updateCheck.phase === "ok" && updateCheck.latest !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 									"data-update-latest": true,
 									children: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-milestone",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Git-style milestone timeline for DeepSeek Harness: hover for metadata, click to jump to any message. 会话里程碑导航条：圆点时间线，定位并跳转到每条提问。",
   "type": "module",
   "main": "lib/index.js",