dsh-focus-overlay 0.5.0 → 0.7.0

package/README.en.md

@@ -60,6 +60,7 @@ Once in focus mode, an assistant turn no longer shows every step — it folds in
 | Plugin configuration card | A collapsible card under "Settings → Plugins → Plugin configuration": navbar toggle, open-position strategy, text-area width — persisted to `localStorage` |
 | Auto-enter focus | After a reply **completes normally**, auto-open focus at your question; abnormal endings (stop / error / max-tokens / interrupt) never fire |
 | Reply / waiting reminders | In focus, a "New reply ready + View" toast on completion; an "AI is waiting for your reply + Reply" toast on a question/approval, auto-cleared once answered |
+| DSH-better-sidebar compatibility | While in focus, auto-hide its top-right panel toggle buttons and any open right/bottom panels (and release the squeezed layout); restored on exit |
 
 ## Install
 
@@ -98,6 +99,8 @@ dsh web
 
 Restart `dsh web` after install.
 
+> **First run**: after restarting, the welcome page shows a one-time "Focus Mode" intro that explains the features and lets you configure them in place; all of these settings can be changed anytime in "Settings → Plugins → Plugin configuration".
+
 ## Usage
 
 1. Open a session and click the **"Focus"** button in the session header action row.
@@ -105,16 +108,18 @@ Restart `dsh web` after install.
 3. Hover the right-side dots to preview, click to jump; a centered "↓ back to latest" button appears when you're not at the bottom.
 4. Press `Esc` or click "Exit focus" to return — the original UI is untouched.
 
+> **Compatibility note**: if [DSH-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) is also installed, entering focus mode auto-hides its two top-right panel toggle buttons and any open right/bottom panels (releasing the squeezed layout); they're restored as they were on exit, without touching that plugin's layout state.
+
 ## Settings
 
 In the sidebar "Settings → Plugins → Plugin configuration", expand the "Focus Mode" card:
 
 | Option | Description |
 | --- | --- |
-| Show right-side navbar | Toggle the nav dots (default on) |
-| Preserve chat position on open | Open at your current reading position; off opens at the latest (default on) |
+| Auto-enter focus mode when the AI finishes a reply | On a normal completion: auto-open at your question when closed, or a "New reply ready" toast when open (default off) |
+| Sync the current reading position when entering focus mode | Open at the message you're reading; off opens at the latest (default on) |
+| Show right-side turn navbar | One navigation dot per user message (turn) — hover to preview, click to jump (default on) |
 | Text width | 480–1200px slider for the reading column (default 760px) |
-| Auto-enter focus mode when a reply completes | On a normal completion: auto-open at your question when closed, or a "New reply ready" toast when open; an "AI is waiting" toast on a question/approval (default off) |
 
 ## License
 

package/README.md

@@ -58,6 +58,7 @@
 | 插件配置卡片 | 在「设置 → 插件 → 插件配置」中的可折叠卡片，含导航条开关、打开定位策略、文字区宽度，持久化到 `localStorage` |
 | 自动进入专注 | 回复**正常完成**后自动打开专注并定位到本轮你的提问；异常结束（停止 / 报错 / 超 token / 打断）不触发 |
 | 回复 / 等待提醒 | 专注中回复完成弹「新回复已生成 + 查看」；AI 提问 / 审批等待时弹「AI 正在等待你的回复 + 去回复」，回答完自动消失 |
+| 兼容 DSH-better-sidebar | 进入专注时自动隐藏其右上角的收放面板按钮与已开启的右侧/底部面板，并释放被挤压的布局；退出专注后按原状态还原 |
 
 ## 安装
 
@@ -96,6 +97,8 @@ dsh web
 
 安装后重启 `dsh web` 生效。
 
+> **首次安装**：重启后欢迎页会弹出一次「专注模式」引导，说明功能并让你就地完成配置；其中所有设置随时可在「设置 → 插件 → 插件配置」中更改。
+
 ## 使用
 
 1. 打开任意会话，点击标题栏操作区的 **「专注」** 按钮。
@@ -103,16 +106,18 @@ dsh web
 3. 右侧导航圆点可悬停预览、点击跳转；离开底部时右下出现居中的「↓ 回到最新」。
 4. 按 `Esc` 或点「退出专注」返回原界面，原位置/状态保持不变。
 
