@luziyang2026/dsh-question-nav 0.4.1 → 0.5.0

package/README.md

@@ -1,5 +1,10 @@
 # dsh-question-nav
 
+<p align="center">
+  <a href="https://github.com/AbelKeithsun/dsh-question-nav/blob/main/README.md">English</a> |
+  <a href="https://github.com/AbelKeithsun/dsh-question-nav/blob/main/README.zh.md">简体中文</a>
+</p>
+
 In-session question navigator for the [DeepSeek Harness (DSH) Web GUI][dsh]: a
 vertical column of small round dots overlaid on the **left edge** of the
 conversation column — one dot per user question. Hover a dot to enlarge it and
@@ -14,11 +19,14 @@ Package: **`@luziyang2026/dsh-question-nav`** ([npm][npm] · [GitHub][github]).
 
 ## Preview
 
-![Left-edge dot minimap with a hover tooltip showing the turn label and full question text](https://raw.githubusercontent.com/AbelKeithsun/dsh-question-nav/main/docs/images/question-nav-preview.jpg)
+![Full DSH Web GUI screenshot with the question-nav dot rail embedded on the left edge of the conversation column](https://raw.githubusercontent.com/AbelKeithsun/dsh-question-nav/main/docs/images/question-nav-preview.jpg)
 
 ## What it does
 
-- **Left-edge dot minimap** (embedded, not reserving any width).
+- **Left-edge dot minimap** (embedded, not reserving any width). The rail's
+  anchor edge is configurable — **Settings → Plugins → Question Nav → Rail
+  alignment** switches it between the left and right edge of the conversation
+  column.
 - **Vertically centered** in the conversation column.
 - **One dot = one turn that asked a question** (strictly aligned with the
   Trajectory view's turn numbering), with a small count above the dot column.

package/README.zh.md

@@ -1,5 +1,10 @@
 # dsh-question-nav
 
+<p align="center">
+  <a href="https://github.com/AbelKeithsun/dsh-question-nav/blob/main/README.md">English</a> |
+  <a href="https://github.com/AbelKeithsun/dsh-question-nav/blob/main/README.zh.md">简体中文</a>
+</p>
+
 [DeepSeek Harness (DSH) Web GUI][dsh] 的**会话内提问导航**插件：在对话栏**左侧**
 内嵌一列竖排的圆点小按钮 —— 每个圆点对应一个用户提问。鼠标悬停圆点会放大
 并**立即**显示该提问的**全文**；点击圆点则把对话滚动跳到那一提问的位置。
@@ -11,11 +16,12 @@
 
 ## 效果展示
 
-![左缘圆点迷你地图：竖排圆点，每个圆点对应一个用户提问，悬停显示 Turn 编号与全文](https://raw.githubusercontent.com/AbelKeithsun/dsh-question-nav/main/docs/images/question-nav-preview.jpg)
+![DSH Web GUI 完整截图：对话栏左侧内嵌提问导航圆点列，每个圆点对应一个用户提问](https://raw.githubusercontent.com/AbelKeithsun/dsh-question-nav/main/docs/images/question-nav-preview.jpg)
 
 ## 功能
 
-- **左缘圆点迷你地图**：内嵌，**不占任何宽度**。
+- **左缘圆点迷你地图**：内嵌，**不占任何宽度**。导航条锚定边**可配置**——
+  **设置 → 插件 → 提问导航 → 导航条对齐**可在对话栏左/右缘之间切换。
 - **垂直居中**在对话栏中。
 - **一个圆点 = 一个含提问的 turn**（与轨迹视图的 Turn 编号严格对齐），
   圆点列上方有圆点数量。

package/lib/client.js

@@ -18,13 +18,21 @@ window.__ModuleLoader__.load({
 		function questionKey(id) {
 			return `13:${MESSAGE_DEFINITION_KIND}${String(id)}`;
 		}
+		/** True when entries are already in non-decreasing seq order (the projection
+		* appends in event order, so this is the common case and skips the sort). */
+		function isSortedBySeq(entries) {
+			for (let i = 1; i < entries.length; i++) if (entries[i].seq < entries[i - 1].seq) return false;
+			return true;
+		}
 		/**
 		* Fold the projection's question list into one dot per turn. Entries arrive
 		* in event order; consecutive same-turn entries merge into a single dot whose
-		* anchor is the turn's first question.
+		* anchor is the turn's first question. The input is expected to be sorted by
+		* seq; the defensive sort is skipped when it already is, so a long session
+		* never pays an O(n log n) sort on every content update.
 		*/
 		function groupQuestionsByTurn(entries) {
-			const sorted = [...entries].sort((a, b) => a.seq - b.seq);
+			const sorted = isSortedBySeq(entries) ? entries : [...entries].sort((a, b) => a.seq - b.seq);
 			const dots = [];
 			for (const entry of sorted) {
 				const key = questionKey(entry.id);
@@ -54,23 +62,45 @@ window.__ModuleLoader__.load({
 		* whose key is already folded into a dot is dropped (the projected copy
 		* wins); the rest become single-question dots with `turn: null`, inserted in
 		* anchor-seq order so the strip stays strictly chronological.
+		*
+		* Fast path: when nothing new arrives the SAME array is returned (no copy),
+		* so the caller can bail out of a re-render on identical reference.
 		*/
 		function mergeLiveQuestions(dots, live) {
-			const known = new Set(dots.flatMap((dot) => dot.memberKeys));
-			const extras = live.filter((question) => !known.has(question.key)).map((question) => ({
-				turn: null,
-				key: question.key,
-				anchorSeq: question.anchorSeq,
-				time: question.time,
-				texts: [question.text],
-				memberKeys: [question.key]
-			}));
-			if (extras.length === 0) return [...dots];
-			return [...dots, ...extras].sort((a, b) => a.anchorSeq - b.anchorSeq);
+			if (live.length === 0) return dots;
+			const known = /* @__PURE__ */ new Set();
+			for (const dot of dots) for (const key of dot.memberKeys) known.add(key);
+			const extras = [];
+			for (const question of live) {
+				if (known.has(question.key)) continue;
+				extras.push({
+					turn: null,
+					key: question.key,
+					anchorSeq: question.anchorSeq,
+					time: question.time,
+					texts: [question.text],
+					memberKeys: [question.key]
+				});
+			}
+			if (extras.length === 0) return dots;
+			const out = [];
+			let i = 0;
+			for (const extra of extras) {
+				while (i < dots.length && dots[i].anchorSeq <= extra.anchorSeq) {
+					out.push(dots[i]);
+					i += 1;
+				}
+				out.push(extra);
+			}
+			while (i < dots.length) {
+				out.push(dots[i]);
+				i += 1;
+			}
+			return out;
 		}
 		//#endregion
 		//#region \0dsh-css:dsh-question-nav/src/client/question-nav.module.css.mjs
-		const css = ".TWf_pa_rail{z-index:1;box-sizing:border-box;pointer-events:none;background:0 0;flex-direction:column;align-items:center;width:44px;display:flex;position:absolute;top:0;bottom:0;left:0}.TWf_pa_list{scrollbar-width:thin;flex-direction:column;flex:1;align-items:center;gap:6px;width:100%;min-height:0;padding:8px 0;display:flex;overflow:hidden auto}.TWf_pa_list>:first-child{margin-top:auto}.TWf_pa_list>:last-child{margin-bottom:auto}.TWf_pa_dot{pointer-events:auto;background:var(--dsw-alias-border-l3);cursor:pointer;border:none;border-radius:50%;flex:none;width:8px;height:8px;padding:0;transition:transform .12s,background .12s}.TWf_pa_dot:hover{background:var(--dsw-alias-brand-primary);transform:scale(2)}.TWf_pa_dot.TWf_pa_active{background:var(--dsw-alias-brand-primary);transform:scale(1.6)}.TWf_pa_count{color:var(--dsw-alias-label-tertiary);user-select:none;flex:none;font-size:10px;font-weight:600;line-height:1}.TWf_pa_dots{flex-direction:column;align-items:center;gap:6px;display:flex}.TWf_pa_empty{color:var(--dsw-alias-label-tertiary);text-align:center;word-break:break-word;padding:10px 4px;font-size:11px}.TWf_pa_tooltip{z-index:20;background:var(--dsw-alias-bg-layer-1);border:1px solid var(--dsw-alias-border-l1);max-width:420px;color:var(--dsw-alias-label-primary);white-space:normal;word-break:break-word;pointer-events:none;border-radius:8px;padding:8px 12px;font-size:13px;line-height:18px;position:fixed;box-shadow:0 4px 16px #0003}.TWf_pa_tooltipTitle{color:var(--dsw-alias-label-tertiary);margin-bottom:4px;font-size:11px;font-weight:600}.TWf_pa_tooltipLine+.TWf_pa_tooltipLine{border-top:1px solid var(--dsw-alias-border-l1);margin-top:6px;padding-top:6px}";
+		const css = ".TWf_pa_rail{z-index:1;box-sizing:border-box;pointer-events:none;background:0 0;flex-direction:column;align-items:center;width:44px;display:flex;position:absolute;top:0;bottom:0;left:0}.TWf_pa_railRight{left:auto}.TWf_pa_list{scrollbar-width:thin;flex-direction:column;flex:1;align-items:center;gap:6px;width:100%;min-height:0;padding:8px 0;display:flex;overflow:hidden auto}.TWf_pa_list>:first-child{margin-top:auto}.TWf_pa_list>:last-child{margin-bottom:auto}.TWf_pa_dot{pointer-events:auto;background:var(--dsw-alias-border-l3);cursor:pointer;border:none;border-radius:50%;flex:none;width:8px;height:8px;padding:0;transition:transform .12s,background .12s}.TWf_pa_dot:hover{background:var(--dsw-alias-brand-primary);transform:scale(2)}.TWf_pa_dot.TWf_pa_active{background:var(--dsw-alias-brand-primary);transform:scale(1.6)}.TWf_pa_count{color:var(--dsw-alias-label-tertiary);user-select:none;flex:none;font-size:10px;font-weight:600;line-height:1}.TWf_pa_dots{flex-direction:column;align-items:center;gap:6px;display:flex}.TWf_pa_empty{color:var(--dsw-alias-label-tertiary);text-align:center;word-break:break-word;padding:10px 4px;font-size:11px}.TWf_pa_tooltip{z-index:20;background:var(--dsw-alias-bg-layer-1);border:1px solid var(--dsw-alias-border-l1);max-width:420px;color:var(--dsw-alias-label-primary);white-space:normal;word-break:break-word;pointer-events:none;border-radius:8px;padding:8px 12px;font-size:13px;line-height:18px;position:fixed;box-shadow:0 4px 16px #0003}.TWf_pa_tooltipTitle{color:var(--dsw-alias-label-tertiary);margin-bottom:4px;font-size:11px;font-weight:600}.TWf_pa_tooltipLine+.TWf_pa_tooltipLine{border-top:1px solid var(--dsw-alias-border-l1);margin-top:6px;padding-top:6px}.TWf_pa_settings{flex-direction:column;gap:8px;padding:4px 0;display:flex}.TWf_pa_settingsTitle{color:var(--dsw-alias-label-primary);margin:0;font-size:13px;font-weight:600}.TWf_pa_settingsDesc{color:var(--dsw-alias-label-secondary);margin:0;font-size:12px;line-height:18px}.TWf_pa_segmented{border:1px solid var(--dsw-alias-border-l1);border-radius:8px;align-self:flex-start;display:inline-flex;overflow:hidden}.TWf_pa_segment{color:var(--dsw-alias-label-secondary);cursor:pointer;background:0 0;border:none;padding:8px 16px;font-size:13px;line-height:1;transition:background .12s,color .12s}.TWf_pa_segment+.TWf_pa_segment{border-left:1px solid var(--dsw-alias-border-l1)}.TWf_pa_segment:hover{background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary)}.TWf_pa_segmentActive,.TWf_pa_segmentActive:hover{background:var(--dsw-alias-brand-primary);color:var(--dsw-alias-label-inverse)}";
 		const tagId = "@luziyang2026/dsh-question-nav/question-nav.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
 			const tag = document.createElement("style");
@@ -87,6 +117,13 @@ window.__ModuleLoader__.load({
 			"empty": "TWf_pa_empty",
 			"list": "TWf_pa_list",
 			"rail": "TWf_pa_rail",
+			"railRight": "TWf_pa_railRight",
+			"segment": "TWf_pa_segment",
+			"segmentActive": "TWf_pa_segmentActive",
+			"segmented": "TWf_pa_segmented",
+			"settings": "TWf_pa_settings",
+			"settingsDesc": "TWf_pa_settingsDesc",
+			"settingsTitle": "TWf_pa_settingsTitle",
 			"tooltip": "TWf_pa_tooltip",
 			"tooltipLine": "TWf_pa_tooltipLine",
 			"tooltipTitle": "TWf_pa_tooltipTitle"
@@ -129,6 +166,19 @@ window.__ModuleLoader__.load({
 		function findConvRoot() {
 			return document.querySelector("[data-slot=\"conversation\"] > div[data-phase]");
 		}
+		/** Structural equality of two dot lists (member keys fully capture a dot's
+		* folded questions, so identical key sequences mean identical content).
+		* Lets the strip skip a re-render when a refresh produced no change. */
+		function sameDots(a, b) {
+			if (a.length !== b.length) return false;
+			for (let i = 0; i < a.length; i++) {
+				const da = a[i];
+				const db = b[i];
+				if (da.key !== db.key || da.memberKeys.length !== db.memberKeys.length) return false;
+				for (let j = 0; j < da.memberKeys.length; j++) if (da.memberKeys[j] !== db.memberKeys[j]) return false;
+			}
+			return true;
+		}
 		function QuestionNavStrip(props) {
 			const current = props.useSessions((s) => s.current);
 			const summary = props.useSessions((s) => s.current === void 0 ? void 0 : s.byId[s.current]);
@@ -137,8 +187,11 @@ window.__ModuleLoader__.load({
 			const [jumpingKey, setJumpingKey] = (0, react.useState)(null);
 			const [hint, setHint] = (0, react.useState)(null);
 			const [tooltip, setTooltip] = (0, react.useState)(null);
+			const [align, setAlign] = (0, react.useState)(() => props.align());
 			const panelRef = (0, react.useRef)(null);
 			const hintTimerRef = (0, react.useRef)(null);
+			const lastDotsRef = (0, react.useRef)([]);
+			(0, react.useEffect)(() => props.subscribeAlign(() => setAlign(props.align())), [props]);
 			const showHint = (message) => {
 				setHint(message);
 				if (hintTimerRef.current !== null) window.clearTimeout(hintTimerRef.current);
@@ -147,22 +200,26 @@ window.__ModuleLoader__.load({
 			(0, react.useEffect)(() => {
 				if (!visible || current === void 0) {
 					setDots([]);
+					lastDotsRef.current = [];
 					return;
 				}
 				const sessionId = current;
 				const face = props.questionProjection(sessionId);
 				const refresh = () => {
-					const grouped = groupQuestionsByTurn(projectionEntries(face));
-					setDots(mergeLiveQuestions(grouped, props.readQuestions(sessionId)));
+					const next = mergeLiveQuestions(groupQuestionsByTurn(projectionEntries(face)), props.readQuestions(sessionId));
+					if (sameDots(next, lastDotsRef.current)) {
+						setDots(lastDotsRef.current);
+						return;
+					}
+					lastDotsRef.current = next;
+					setDots(next);
 				};
 				refresh();
 				const unsubProjection = face?.subscribe(refresh) ?? (() => {});
 				const unsubContent = props.subscribeContent(sessionId, refresh);
-				const unsubList = props.subscribeList(refresh);
 				return () => {
 					unsubProjection();
 					unsubContent();
-					unsubList();
 				};
 			}, [
 				visible,
@@ -180,39 +237,84 @@ window.__ModuleLoader__.load({
 			(0, react.useLayoutEffect)(() => {
 				if (!visible) return;
 				let raf = 0;
-				let retries = 0;
+				let idle = 0;
+				let stopped = false;
+				let observer = null;
+				const observed = {
+					frame: null,
+					convRoot: null
+				};
 				const applyLayout = () => {
 					const panel = panelRef.current;
-					if (panel === null) return;
+					if (panel === null) return false;
 					const frame = panel.closest("[data-shell-overlay]")?.parentElement ?? null;
 					const convRoot = findConvRoot();
-					if (frame === null || convRoot === null) return;
+					if (frame === null || convRoot === null) return true;
+					if (observer !== null) {
+						if (observed.frame !== frame) {
+							observer.observe(frame, { box: "border-box" });
+							observed.frame = frame;
+						}
+						if (observed.convRoot !== convRoot) {
+							observer.observe(convRoot, { box: "border-box" });
+							observed.convRoot = convRoot;
+						}
+					}
 					const frameRect = frame.getBoundingClientRect();
 					const convRect = convRoot.getBoundingClientRect();
-					if (convRect.height <= 0) {
-						if (retries < 20) {
-							retries += 1;
-							raf = requestAnimationFrame(applyLayout);
-						}
-						return;
+					if (convRect.height <= 0 || convRect.width <= 0) return true;
+					const top = `${convRect.top - frameRect.top}px`;
+					const height = `${convRect.height}px`;
+					if (align === "right") {
+						const right = `${frameRect.right - convRect.right}px`;
+						if (panel.style.top === top && panel.style.height === height && panel.style.right === right && panel.style.left === "") return false;
+						panel.style.top = top;
+						panel.style.height = height;
+						panel.style.right = right;
+						panel.style.left = "";
+						return true;
 					}
-					retries = 0;
-					panel.style.top = `${convRect.top - frameRect.top}px`;
-					panel.style.height = `${convRect.height}px`;
-					panel.style.left = `${convRect.left - frameRect.left}px`;
+					const left = `${convRect.left - frameRect.left}px`;
+					if (panel.style.top === top && panel.style.height === height && panel.style.left === left && panel.style.right === "") return false;
+					panel.style.top = top;
+					panel.style.height = height;
+					panel.style.left = left;
+					panel.style.right = "";
+					return true;
+				};
+				const loop = () => {
+					if (stopped) return;
+					raf = 0;
+					idle = applyLayout() ? 0 : idle + 1;
+					if (idle < 3) raf = requestAnimationFrame(loop);
 				};
-				applyLayout();
-				raf = requestAnimationFrame(applyLayout);
-				const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(applyLayout);
-				const convRoot = findConvRoot();
-				observer?.observe(convRoot ?? document.body, { box: "border-box" });
-				window.addEventListener("resize", applyLayout);
+				const wake = () => {
+					if (stopped) return;
+					idle = 0;
+					if (raf === 0) raf = requestAnimationFrame(loop);
+				};
+				observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(wake);
+				if (observer !== null) {
+					const frame = panelRef.current?.closest("[data-shell-overlay]")?.parentElement ?? null;
+					const convRoot = findConvRoot();
+					if (frame !== null) {
+						observer.observe(frame, { box: "border-box" });
+						observed.frame = frame;
+					}
+					if (convRoot !== null) {
+						observer.observe(convRoot, { box: "border-box" });
+						observed.convRoot = convRoot;
+					}
+				}
+				wake();
+				window.addEventListener("resize", wake);
 				return () => {
+					stopped = true;
 					if (raf !== 0) cancelAnimationFrame(raf);
 					observer?.disconnect();
-					window.removeEventListener("resize", applyLayout);
+					window.removeEventListener("resize", wake);
 				};
-			}, [visible]);
+			}, [visible, align]);
 			(0, react.useEffect)(() => () => {
 				if (hintTimerRef.current !== null) window.clearTimeout(hintTimerRef.current);
 			}, []);
@@ -228,14 +330,14 @@ window.__ModuleLoader__.load({
 				setTooltip({
 					title: dot.turn === null ? null : `Turn ${dot.turn}`,
 					lines: dot.texts,
-					left: r.right + 10,
+					...align === "right" ? { right: window.innerWidth - r.left + 10 } : { left: r.right + 10 },
 					top: r.top
 				});
 			};
 			const t = props.t;
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				ref: panelRef,
-				className: question_nav_module_css_default.rail,
+				className: align === "right" ? `${question_nav_module_css_default.rail} ${question_nav_module_css_default.railRight}` : question_nav_module_css_default.rail,
 				"data-question-nav": "rail",
 				children: [
 					hint !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
@@ -266,6 +368,7 @@ window.__ModuleLoader__.load({
 						className: question_nav_module_css_default.tooltip,
 						style: {
 							left: tooltip.left,
+							right: tooltip.right,
 							top: tooltip.top
 						},
 						children: [tooltip.title !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
@@ -280,6 +383,134 @@ window.__ModuleLoader__.load({
 			});
 		}
 		//#endregion
+		//#region src/core/align.ts
+		/**
+		* Rail anchor-edge constants shared by the host schema and the browser
+		* settings scope. Pure data: no DSH imports, so the client bundle may inline
+		* this module (a Host import here would leak into the browser half).
+		*
+		* @module dsh-question-nav/align
+		*/
+		/** Supported rail anchor edges. */
+		const ALIGN_OPTIONS = ["left", "right"];
+		/** Default anchor edge when the user-settings document has no override. */
+		const DEFAULT_ALIGN = "left";
+		/** Settings namespace owned by this plugin (spelled here rather than
+		* imported: the client bundle must not depend on a Host package). */
+		const QUESTION_NAV_SETTINGS_NS = "question-nav";
+		/** Field carrying the selected anchor edge. */
+		const ALIGN_FIELD = "align";
+		//#endregion
+		//#region src/client/QuestionNavSettingsTab.tsx
+		/**
+		* The plugin's settings page inside the shell's Plugins section
+		* (`settings.plugins.tab`): a segmented control choosing which edge of the
+		* conversation column the dot rail anchors to. The choice is written to the
+		* `question-nav` settings namespace (registered by the host half); the strip
+		* re-anchors live when the snapshot changes.
+		*
+		* @module dsh-question-nav/client/settings-tab
+		*/
+		/** Re-render on settings snapshot changes (the register inject face is static). */
+		function useAlignTick(subscribe) {
+			const [, bump] = (0, react.useState)(0);
+			(0, react.useEffect)(() => subscribe(() => bump((n) => n + 1)), [subscribe]);
+		}
+		function QuestionNavSettingsTab(props) {
+			useAlignTick(props.subscribeAlign);
+			const align = props.align();
+			const t = props.t;
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: question_nav_module_css_default.settings,
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: question_nav_module_css_default.settingsTitle,
+						children: t("settings.align.title")
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: question_nav_module_css_default.settingsDesc,
+						children: t("settings.align.desc")
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: question_nav_module_css_default.segmented,
+						role: "radiogroup",
+						"aria-label": t("settings.align.title"),
+						children: ALIGN_OPTIONS.map((option) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							type: "button",
+							role: "radio",
+							"aria-checked": align === option,
+							className: align === option ? `${question_nav_module_css_default.segment} ${question_nav_module_css_default.segmentActive}` : question_nav_module_css_default.segment,
+							onClick: () => props.setAlign(option),
+							children: t(option === "left" ? "settings.align.left" : "settings.align.right")
+						}, option))
+					})
+				]
+			});
+		}
+		//#endregion
+		//#region src/client/settings.ts
+		/** Narrow a raw section to the anchor field. */
+		function isAlignPreference(value) {
+			return ALIGN_OPTIONS.some((option) => option === value);
+		}
+		/** Reactive handle over the plugin's durable settings section. */
+		var QuestionNavSettingsController = class {
+			scope;
+			listeners = /* @__PURE__ */ new Set();
+			unsubscribe = () => {};
+			state = {
+				align: DEFAULT_ALIGN,
+				overridden: false
+			};
+			/**
+			* Bind the namespace scope once the settings surface is present. Called
+			* from a fiber that injects `settingsScope`, so the scope subscription
+			* lives on that fiber and is released with it. A no-op after the first
+			* bind.
+			* @param binder - the settings scope service.
+			*/
+			attach(binder) {
+				if (this.scope !== void 0) return;
+				this.scope = binder.bind({ namespace: QUESTION_NAV_SETTINGS_NS });
+				this.state = this.derive(this.scope.getSnapshot());
+				this.unsubscribe = this.scope.subscribe(() => {
+					if (this.scope === void 0) return;
+					const next = this.derive(this.scope.getSnapshot());
+					if (next.align === this.state.align && next.overridden === this.state.overridden) return;
+					this.state = next;
+					for (const listener of this.listeners) listener();
+				});
+			}
+			derive(snapshot) {
+				const user = snapshot.user;
+				return {
+					align: snapshot.status === "ready" && isAlignPreference(snapshot.value?.align) ? snapshot.value.align : DEFAULT_ALIGN,
+					overridden: user !== void 0 && user.align !== void 0
+				};
+			}
+			/** Release the scope subscription (bound on the settings fiber's lifecycle). */
+			dispose() {
+				this.unsubscribe();
+				this.listeners.clear();
+			}
+			/** @returns the current state (stable reference until the next change). */
+			getSnapshot() {
+				return this.state;
+			}
+			/** Observe state replacements; returns the disposer. */
+			subscribe(listener) {
+				this.listeners.add(listener);
+				return () => {
+					this.listeners.delete(listener);
+				};
+			}
+			/** Route the user's anchor-edge choice to the Host document. */
+			setAlign(align) {
+				if (this.scope === void 0) return;
+				this.scope.set(ALIGN_FIELD, align);
+			}
+		};
+		//#endregion
 		//#region src/client/locales.ts
 		/**
 		* Locale dictionaries for the question-nav surface (zh/en). Registered under
@@ -290,14 +521,24 @@ window.__ModuleLoader__.load({
 			"jump.inactive": "聊天视图未激活",
 			"jump.hidden": "目标无独立气泡，已定位到邻近内容",
 			"jump.notfound": "目标未加载或不存在（可能已压缩）",
-			"jump.timeout": "加载历史超时，可重试"
+			"jump.timeout": "加载历史超时，可重试",
+			"settings.tab": "提问导航",
+			"settings.align.title": "导航条对齐",
+			"settings.align.desc": "选择圆点导航条锚定在对话栏的哪一侧。",
+			"settings.align.left": "左侧",
+			"settings.align.right": "右侧"
 		};
 		const en = {
 			"strip.empty": "No questions in this session yet",
 			"jump.inactive": "Chat view is not active",
 			"jump.hidden": "No dedicated bubble; landed on nearby content",
 			"jump.notfound": "Target not loaded or missing (maybe compacted)",
-			"jump.timeout": "Timed out loading history; retry"
+			"jump.timeout": "Timed out loading history; retry",
+			"settings.tab": "Question Nav",
+			"settings.align.title": "Rail alignment",
+			"settings.align.desc": "Choose which edge of the conversation column the dot rail anchors to.",
+			"settings.align.left": "Left",
+			"settings.align.right": "Right"
 		};
 		//#endregion
 		//#region src/core/nodes.ts
@@ -505,7 +746,7 @@ window.__ModuleLoader__.load({
 				subscribe: (listener) => face.subscribe(listener)
 			};
 		}
-		function createInject(ctx) {
+		function createInject(ctx, settings) {
 			return {
 				readQuestions: (sessionId) => {
 					const snap = ctx.sessions.binding(sessionId)?.session.getSnapshot();
@@ -525,7 +766,10 @@ window.__ModuleLoader__.load({
 						window.dispatchEvent(new CustomEvent("question-nav:jump-failed", { detail: code }));
 					};
 					jumpToQuestion(ports, key);
-				}
+				},
+				align: () => settings.getSnapshot().align,
+				subscribeAlign: (cb) => settings.subscribe(cb),
+				setAlign: (align) => settings.setAlign(align)
 			};
 		}
 		/**
@@ -539,7 +783,9 @@ window.__ModuleLoader__.load({
 				zh,
 				en
 			}), "question-nav: dictionaries");
-			const injected = createInject(ctx);
+			const t = ctx.locale.bind(NS);
+			const settings = new QuestionNavSettingsController();
+			const injected = createInject(ctx, settings);
 			ctx.slots.inject("shell.overlay", () => ctx.slots.register({
 				name: "shell.overlay",
 				id: "question-nav",
@@ -547,6 +793,17 @@ window.__ModuleLoader__.load({
 				locale: NS,
 				inject: () => injected
 			}, QuestionNavStrip));
+			ctx.inject(["settingsScope"], (scopeCtx) => {
+				settings.attach(scopeCtx.get("settingsScope"));
+				ctx.slots.inject("settings.plugins.tab", () => ctx.slots.register({
+					name: "settings.plugins.tab",
+					id: "question-nav",
+					order: 100,
+					label: () => t("settings.tab"),
+					locale: NS,
+					inject: () => injected
+				}, QuestionNavSettingsTab));
+			});
 		}
 		//#endregion
 		exports.apply = apply;