dsh-milestone 0.6.3 → 0.6.4

package/lib/client.js

@@ -795,7 +795,73 @@ 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.4 onboarding: welcome title (also the tutorial dialog's aria-label). */
+			"onboarding.welcome.title": "欢迎使用 dsh-milestone",
+			/** 0.6.4 onboarding: one-line positioning statement on the welcome page. */
+			"onboarding.welcome.subtitle": "一条附着在会话侧边的里程碑导航：悬停圆点看元信息，点击跳到任意提问。",
+			/** 0.6.4 onboarding: primary action on the welcome page → step 1. */
+			"onboarding.start": "开始引导",
+			/** 0.6.4 onboarding: skip action — persists the flag and closes, on EVERY page. */
+			"onboarding.skip": "跳过",
+			/** 0.6.4 onboarding: step-page progress text `第 n / 4 步`. */
+			"onboarding.step.label": "第 {n} / 4 步",
+			/** 0.6.4 onboarding: aria-label on one progress dot. */
+			"onboarding.step.short": "第 {n} 步",
+			/** 0.6.4 onboarding: step-page back navigation. */
+			"onboarding.prev": "上一步",
+			/** 0.6.4 onboarding: step-page forward navigation (steps 1–3). */
+			"onboarding.next": "下一步",
+			/** 0.6.4 onboarding: step-4 primary action — persists the flag and closes. */
+			"onboarding.finish": "开始使用",
+			/** 0.6.4 onboarding: step 1 title — the dot timeline. */
+			"onboarding.step1.title": "圆点时间线",
+			/** 0.6.4 onboarding: step 1 line 1. */
+			"onboarding.step1.desc1": "每条提问在侧边对应一个圆点，自上而下按时间排列。",
+			/** 0.6.4 onboarding: step 1 line 2. */
+			"onboarding.step1.desc2": "悬停圆点，查看该轮元信息（用时、首字、模型与 Token）。",
+			/** 0.6.4 onboarding: step 1 line 3. */
+			"onboarding.step1.desc3": "点击任意圆点，会话立即跳到那条提问。",
+			/** 0.6.4 onboarding: step 2 title — in-rail search & bookmarks. */
+			"onboarding.step2.title": "搜索与收藏",
+			/** 0.6.4 onboarding: step 2 line 1. */
+			"onboarding.step2.desc1": "输入关键词过滤圆点，只点亮匹配项并显示 N / M 计数；Enter 逐个跳转，Esc 关闭。",
+			/** 0.6.4 onboarding: step 2 line 2. */
+			"onboarding.step2.desc2": "星标收藏重要消息，再用「只看收藏」一键过滤。",
+			/** 0.6.4 onboarding: step 3 title — personalization & settings. */
+			"onboarding.step3.title": "个性化与设置",
+			/** 0.6.4 onboarding: step 3 line 1. */
+			"onboarding.step3.desc1": "调整强调色、圆点大小、距边距离与左右位置，即调即存。",
+			/** 0.6.4 onboarding: step 3 line 2. */
+			"onboarding.step3.desc2": "切换界面语言、搭配「聚焦」效果，或把常用功能 pin 在折叠外。",
+			/** 0.6.4 onboarding: step 4 title — update detection & support. */
+			"onboarding.step4.title": "更新检测与支持",
+			/** 0.6.4 onboarding: step 4 line 1. */
+			"onboarding.step4.desc1": "挂载后自动检查 npm 新版本；有新版本时工具栏会亮起提示。",
+			/** 0.6.4 onboarding: step 4 line 2. */
+			"onboarding.step4.desc2": "喜欢这个插件？欢迎 Star、提交 Issue，或通过 npm 安装升级。",
+			/** 0.6.4 onboarding demo: fake message 1 (step 1 dots / step 2 corpus). */
+			"onboarding.demo.m1": "帮我优化这段代码",
+			/** 0.6.4 onboarding demo: fake message 2. */
+			"onboarding.demo.m2": "解释这个报错",
+			/** 0.6.4 onboarding demo: fake message 3. */
+			"onboarding.demo.m3": "再检查边界条件",
+			/** 0.6.4 onboarding demo: fake message 4. */
+			"onboarding.demo.m4": "写个单元测试",
+			/** 0.6.4 onboarding demo: fake message 5. */
+			"onboarding.demo.m5": "总结一下方案",
+			/** 0.6.4 onboarding demo (step 1): hint under the toy dot rail. */
+			"onboarding.demo.hoverHint": "试试悬停与点击圆点",
+			/** 0.6.4 onboarding demo (step 2): hint under the toy search/favorite. */
+			"onboarding.demo.searchHint": "试试输入「报错」，或点星标切换只看收藏",
+			/** 0.6.4 onboarding demo (step 3): the 展开箭头 → 齿轮 → 设置 path hint. */
+			"onboarding.demo.settingsPath": "展开箭头 → 齿轮 → 设置",
+			/** 0.6.4 onboarding demo (step 3): legend label for the focus mix. */
+			"onboarding.demo.focusMix": "聚焦搭配",
+			/** 0.6.4 onboarding demo (step 3): legend label for pinning features. */
+			"onboarding.demo.pin": "pin 固定",
+			/** 0.6.4 settings footer action: replay the tutorial. */
+			"onboarding.reopen": "重新查看教程"
 		};
 		const en = {
 			"jump.to": "Jump to message {n}",
@@ -900,7 +966,40 @@ window.__ModuleLoader__.load({
 			"settings.language": "Language",
 			"settings.lang.system": "Follow system",
 			"settings.lang.zh": "Chinese",
-			"settings.lang.en": "English"
+			"settings.lang.en": "English",
+			"onboarding.welcome.title": "Welcome to dsh-milestone",
+			"onboarding.welcome.subtitle": "A milestone rail beside your conversation: hover a dot for metadata, click any dot to jump.",
+			"onboarding.start": "Start the tour",
+			"onboarding.skip": "Skip",
+			"onboarding.step.label": "Step {n} of 4",
+			"onboarding.step.short": "Step {n}",
+			"onboarding.prev": "Back",
+			"onboarding.next": "Next",
+			"onboarding.finish": "Get started",
+			"onboarding.step1.title": "The dot timeline",
+			"onboarding.step1.desc1": "Every prompt is a dot on the side rail, listed top to bottom in time order.",
+			"onboarding.step1.desc2": "Hover a dot to see that turn’s metadata (duration, first token, model, tokens).",
+			"onboarding.step1.desc3": "Click any dot to jump the conversation straight to that prompt.",
+			"onboarding.step2.title": "Search & bookmarks",
+			"onboarding.step2.desc1": "Type to filter the dots — matches light up with an N / M counter; Enter jumps, Esc closes.",
+			"onboarding.step2.desc2": "Star a message to bookmark it, then use “Bookmarks only” to filter.",
+			"onboarding.step3.title": "Personalize & settings",
+			"onboarding.step3.desc1": "Tune the accent color, dot size, edge distance, and left/right side — saved as you adjust.",
+			"onboarding.step3.desc2": "Switch the UI language, compose your focus effect, or pin features outside the collapse.",
+			"onboarding.step4.title": "Updates & support",
+			"onboarding.step4.desc1": "A silent check runs after mount; when a new version exists, the toolbar shows a hint.",
+			"onboarding.step4.desc2": "Enjoying the plugin? Star us, file an issue, or upgrade via npm.",
+			"onboarding.demo.m1": "Help me optimize this code",
+			"onboarding.demo.m2": "Explain this error",
+			"onboarding.demo.m3": "Check the edge cases again",
+			"onboarding.demo.m4": "Write a unit test",
+			"onboarding.demo.m5": "Summarize the plan",
+			"onboarding.demo.hoverHint": "Try hovering and clicking the dots",
+			"onboarding.demo.searchHint": "Try typing “error”, or tap the star for bookmarks-only",
+			"onboarding.demo.settingsPath": "Expand arrow → gear → Settings",
+			"onboarding.demo.focusMix": "Focus mix",
+			"onboarding.demo.pin": "Pin keys",
+			"onboarding.reopen": "Replay the tour"
 		};
 		/**
 		* Interpolate `{name}` placeholders with params, matching the harness t seat's
@@ -1329,6 +1428,950 @@ window.__ModuleLoader__.load({
 			});
 		}
 		//#endregion
+		//#region src/client/modal-tokens.ts
+		/**
+		* modal-tokens: the ONE source for the settings modal's dark-panel palette and
+		* radius scale, shared with the 0.6.4 onboarding tutorial modal so the two
+		* dialogs cannot drift (same dark panel on a dark host, same three text tiers,
+		* same 12px panel / 8px control radius, same border tone).
+		*
+		* The static MODAL_CSS block (hover/focus-visible/reduced-motion rules) stays
+		* in MilestoneRail.tsx because it also styles the settings modal's own chrome
+		* (`[data-support-card]`, `[data-toolbar-*]`, ...); the onboarding modal
+		* carries its own small ONBOARDING_CSS block for its own controls, built from
+		* these same tokens. MilestoneRail.tsx imports these constants verbatim so a
+		* future palette change edits exactly one file.
+		*/
+		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";
+		//#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/version-meta.ts
+		/**
+		* 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.4";
+		/** Main repository of dsh-milestone (as referenced by README.md). */
+		const PLUGIN_REPO_URL = "https://github.com/SnowCrescenter-tech/dsh-milestone";
+		/** npm package page (install channel promoted in the settings menu). */
+		const PLUGIN_NPM_URL = "https://www.npmjs.com/package/dsh-milestone";
+		//#endregion
+		//#region src/client/MilestoneOnboarding.tsx
+		/**
+		* MilestoneOnboarding: the 0.6.4 first-run tutorial modal.
+		*
+		* Trigger/ownership lives in MilestoneRail (mount timer + settings reopen);
+		* this component is a fully SELF-CONTAINED dialog: it carries the welcome
+		* page, the 4 step pages with built-in toy demos, step progress, and the
+		* close paths (skip / finish / Escape), and it persists the
+		* `dsh-milestone.onboarded` flag itself via onboarding-store.
+		*
+		* Visual language is copied from the settings modal (MilestoneRail's
+		* MODAL_CSS): dark `rgba(20, 24, 32, 0.98)` panel, three text tiers, 12px
+		* panel / 8px control radii, one accent (inherited through the rail root's
+		* `--ms-accent*` CSS variables), and a small ONBOARDING_CSS block for the
+		* hover / :focus-visible / reduced-motion rules inline styles cannot express.
+		*
+		* Deliberate non-features:
+		*   - NO outside-pointerdown dismissal (a misclick must never swallow the
+		*     tutorial — the requirement explicitly keeps it off).
+		*   - Escape ALWAYS means "skip": it persists the flag and closes.
+		*   - The flag is written on IMPRESSION (the welcome page showing is enough);
+		*     skip / finish / Escape re-assert it. A mid-tour refresh/crash never
+		*     re-pops — replay lives in settings 重新查看教程.
+		*/
+		/** Step-page count — the progress indicator shape. */
+		const STEP_COUNT = [
+			1,
+			2,
+			3,
+			4
+		];
+		/** The onboarding modal floats above every other rail layer (settings 105). */
+		const ONBOARDING_Z = 110;
+		/** Fake messages the step-1/step-2 demos run on (zh AND en keys exist). */
+		const DEMO_MESSAGE_KEYS = [
+			"onboarding.demo.m1",
+			"onboarding.demo.m2",
+			"onboarding.demo.m3",
+			"onboarding.demo.m4",
+			"onboarding.demo.m5"
+		];
+		/** Fake per-turn durations for the step-1 hover tooltip (unit text is locale-neutral). */
+		const DEMO_DURATIONS = [
+			"6.2s",
+			"13.4s",
+			"5.1s",
+			"22.0s",
+			"9.8s"
+		];
+		/**
+		* Static onboarding-modal styling that needs `:hover`/`:focus-visible`
+		* (inline styles cannot express them): one accent focus ring for every
+		* control, hover washes, the demo-link micro-lift, the panel fade-in, and the
+		* reduced-motion kill — mirrors the settings MODAL_CSS pattern. Accent values
+		* come from the rail root's CSS variables (`--ms-accent*`), inherited into
+		* this fixed layer because the overlay renders inside the rail root.
+		*/
+		const ONBOARDING_CSS = `
+@keyframes ms-onboarding-fade { from { opacity: 0; transform: translateY(-2px); } to { opacity: 1; transform: none; } }
+[data-onboarding-panel] { animation: ms-onboarding-fade 160ms ease; }
+[data-onboarding-skip]:hover { background: rgba(255, 255, 255, 0.08); }
+[data-onboarding-prev]:hover, [data-onboarding-next]:hover, [data-onboarding-start]:hover, [data-onboarding-finish]:hover { background: rgba(255, 255, 255, 0.1); }
+[data-onboarding-skip]:focus-visible, [data-onboarding-prev]:focus-visible,
+[data-onboarding-next]:focus-visible, [data-onboarding-start]:focus-visible,
+[data-onboarding-finish]:focus-visible, [data-demo-star]:focus-visible,
+[data-demo-dot]:focus-visible, [data-demo-search-input]:focus-visible {
+  box-shadow: 0 0 0 2px var(--ms-accent-soft);
+}
+[data-demo-link] { transition: transform 120ms ease, border-color 120ms ease, background 120ms ease; }
+[data-demo-link]:hover { transform: translateY(-2px); border-color: var(--ms-accent); background: rgba(255, 255, 255, 0.09); }
+@media (prefers-reduced-motion: reduce) {
+  [data-onboarding-panel] { animation: none; }
+  [data-onboarding-skip], [data-onboarding-prev], [data-onboarding-next],
+  [data-onboarding-start], [data-onboarding-finish], [data-demo-link] { transition: none; }
+}
+`;
+		/** Primary (accent) dialog action — start / next / finish. */
+		const PRIMARY_BUTTON = {
+			background: "var(--ms-accent-bg)",
+			color: "var(--ms-accent-soft)",
+			border: "1px solid var(--ms-accent)",
+			borderRadius: 8,
+			padding: "7px 18px",
+			fontSize: 13,
+			fontWeight: 600,
+			cursor: "pointer"
+		};
+		/** Secondary dialog action — back / welcome skip. */
+		const GHOST_BUTTON = {
+			background: "rgba(255, 255, 255, 0.06)",
+			color: MODAL_TEXT,
+			border: `1px solid ${MODAL_BORDER}`,
+			borderRadius: 8,
+			padding: "7px 16px",
+			fontSize: 12.5,
+			cursor: "pointer"
+		};
+		/** Corner skip (step pages) — the quietest of the three button tiers. */
+		const SKIP_BUTTON = {
+			background: "transparent",
+			color: MODAL_HINT,
+			border: "none",
+			padding: "4px 8px",
+			borderRadius: 8,
+			fontSize: 12,
+			cursor: "pointer"
+		};
+		/** Resolve the five fake demo messages through the active locale. */
+		function demoMessages(t) {
+			return DEMO_MESSAGE_KEYS.map((key) => t(key));
+		}
+		/**
+		* Step-1 demo: a toy dot rail with the REAL dot visual — accent gradient dots,
+		* hover enlarges + shows a fake metadata tooltip (position + duration), click
+		* marks the dot with the white ring. All local state; nothing touches real
+		* session data.
+		*/
+		function DemoDotRail({ t, accent }) {
+			const messages = demoMessages(t);
+			const [hoverIndex, setHoverIndex] = (0, react.useState)(null);
+			const [activeIndex, setActiveIndex] = (0, react.useState)(null);
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				"data-demo-dots": true,
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						"data-demo-dot-row": true,
+						style: {
+							display: "flex",
+							alignItems: "center",
+							justifyContent: "center",
+							gap: 22
+						},
+						children: messages.map((msg, i) => {
+							const hovered = hoverIndex === i;
+							const active = activeIndex === i;
+							return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								"data-demo-dot": i,
+								"data-active": active ? "true" : void 0,
+								"aria-label": msg,
+								"aria-pressed": active,
+								onMouseEnter: () => setHoverIndex(i),
+								onMouseLeave: () => setHoverIndex(null),
+								onFocus: () => setHoverIndex(i),
+								onBlur: () => setHoverIndex(null),
+								onClick: () => setActiveIndex(i),
+								style: {
+									width: 36,
+									height: 36,
+									display: "flex",
+									alignItems: "center",
+									justifyContent: "center",
+									background: "transparent",
+									border: "none",
+									padding: 0,
+									cursor: "pointer",
+									borderRadius: "50%"
+								},
+								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { style: {
+									width: 13,
+									height: 13,
+									borderRadius: "50%",
+									background: dotColor(i, messages.length, accent),
+									boxShadow: active ? "0 0 0 3px rgba(255, 255, 255, 0.9)" : hovered ? "0 0 0 3px rgba(255, 255, 255, 0.35)" : "none",
+									transform: hovered || active ? "scale(1.35)" : "scale(1)",
+									transition: "transform 120ms ease, box-shadow 120ms ease"
+								} })
+							}, msg);
+						})
+					}),
+					hoverIndex !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						"data-demo-tooltip": true,
+						style: {
+							marginTop: 8,
+							textAlign: "center",
+							fontSize: 12,
+							color: "#b9c2d4",
+							lineHeight: 1.5
+						},
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: t("pos.of", {
+								n: hoverIndex + 1,
+								m: messages.length
+							}) }),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: " · " }),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: t("duration.label", { name: DEMO_DURATIONS[hoverIndex] }) })
+						]
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						"data-demo-hint": true,
+						style: {
+							marginTop: 8,
+							textAlign: "center",
+							fontSize: 12,
+							color: MODAL_HINT
+						},
+						children: t("onboarding.demo.hoverHint")
+					})
+				]
+			});
+		}
+		/**
+		* Step-2 demo: a toy search box that filters the demo messages (N / M count)
+		* plus one bookmark star — active = solid star + "bookmarks only" row list.
+		* Local state only; the real rail/search/bookmarks are untouched.
+		*/
+		function DemoSearch({ t, accent }) {
+			const messages = demoMessages(t);
+			const starIndex = 1;
+			const [query, setQuery] = (0, react.useState)("");
+			const [favOnly, setFavOnly] = (0, react.useState)(false);
+			const lower = query.trim().toLowerCase();
+			const visible = favOnly ? messages.filter((_, i) => i === starIndex) : messages;
+			const matches = lower === "" ? visible.length : visible.filter((m) => m.toLowerCase().includes(lower)).length;
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				"data-demo-search": true,
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						style: {
+							display: "flex",
+							alignItems: "center",
+							gap: 8
+						},
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+								"data-demo-search-input": true,
+								type: "text",
+								value: query,
+								onChange: (e) => setQuery(e.target.value),
+								placeholder: t("search.placeholder"),
+								"aria-label": t("search.label"),
+								style: {
+									flex: 1,
+									minWidth: 0,
+									padding: "6px 10px",
+									borderRadius: 8,
+									border: `1px solid ${MODAL_BORDER}`,
+									background: "rgba(255, 255, 255, 0.05)",
+									color: MODAL_FG,
+									fontSize: 12.5,
+									outline: "none"
+								}
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+								"data-demo-search-count": true,
+								style: {
+									fontSize: 12,
+									color: MODAL_TEXT,
+									whiteSpace: "nowrap"
+								},
+								children: [
+									matches,
+									" / ",
+									visible.length
+								]
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								"data-demo-star": true,
+								"aria-pressed": favOnly,
+								"aria-label": t("bookmark.filter"),
+								title: t("bookmark.filter"),
+								onClick: () => setFavOnly((v) => !v),
+								style: {
+									width: 30,
+									height: 30,
+									flexShrink: 0,
+									display: "flex",
+									alignItems: "center",
+									justifyContent: "center",
+									background: favOnly ? "var(--ms-accent-bg)" : "transparent",
+									border: `1px solid ${MODAL_BORDER}`,
+									borderRadius: 8,
+									padding: 0,
+									cursor: "pointer",
+									color: favOnly ? "var(--ms-accent-soft)" : MODAL_HINT
+								},
+								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("svg", {
+									width: "14",
+									height: "14",
+									viewBox: "0 0 24 24",
+									fill: favOnly ? "currentColor" : "none",
+									stroke: "currentColor",
+									strokeWidth: "2",
+									strokeLinejoin: "round",
+									"aria-hidden": "true",
+									children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "m12 2 3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z" })
+								})
+							})
+						]
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						"data-demo-search-rows": true,
+						style: {
+							display: "flex",
+							flexDirection: "column",
+							gap: 6,
+							marginTop: 10
+						},
+						children: visible.map((msg, i) => {
+							const realIndex = favOnly ? starIndex : i;
+							const lit = lower === "" || msg.toLowerCase().includes(lower);
+							return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								"data-demo-search-row": true,
+								"data-index": realIndex,
+								"data-lit": lit ? "true" : "false",
+								style: {
+									display: "flex",
+									alignItems: "center",
+									gap: 8,
+									fontSize: 12,
+									color: lit ? MODAL_FG : MODAL_HINT,
+									opacity: lit ? 1 : .45,
+									transition: "opacity 120ms ease"
+								},
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									"aria-hidden": "true",
+									style: {
+										width: 8,
+										height: 8,
+										flexShrink: 0,
+										borderRadius: "50%",
+										background: dotColor(realIndex, messages.length, accent)
+									}
+								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: msg })]
+							}, msg);
+						})
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						"data-demo-search-hint": true,
+						style: {
+							marginTop: 8,
+							textAlign: "center",
+							fontSize: 12,
+							color: MODAL_HINT
+						},
+						children: t("onboarding.demo.searchHint")
+					})
+				]
+			});
+		}
+		/**
+		* Step-3 demo: a static legend of the personalization controls (accent / size /
+		* distance / side / language / focus mix / pin), each with a tiny aria-hidden
+		* visual, plus the 展开箭头 → 齿轮 → 设置 path hint.
+		*/
+		function DemoSettings({ t, accent }) {
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				"data-demo-settings": true,
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					style: {
+						display: "flex",
+						flexDirection: "column",
+						gap: 6
+					},
+					children: [
+						{
+							label: t("settings.accent"),
+							visual: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								"aria-hidden": "true",
+								style: {
+									width: 10,
+									height: 10,
+									borderRadius: "50%",
+									background: accent
+								}
+							})
+						},
+						{
+							label: t("settings.iconSize"),
+							visual: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+								"aria-hidden": "true",
+								style: {
+									display: "flex",
+									alignItems: "flex-end",
+									gap: 2
+								},
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { style: {
+									width: 7,
+									height: 7,
+									borderRadius: "50%",
+									background: MODAL_HINT
+								} }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { style: {
+									width: 12,
+									height: 12,
+									borderRadius: "50%",
+									background: MODAL_TEXT
+								} })]
+							})
+						},
+						{
+							label: t("settings.inset"),
+							visual: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								"aria-hidden": "true",
+								style: {
+									width: 12,
+									height: 12,
+									border: `1px solid ${MODAL_BORDER}`,
+									borderRadius: 2
+								}
+							})
+						},
+						{
+							label: t("settings.side"),
+							visual: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								"aria-hidden": "true",
+								style: {
+									fontSize: 14,
+									color: MODAL_TEXT
+								},
+								children: "⇄"
+							})
+						},
+						{
+							label: t("settings.language"),
+							visual: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								"aria-hidden": "true",
+								style: {
+									fontSize: 11,
+									color: MODAL_TEXT
+								},
+								children: "中 / EN"
+							})
+						},
+						{
+							label: t("onboarding.demo.focusMix"),
+							visual: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("svg", {
+								"aria-hidden": "true",
+								width: "14",
+								height: "10",
+								viewBox: "0 0 24 24",
+								fill: "none",
+								stroke: "currentColor",
+								strokeWidth: "2.5",
+								strokeLinecap: "round",
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7z" }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("circle", {
+									cx: "12",
+									cy: "12",
+									r: "3"
+								})]
+							})
+						},
+						{
+							label: t("onboarding.demo.pin"),
+							visual: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("svg", {
+								"aria-hidden": "true",
+								width: "12",
+								height: "14",
+								viewBox: "0 0 24 24",
+								fill: "none",
+								stroke: "currentColor",
+								strokeWidth: "2",
+								strokeLinecap: "round",
+								strokeLinejoin: "round",
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "M12 21v-4" }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "M7 4h10l-1.2 6.5a4.6 4.6 0 0 1-7.6 0z" })]
+							})
+						}
+					].map((row) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						"data-demo-legend-row": true,
+						style: {
+							display: "flex",
+							alignItems: "center",
+							gap: 10,
+							fontSize: 12.5,
+							color: MODAL_TEXT
+						},
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							style: {
+								width: 56,
+								flexShrink: 0,
+								display: "flex",
+								justifyContent: "center"
+							},
+							children: row.visual
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: row.label })]
+					}, row.label))
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					"data-demo-settings-path": true,
+					style: {
+						marginTop: 10,
+						textAlign: "center",
+						fontSize: 12,
+						color: MODAL_HINT
+					},
+					children: t("onboarding.demo.settingsPath")
+				})]
+			});
+		}
+		/** Step-4 demo: update-check pill + the four support links (repo/star/issues/npm). */
+		function DemoSupport({ t }) {
+			const linkStyle = {
+				display: "flex",
+				alignItems: "center",
+				justifyContent: "center",
+				padding: "7px 6px",
+				borderRadius: 8,
+				background: "rgba(255, 255, 255, 0.05)",
+				border: `1px solid ${MODAL_BORDER}`,
+				color: MODAL_TITLE,
+				fontSize: 11.5,
+				textDecoration: "none",
+				textAlign: "center",
+				lineHeight: 1.35
+			};
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				"data-demo-support": true,
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					"data-demo-update-pill": true,
+					style: {
+						display: "inline-flex",
+						alignItems: "center",
+						gap: 6,
+						padding: "4px 10px",
+						borderRadius: 999,
+						background: "rgba(255, 255, 255, 0.06)",
+						border: `1px solid ${MODAL_BORDER}`,
+						color: MODAL_TEXT,
+						fontSize: 12
+					},
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+						"aria-hidden": "true",
+						style: {
+							width: 6,
+							height: 6,
+							borderRadius: "50%",
+							background: "var(--ms-accent)"
+						}
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", { children: [
+						t("update.title"),
+						" · v",
+						PLUGIN_VERSION
+					] })]
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					"data-demo-links": true,
+					style: {
+						display: "grid",
+						gridTemplateColumns: "repeat(4, minmax(0, 1fr))",
+						gap: 8,
+						marginTop: 12
+					},
+					children: [
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
+							href: PLUGIN_REPO_URL,
+							target: "_blank",
+							rel: "noreferrer",
+							"data-demo-link": true,
+							"data-link": "repo",
+							style: linkStyle,
+							children: t("settings.repo")
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
+							href: PLUGIN_REPO_URL,
+							target: "_blank",
+							rel: "noreferrer",
+							"data-demo-link": true,
+							"data-link": "star",
+							style: linkStyle,
+							children: t("settings.star")
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
+							href: `${PLUGIN_REPO_URL}/issues`,
+							target: "_blank",
+							rel: "noreferrer",
+							"data-demo-link": true,
+							"data-link": "issues",
+							style: linkStyle,
+							children: t("settings.issues")
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
+							href: PLUGIN_NPM_URL,
+							target: "_blank",
+							rel: "noreferrer",
+							"data-demo-link": true,
+							"data-link": "npm",
+							style: linkStyle,
+							children: t("settings.npm")
+						})
+					]
+				})]
+			});
+		}
+		/**
+		* The tutorial dialog. `step` 0 = welcome; 1–4 = the step pages.
+		*
+		* Impressions persist: the moment the dialog mounts (welcome shown), the
+		* onboarded flag is written — closing mid-tour via refresh/crash/navigation
+		* never re-pops (ROADMAP 0.6.4: 印象即持久化). Every explicit close path
+		* (skip anywhere, finish, Escape) re-asserts the same `'1'` and then lets the
+		* parent unmount the modal.
+		*/
+		function MilestoneOnboarding({ t, accent, onClose }) {
+			const [step, setStep] = (0, react.useState)(0);
+			const panelRef = (0, react.useRef)(null);
+			(0, react.useEffect)(() => {
+				writeOnboardedFlag();
+			}, []);
+			/** Skip / finish / Escape converge here: persist, then close. */
+			const finish = (0, react.useCallback)(() => {
+				writeOnboardedFlag();
+				onClose();
+			}, [onClose]);
+			(0, react.useEffect)(() => {
+				const onKey = (e) => {
+					if (e.key !== "Escape") return;
+					finish();
+				};
+				window.addEventListener("keydown", onKey);
+				return () => window.removeEventListener("keydown", onKey);
+			}, [finish]);
+			(0, react.useEffect)(() => {
+				panelRef.current?.querySelector("[data-onboarding-start], [data-onboarding-next], [data-onboarding-finish]")?.focus();
+			}, [step]);
+			const goNext = () => setStep((s) => Math.min(4, s + 1));
+			const goPrev = () => setStep((s) => Math.max(1, s - 1));
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				"data-onboarding-overlay": true,
+				style: {
+					position: "fixed",
+					inset: 0,
+					background: "rgba(8, 10, 15, 0.55)",
+					zIndex: ONBOARDING_Z,
+					display: "flex",
+					alignItems: "center",
+					justifyContent: "center",
+					padding: 16
+				},
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					ref: panelRef,
+					"data-onboarding-panel": true,
+					role: "dialog",
+					"aria-modal": "true",
+					"aria-label": t("onboarding.welcome.title"),
+					onClick: (e) => e.stopPropagation(),
+					style: {
+						width: "min(560px, 92vw)",
+						maxHeight: "80vh",
+						overflowY: "auto",
+						padding: 20,
+						background: MODAL_BG,
+						color: MODAL_FG,
+						borderRadius: 12,
+						boxShadow: "0 24px 64px rgba(0, 0, 0, 0.55)",
+						scrollbarWidth: "thin",
+						scrollbarColor: "rgba(255, 255, 255, 0.2) transparent"
+					},
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("style", { children: ONBOARDING_CSS }), step === 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						"data-onboarding-welcome": true,
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+								"data-onboarding-welcome-title": true,
+								style: {
+									fontSize: 17,
+									fontWeight: 700,
+									color: MODAL_FG
+								},
+								children: t("onboarding.welcome.title")
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+								"data-onboarding-welcome-subtitle": true,
+								style: {
+									marginTop: 8,
+									fontSize: 13,
+									lineHeight: 1.65,
+									color: MODAL_TEXT
+								},
+								children: t("onboarding.welcome.subtitle")
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								"data-onboarding-welcome-actions": true,
+								style: {
+									display: "flex",
+									justifyContent: "center",
+									gap: 10,
+									marginTop: 18
+								},
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+									type: "button",
+									"data-onboarding-start": true,
+									onClick: () => setStep(1),
+									style: PRIMARY_BUTTON,
+									children: t("onboarding.start")
+								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+									type: "button",
+									"data-onboarding-skip": true,
+									onClick: finish,
+									style: GHOST_BUTTON,
+									children: t("onboarding.skip")
+								})]
+							})
+						]
+					}) : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						"data-onboarding-step": true,
+						"data-step": step,
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								style: {
+									display: "flex",
+									alignItems: "flex-start",
+									justifyContent: "space-between",
+									gap: 10
+								},
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+									"data-onboarding-step-title": true,
+									style: {
+										fontSize: 15,
+										fontWeight: 600,
+										color: MODAL_FG
+									},
+									children: [
+										step === 1 && t("onboarding.step1.title"),
+										step === 2 && t("onboarding.step2.title"),
+										step === 3 && t("onboarding.step3.title"),
+										step === 4 && t("onboarding.step4.title")
+									]
+								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+									type: "button",
+									"data-onboarding-skip": true,
+									onClick: finish,
+									style: SKIP_BUTTON,
+									children: t("onboarding.skip")
+								})]
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								style: {
+									display: "flex",
+									flexDirection: "column",
+									gap: 6,
+									marginTop: 10
+								},
+								children: [
+									step === 1 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
+										/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+											"data-onboarding-step-desc": true,
+											"data-desc": "1",
+											children: t("onboarding.step1.desc1")
+										}),
+										/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+											"data-onboarding-step-desc": true,
+											"data-desc": "2",
+											children: t("onboarding.step1.desc2")
+										}),
+										/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+											"data-onboarding-step-desc": true,
+											"data-desc": "3",
+											children: t("onboarding.step1.desc3")
+										})
+									] }),
+									step === 2 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+										"data-onboarding-step-desc": true,
+										"data-desc": "1",
+										children: t("onboarding.step2.desc1")
+									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+										"data-onboarding-step-desc": true,
+										"data-desc": "2",
+										children: t("onboarding.step2.desc2")
+									})] }),
+									step === 3 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+										"data-onboarding-step-desc": true,
+										"data-desc": "1",
+										children: t("onboarding.step3.desc1")
+									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+										"data-onboarding-step-desc": true,
+										"data-desc": "2",
+										children: t("onboarding.step3.desc2")
+									})] }),
+									step === 4 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+										"data-onboarding-step-desc": true,
+										"data-desc": "1",
+										children: t("onboarding.step4.desc1")
+									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+										"data-onboarding-step-desc": true,
+										"data-desc": "2",
+										children: t("onboarding.step4.desc2")
+									})] })
+								]
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								"data-onboarding-demo": true,
+								style: {
+									marginTop: 14,
+									padding: 12,
+									borderRadius: 8,
+									background: MODAL_TIP_BG,
+									border: `1px solid ${MODAL_BORDER}`
+								},
+								children: [
+									step === 1 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(DemoDotRail, {
+										t,
+										accent
+									}),
+									step === 2 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(DemoSearch, {
+										t,
+										accent
+									}),
+									step === 3 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(DemoSettings, {
+										t,
+										accent
+									}),
+									step === 4 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(DemoSupport, { t })
+								]
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("footer", {
+								style: {
+									display: "flex",
+									alignItems: "center",
+									justifyContent: "space-between",
+									gap: 12,
+									marginTop: 16
+								},
+								children: [
+									/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+										type: "button",
+										"data-onboarding-prev": true,
+										onClick: goPrev,
+										disabled: step === 1,
+										style: GHOST_BUTTON,
+										children: t("onboarding.prev")
+									}),
+									/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+										style: {
+											display: "flex",
+											flexDirection: "column",
+											alignItems: "center",
+											gap: 6
+										},
+										children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+											"data-onboarding-progress": true,
+											style: {
+												fontSize: 12,
+												color: MODAL_HINT
+											},
+											children: t("onboarding.step.label", { n: step })
+										}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+											style: {
+												display: "flex",
+												gap: 5
+											},
+											children: STEP_COUNT.map((n) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+												"data-onboarding-progress-dot": true,
+												"data-active": step === n ? "true" : void 0,
+												"aria-label": t("onboarding.step.short", { n }),
+												"aria-current": step === n ? "step" : void 0,
+												style: {
+													width: 16,
+													height: 4,
+													borderRadius: 2,
+													background: step === n ? "var(--ms-accent)" : "rgba(255, 255, 255, 0.18)",
+													transition: "background 120ms ease, width 120ms ease"
+												}
+											}, n))
+										})]
+									}),
+									step < 4 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+										type: "button",
+										"data-onboarding-next": true,
+										onClick: goNext,
+										style: PRIMARY_BUTTON,
+										children: t("onboarding.next")
+									}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+										type: "button",
+										"data-onboarding-finish": true,
+										onClick: finish,
+										style: PRIMARY_BUTTON,
+										children: t("onboarding.finish")
+									})
+								]
+							})
+						]
+					})]
+				})
+			});
+		}
+		//#endregion
 		//#region src/client/MilestoneRailTooltip.tsx
 		/**
 		* @param props - the hovered mark + bookmark wiring (see {@link MilestoneRailTooltipProps}).
@@ -2274,13 +3317,6 @@ window.__ModuleLoader__.load({
 			return fresh;
 		}
 		//#endregion
-		//#region src/client/version-meta.ts
-		/**
-		* 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";
-		//#endregion
 		//#region src/client/MilestoneRail.tsx
 		/**
 		* MilestoneRail: the milestone.rail entry (session scope). Renders a fixed
@@ -2324,6 +3360,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 +3465,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 +3497,13 @@ 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); }
 /* 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 +3546,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 +3579,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.4 first-run tutorial: mount-time show delay (ms) — let the rail settle
+		* before the onboarding modal pops. */
+		const ONBOARDING_MOUNT_DELAY = 800;
 		/** Initial state: no check has completed yet, nothing to show. */
 		const NO_UPDATE_CHECK = {
 			phase: "idle",
@@ -2778,6 +3809,7 @@ 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 [onboardingOpen, setOnboardingOpen] = (0, react.useState)(false);
 			/** 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 +3889,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()) setOnboardingOpen(true);
+				}, ONBOARDING_MOUNT_DELAY);
+				return () => window.clearTimeout(timer);
+			}, []);
 			useOutsideDismiss(updatePanelRef, updateOpen, () => {
 				setUpdateOpen(false);
 				updateBtnRef.current?.focus();
@@ -3020,6 +4058,13 @@ window.__ModuleLoader__.load({
 				setSettingsOpen(false);
 				settingsBtnRef.current?.focus();
 			};
+			/** 0.6.4: settings → 重新查看教程 — close settings and replay the tutorial
+			* immediately (the flag may or may not be set; skipping/completing it
+			* re-persists the flag anyway). */
+			const reopenOnboarding = () => {
+				setSettingsOpen(false);
+				setOnboardingOpen(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 +4548,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 +4569,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 +4588,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 +4614,7 @@ window.__ModuleLoader__.load({
 											style: {
 												fontSize: 13,
 												fontWeight: 600,
-												color: MODAL_TITLE,
+												color: "#c7cede",
 												marginBottom: 4
 											},
 											children: t("settings.section.features")
@@ -3578,7 +4623,7 @@ window.__ModuleLoader__.load({
 											"data-settings-pin-hint": true,
 											style: {
 												fontSize: 12,
-												color: MODAL_HINT,
+												color: "#8b96ab",
 												lineHeight: 1.5,
 												marginBottom: 10
 											},
@@ -3619,9 +4664,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 +4712,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 +4788,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 +4804,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 +4842,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 +4873,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 +4897,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 +4915,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 +4939,7 @@ window.__ModuleLoader__.load({
 														"data-inset-value": true,
 														style: {
 															fontSize: 12.5,
-															color: MODAL_TEXT,
+															color: "#b9c2d4",
 															width: 40
 														},
 														children: [inset, "px"]
@@ -3914,7 +4959,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 +4971,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 +4989,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 +5059,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 +5072,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 +5091,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 +5110,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 +5133,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 +5157,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 +5176,7 @@ window.__ModuleLoader__.load({
 										style: {
 											fontSize: 13,
 											fontWeight: 600,
-											color: MODAL_TITLE,
+											color: "#c7cede",
 											marginBottom: 8
 										},
 										children: t("settings.language")
@@ -4154,7 +5199,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 +5219,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 +5320,51 @@ 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: reopenOnboarding,
+										style: {
+											padding: "7px 16px",
+											border: `1px solid rgba(255, 255, 255, 0.14)`,
+											borderRadius: 8,
+											cursor: "pointer",
+											color: "#b9c2d4",
+											fontSize: 12.5
+										},
+										children: t("onboarding.reopen")
+									})]
 								})
 							]
 						})
 					}),
+					onboardingOpen && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(MilestoneOnboarding, {
+						t,
+						accent,
+						onClose: () => setOnboardingOpen(false)
+					}),
 					updateOpen && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 						ref: updatePanelRef,
 						"data-update-panel": true,
@@ -4330,7 +5401,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.4" })] }),
 								updateCheck.phase === "ok" && updateCheck.latest !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 									"data-update-latest": true,
 									children: [