+> **兼容提示**：若同时安装了 [DSH-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar)，进入专注模式会自动隐藏其右上角的两个收放面板按钮以及已开启的右侧/底部面板（并释放被挤压的布局）；退出专注后按原状态恢复，不会改动该插件的面板布局。
+
 ## 设置
 
 侧栏「设置 → 插件 → 插件配置」中，展开「专注模式」卡片：
 
 | 选项 | 说明 |
 | --- | --- |
-| 显示右侧导航条 | 开关导航圆点（默认开） |
-| 打开时保留聊天位置 | 进入时定位到当前阅读位置；关闭则定位到最新（默认开） |
-| 文字区宽度 | 480–1200px 滑块，调整阅读列宽（默认 760px） |
-| 回复结束后自动进入专注模式 | 回复正常完成后：关闭时自动进入并定位到提问，已打开时弹「新回复已生成」；AI 提问 / 审批等待时弹「AI 正在等待你的回复」（默认关） |
+| AI完成回复后，自动进入专注模式 | AI 正常完成回复后自动进入并定位到你的提问；已打开时弹「新回复已生成」（默认关） |
+| 进入专注模式时，同步当前阅读位置 | 进入时定位到你正在阅读的消息；关闭则定位到最新（默认开） |
+| 显示右侧轮次导航条 | 在右侧显示导航圆点，每个用户消息（一轮）对应一个，悬停预览、点击跳转（默认开） |
+| 文字区宽度 | 480–1200px 滑块，调整正文阅读列宽（默认 760px） |
 
 ## 许可
 

package/lib/client.js

@@ -6,53 +6,6 @@ window.__ModuleLoader__.load({
 		let react = require("react");
 		let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
 		let react_jsx_runtime = require("react/jsx-runtime");
-		//#region src/client/settings.ts
-		const KEY = "dsh-focus-overlay:prefs";
-		const DEFAULTS = {
-			navbar: true,
-			scroll: "preserve",
-			width: 760,
-			autoFocus: false
-		};
-		function load() {
-			try {
-				const raw = localStorage.getItem(KEY);
-				if (raw) return {
-					...DEFAULTS,
-					...JSON.parse(raw)
-				};
-			} catch {}
-			return { ...DEFAULTS };
-		}
-		let prefs = load();
-		const listeners = [];
-		const prefsStore = {
-			get: () => prefs,
-			set: (next) => {
-				prefs = next;
-				try {
-					localStorage.setItem(KEY, JSON.stringify(next));
-				} catch {}
-				for (const l of listeners) l();
-			},
-			update: (patch) => prefsStore.set({
-				...prefs,
-				...patch
-			}),
-			subscribe: (l) => {
-				listeners.push(l);
-				return () => {
-					const i = listeners.indexOf(l);
-					if (i >= 0) listeners.splice(i, 1);
-				};
-			}
-		};
-		function usePrefs() {
-			const [p, setP] = (0, react.useState)(prefsStore.get);
-			(0, react.useEffect)(() => prefsStore.subscribe(() => setP(prefsStore.get)), []);
-			return p;
-		}
-		//#endregion
 		//#region src/client/model.ts
 		function flattenText(content) {
 			if (!content || !content.length) return "";
@@ -313,6 +266,74 @@ window.__ModuleLoader__.load({
 			const pending = snap && snap.pending;
 			return Array.isArray(pending) && pending.length > 0;
 		}
+		/** True once the persisted onboarding flag matches the current intro version.
+		*  Kept as a pure comparison so the "already seen?" decision is testable and
+		*  can be versioned: bump the version to re-show the intro after a major change. */
+		function onboardingSeen(stored, version) {
+			return stored === version;
+		}
+		//#endregion
+		//#region src/client/settings.ts
+		const KEY = "dsh-focus-overlay:prefs";
+		const DEFAULTS = {
+			navbar: true,
+			scroll: "preserve",
+			width: 760,
+			autoFocus: false
+		};
+		function load() {
+			try {
+				const raw = localStorage.getItem(KEY);
+				if (raw) return {
+					...DEFAULTS,
+					...JSON.parse(raw)
+				};
+			} catch {}
+			return { ...DEFAULTS };
+		}
+		let prefs = load();
+		const listeners = [];
+		const prefsStore = {
+			get: () => prefs,
+			set: (next) => {
+				prefs = next;
+				try {
+					localStorage.setItem(KEY, JSON.stringify(next));
+				} catch {}
+				for (const l of listeners) l();
+			},
+			update: (patch) => prefsStore.set({
+				...prefs,
+				...patch
+			}),
+			subscribe: (l) => {
+				listeners.push(l);
+				return () => {
+					const i = listeners.indexOf(l);
+					if (i >= 0) listeners.splice(i, 1);
+				};
+			}
+		};
+		function usePrefs() {
+			const [p, setP] = (0, react.useState)(prefsStore.get);
+			(0, react.useEffect)(() => prefsStore.subscribe(() => setP(prefsStore.get)), []);
+			return p;
+		}
+		const ONBOARD_KEY = "dsh-focus-overlay:onboarded";
+		const onboardingStore = {
+			isDone: () => {
+				try {
+					return onboardingSeen(localStorage.getItem(ONBOARD_KEY), "1");
+				} catch {
+					return false;
+				}
+			},
+			markDone: () => {
+				try {
+					localStorage.setItem(ONBOARD_KEY, "1");
+				} catch {}
+			}
+		};
 		//#endregion
 		//#region src/client/FocusView.tsx
 		let focusOn = false;
@@ -752,8 +773,91 @@ window.__ModuleLoader__.load({
 				children: t("toggle")
 			});
 		}
-		function FocusSettingsCard({ t }) {
+		function FocusPrefsFields({ t }) {
 			const prefs = usePrefs();
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
+				/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "fm-plugin-field",
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+						className: "fm-plugin-check",
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+							type: "checkbox",
+							checked: prefs.autoFocus,
+							onChange: (e) => prefsStore.update({ autoFocus: e.target.checked })
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: "fm-plugin-check-label",
+							children: t("settings.autoFocus")
+						})]
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: "fm-plugin-field-hint",
+						children: t("settings.autoFocus.hint")
+					})]
+				}),
+				/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "fm-plugin-field",
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+						className: "fm-plugin-check",
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+							type: "checkbox",
+							checked: prefs.scroll === "preserve",
+							onChange: (e) => prefsStore.update({ scroll: e.target.checked ? "preserve" : "bottom" })
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: "fm-plugin-check-label",
+							children: t("settings.scrollPreserve")
+						})]
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: "fm-plugin-field-hint",
+						children: t("settings.scrollPreserve.hint")
+					})]
+				}),
+				/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "fm-plugin-field",
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+						className: "fm-plugin-check",
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+							type: "checkbox",
+							checked: prefs.navbar,
+							onChange: (e) => prefsStore.update({ navbar: e.target.checked })
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: "fm-plugin-check-label",
+							children: t("settings.navbar")
+						})]
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: "fm-plugin-field-hint",
+						children: t("settings.navbar.hint")
+					})]
+				}),
+				/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "fm-plugin-field",
+					children: [
+						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							className: "fm-plugin-field-head",
+							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "fm-plugin-field-label",
+								children: t("settings.width")
+							}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+								className: "fm-plugin-field-value",
+								children: [prefs.width, "px"]
+							})]
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+							type: "range",
+							className: "fm-plugin-range",
+							min: 480,
+							max: 1200,
+							step: 40,
+							value: prefs.width,
+							onChange: (e) => prefsStore.update({ width: Number(e.target.value) })
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+							className: "fm-plugin-field-hint",
+							children: t("settings.width.hint")
+						})
+					]
+				})
+			] });
+		}
+		function FocusSettingsCard({ t }) {
 			const [open, setOpen] = (0, react.useState)(false);
 			const title = t("settings.label");
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("li", {
@@ -774,90 +878,100 @@ window.__ModuleLoader__.load({
 							children: t("settings.description")
 						})]
 					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconChevronDownOutline14, { className: "fm-plugin-card-chevron" + (open ? " fm-plugin-card-chevron-open" : "") })]
-				}), open ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				}), open ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 					className: "fm-plugin-card-body",
+					children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(FocusPrefsFields, { t })
+				}) : null]
+			});
+		}
+		function FocusOnboarding(props) {
+			const { complete, openSection, t } = props;
+			const [done, setDone] = (0, react.useState)(() => onboardingStore.isDone());
+			const finished = (0, react.useRef)(false);
+			const finish = (0, react.useCallback)(() => {
+				if (finished.current) return;
+				finished.current = true;
+				complete();
+			}, [complete]);
+			(0, react.useEffect)(() => {
+				if (done) finish();
+			}, [done, finish]);
+			(0, react.useEffect)(() => {
+				const appRoot = document.getElementById("root");
+				if (!appRoot) return;
+				const previous = appRoot.inert;
+				appRoot.inert = true;
+				return () => {
+					appRoot.inert = previous;
+				};
+			}, []);
+			if (done) return null;
+			const dismiss = () => {
+				onboardingStore.markDone();
+				setDone(true);
+				finish();
+			};
+			const goSettings = () => {
+				onboardingStore.markDone();
+				setDone(true);
+				finish();
+				openSection("plugins");
+			};
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Modal, {
+				open: true,
+				title: t("onboarding.title"),
+				onClose: dismiss,
+				headless: true,
+				className: "fm-onboard",
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "fm-onboard-content",
 					children: [
-						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-							className: "fm-plugin-field",
-							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
-								className: "fm-plugin-check",
-								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
-									type: "checkbox",
-									checked: prefs.navbar,
-									onChange: (e) => prefsStore.update({ navbar: e.target.checked })
-								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-									className: "fm-plugin-check-label",
-									children: t("settings.navbar")
-								})]
-							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-								className: "fm-plugin-field-hint",
-								children: t("settings.navbar.hint")
-							})]
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h2", {
+							className: "fm-onboard-title",
+							children: t("onboarding.title")
 						}),
-						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-							className: "fm-plugin-field",
-							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
-								className: "fm-plugin-check",
-								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
-									type: "checkbox",
-									checked: prefs.scroll === "preserve",
-									onChange: (e) => prefsStore.update({ scroll: e.target.checked ? "preserve" : "bottom" })
-								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-									className: "fm-plugin-check-label",
-									children: t("settings.scrollPreserve")
-								})]
-							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-								className: "fm-plugin-field-hint",
-								children: t("settings.scrollPreserve.hint")
-							})]
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+							className: "fm-onboard-intro",
+							children: t("onboarding.intro")
 						}),
-						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-							className: "fm-plugin-field",
-							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
-								className: "fm-plugin-check",
-								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
-									type: "checkbox",
-									checked: prefs.autoFocus,
-									onChange: (e) => prefsStore.update({ autoFocus: e.target.checked })
-								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-									className: "fm-plugin-check-label",
-									children: t("settings.autoFocus")
-								})]
-							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-								className: "fm-plugin-field-hint",
-								children: t("settings.autoFocus.hint")
-							})]
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h3", {
+							className: "fm-onboard-subtitle",
+							children: t("onboarding.features.title")
 						}),
-						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-							className: "fm-plugin-field",
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("ul", {
+							className: "fm-onboard-features",
 							children: [
-								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-									className: "fm-plugin-field-head",
-									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-										className: "fm-plugin-field-label",
-										children: t("settings.width")
-									}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
-										className: "fm-plugin-field-value",
-										children: [prefs.width, "px"]
-									})]
-								}),
-								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
-									type: "range",
-									className: "fm-plugin-range",
-									min: 480,
-									max: 1200,
-									step: 40,
-									value: prefs.width,
-									onChange: (e) => prefsStore.update({ width: Number(e.target.value) })
-								}),
-								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-									className: "fm-plugin-field-hint",
-									children: t("settings.width.hint")
-								})
-							]
+								"fullscreen",
+								"fold",
+								"navbar",
+								"autoFocus"
+							].map((f) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", { children: t("onboarding.feature." + f) }, f))
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h3", {
+							className: "fm-onboard-subtitle",
+							children: t("onboarding.configure.title")
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)(FocusPrefsFields, { t }),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+							className: "fm-onboard-note",
+							children: t("onboarding.laterNote")
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							className: "fm-onboard-actions",
+							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
+								variant: "outline",
+								size: "sm",
+								onClick: goSettings,
+								children: t("onboarding.openSettings")
+							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
+								variant: "primary",
+								size: "sm",
+								onClick: dismiss,
+								children: t("onboarding.done")
+							})]
 						})
 					]
-				}) : null]
+				})
 			});
 		}
 		//#endregion
@@ -915,6 +1029,26 @@ window.__ModuleLoader__.load({
 .fm-plugin-check input[type="checkbox"]{width:16px;height:16px;margin:0;cursor:pointer;accent-color:var(--dsw-alias-brand-primary,#4176e6)}
 .fm-plugin-check-label{color:var(--dsw-alias-label-primary);font-size:13px;line-height:1.5}
 .fm-plugin-range{width:100%;max-width:280px;cursor:pointer;accent-color:var(--dsw-alias-brand-primary,#4176e6)}
+/* DSH-better-sidebar compatibility: its panel host (top-right toggle cluster +
+   right/bottom panels) is appended to document.body at z-index 40/45, above
+   shell.overlay's z-20 layer, so this overlay cannot cover it. Hide the host
+   while focus is on, and neutralize the #root layout push it applies when its
+   panels are open. Selectors mirror better-sidebar's own layout.css exactly. */
+body[data-fm-focus] [data-dsh-panel-host]{display:none!important}
+body[data-fm-focus] #root{margin-right:0!important;width:100%!important}
+body[data-fm-focus] #root [data-dsh-frame] > [data-pane="conversation"],
+body[data-fm-focus] #root :has(> [data-slot="conversation"]){margin-bottom:0!important}
+/* First-run onboarding (settings.onboarding step) — content inside the official
+   Modal primitive; the primitive owns the mask/dialog chrome, these style our body. */
+.fm-onboard{width:min(600px,100%);padding:0}
+.fm-onboard-content{box-sizing:border-box;flex-direction:column;max-height:calc(100vh - 48px);padding:28px;display:flex;overflow-y:auto}
+.fm-onboard-title{color:var(--dsw-alias-label-primary);outline:none;margin:0;font-size:20px;font-weight:500;line-height:28px}
+.fm-onboard-intro{color:var(--dsw-alias-label-secondary);margin:8px 0 0;font-size:14px;line-height:22px}
+.fm-onboard-subtitle{color:var(--dsw-alias-label-primary);margin:20px 0 8px;font-size:14px;font-weight:600;line-height:22px}
+.fm-onboard-features{margin:0;padding:0 0 0 18px;list-style:disc;display:flex;flex-direction:column;gap:6px;color:var(--dsw-alias-label-secondary);font-size:13px;line-height:20px}
+.fm-onboard-note{color:var(--dsw-alias-label-tertiary);margin:12px 0 0;font-size:12px;line-height:18px}
+.fm-onboard-actions{display:flex;justify-content:flex-end;gap:8px;margin-top:20px}
+@media (width<=560px){.fm-onboard-content{padding:24px}}
 `;
 		//#endregion
 		//#region src/client/locales.ts
@@ -928,14 +1062,14 @@ window.__ModuleLoader__.load({
 			"settings.description": "全屏阅读遮罩的偏好设置",
 			"settings.expand": "展开",
 			"settings.collapse": "收起",
-			"settings.navbar": "显示右侧导航条",
-			"settings.navbar.hint": "在右侧显示用户消息导航圆点",
-			"settings.scrollPreserve": "打开时保留聊天位置",
-			"settings.scrollPreserve.hint": "打开时定位到当前阅读位置；关闭则定位到最新",
-			"settings.autoFocus": "回复结束后自动进入专注模式",
-			"settings.autoFocus.hint": "回复正常完成后自动打开；AI 提问 / 审批等待时弹出提醒",
+			"settings.navbar": "显示右侧轮次导航条",
+			"settings.navbar.hint": "在右侧显示导航圆点，每个用户消息（一轮）对应一个，悬停预览、点击跳转",
+			"settings.scrollPreserve": "进入专注模式时，同步当前阅读位置",
+			"settings.scrollPreserve.hint": "进入时定位到你正在阅读的消息；关闭则定位到最新",
+			"settings.autoFocus": "AI完成回复后，自动进入专注模式",
+			"settings.autoFocus.hint": "AI 正常完成回复后自动进入并定位到你的提问",
 			"settings.width": "文字区宽度",
-			"settings.width.hint": "专注模式阅读列宽度（480–1200px）",
+			"settings.width.hint": "专注模式正文的阅读列宽（480–1200px）",
 			"empty": "暂无打开的会话",
 			"loading": "正在读取会话…",
 			"running": "· 正在工作 …",
@@ -957,7 +1091,18 @@ window.__ModuleLoader__.load({
 			"sum.questions": "问了 {n} 个问题",
 			"sum.plans": "计划了 {n} 次",
 			"sum.jobs": "后台任务 {n} 个",
-			"sum.others": "调用了 {n} 个工具"
+			"sum.others": "调用了 {n} 个工具",
+			"onboarding.title": "欢迎使用专注模式",
+			"onboarding.intro": "dsh-focus-overlay 为 DeepSeek Harness Web 提供全屏专注阅读。",
+			"onboarding.features.title": "功能",
+			"onboarding.feature.fullscreen": "全屏阅读 —— 隐藏标题栏、输入区与侧栏，纵向空间尽给对话",
+			"onboarding.feature.fold": "折叠工具调用 —— 把 AI 的命令、编辑、搜索等步骤折叠成一行摘要",
+			"onboarding.feature.navbar": "右侧导航条 —— 按用户消息快速跳转，悬停预览",
+			"onboarding.feature.autoFocus": "自动专注与提醒 —— 回复完成自动进入专注，AI 提问 / 等待时提醒",
+			"onboarding.configure.title": "快速配置",
+			"onboarding.laterNote": "这些设置随时可在「设置 → 插件 → 插件配置」中更改。",
+			"onboarding.openSettings": "打开设置",
+			"onboarding.done": "完成"
 		};
 		const en = {
 			"toggle": "Focus",
@@ -968,12 +1113,12 @@ window.__ModuleLoader__.load({
 			"settings.description": "Preferences for the full-screen reading overlay",
 			"settings.expand": "Expand",
 			"settings.collapse": "Collapse",
-			"settings.navbar": "Show right-side navbar",
-			"settings.navbar.hint": "Show navigation dots for user messages on the right",
-			"settings.scrollPreserve": "Preserve chat position on open",
-			"settings.scrollPreserve.hint": "Open at your current reading position; off opens at the latest",
-			"settings.autoFocus": "Auto-enter focus mode when a reply completes",
-			"settings.autoFocus.hint": "Auto-open after a normal completion; toast while AI waits for you",
+			"settings.navbar": "Show right-side turn navbar",
+			"settings.navbar.hint": "Show one navigation dot per user message (turn) — hover to preview, click to jump",
+			"settings.scrollPreserve": "Sync the current reading position when entering focus mode",
+			"settings.scrollPreserve.hint": "Open at the message you're reading; off opens at the latest",
+			"settings.autoFocus": "Auto-enter focus mode when the AI finishes a reply",
+			"settings.autoFocus.hint": "Auto-open at your question after a normal reply",
 			"settings.width": "Text width",
 			"settings.width.hint": "Reading column width (480–1200px)",
 			"empty": "No open session",
@@ -997,7 +1142,18 @@ window.__ModuleLoader__.load({
 			"sum.questions": "asked {n} questions",
 			"sum.plans": "planned {n} times",
 			"sum.jobs": "{n} background jobs",
-			"sum.others": "called {n} tools"
+			"sum.others": "called {n} tools",
+			"onboarding.title": "Welcome to Focus Mode",
+			"onboarding.intro": "dsh-focus-overlay adds full-screen reading to the DeepSeek Harness web GUI.",
+			"onboarding.features.title": "Features",
+			"onboarding.feature.fullscreen": "Full-screen reading — hides the header, composer and sidebars",
+			"onboarding.feature.fold": "Folded tool calls — collapses commands, edits and searches into one summary line",
+			"onboarding.feature.navbar": "Right-side navbar — jump between user messages with hover previews",
+			"onboarding.feature.autoFocus": "Auto-focus & reminders — auto-enter after a reply, notify while the AI waits",
+			"onboarding.configure.title": "Quick setup",
+			"onboarding.laterNote": "You can change these anytime in Settings → Plugins → Plugin configuration.",
+			"onboarding.openSettings": "Open settings",
+			"onboarding.done": "Done"
 		};
 		//#endregion
 		//#region src/client/index.ts
@@ -1029,6 +1185,18 @@ window.__ModuleLoader__.load({
 						style.remove();
 					};
 				});
+				ctx.effect(() => {
+					const sync = () => {
+						if (focusStore.get()) document.body.setAttribute("data-fm-focus", "");
+						else document.body.removeAttribute("data-fm-focus");
+					};
+					sync();
+					const unsub = focusStore.subscribe(sync);
+					return () => {
+						unsub();
+						document.body.removeAttribute("data-fm-focus");
+					};
+				});
 				ctx.effect(() => ctx.locale.register(NS, {
 					zh,
 					en
@@ -1115,6 +1283,14 @@ window.__ModuleLoader__.load({
 					id: "dsh-focus-overlay",
 					order: 1e3
 				}, () => (0, react.createElement)(FocusSettingsCard, { t })));
+				ctx.slots.inject("settings.onboarding", () => ctx.slots.register({
+					name: "settings.onboarding",
+					id: "dsh-focus-overlay",
+					order: 10
+				}, (props) => (0, react.createElement)(FocusOnboarding, {
+					...props,
+					t
+				})));
 			}
 		};
 		return module.exports;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-focus-overlay",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Focus Mode for the dsh web GUI: a full-screen reading overlay that hides chrome and folds the AI tool-call flow into summaries, reusing the official Markdown / image primitives.",
   "type": "module",
   "main": "lib/index.mjs",