@luziyang2026/dsh-question-nav 0.4.2 → 0.6.0

package/lib/client.js

@@ -98,9 +98,90 @@ window.__ModuleLoader__.load({
 			}
 			return out;
 		}
+		/** Magnification scale per tier, by distance from the selected dot
+		* (0 = selected, 1 = immediate neighbor, 2 = outer window edge). */
+		const FOCUS_SCALES = [
+			2,
+			1.55,
+			1.25
+		];
+		/**
+		* The focus tier of a dot at `distance` from the selected dot: 0..FOCUS_RADIUS
+		* while inside the magnification window, null beyond it (base scale).
+		*/
+		function focusTier(distance) {
+			const d = Math.abs(distance);
+			if (d > 2) return null;
+			return d;
+		}
+		/** Magnification scale for a dot at `distance`; 1 (base) outside the window. */
+		function focusScale(distance) {
+			const tier = focusTier(distance);
+			return tier === null ? 1 : FOCUS_SCALES[tier];
+		}
+		function focusCardMetrics(distance) {
+			const tier = focusTier(distance);
+			if (tier === null) return null;
+			switch (tier) {
+				case 0: return {
+					widthPx: 380,
+					fontSize: 13,
+					maxLines: 6,
+					brightness: 1
+				};
+				case 1: return {
+					widthPx: 300,
+					fontSize: 12.5,
+					maxLines: 2,
+					brightness: .82
+				};
+				default: return {
+					widthPx: 240,
+					fontSize: 12,
+					maxLines: 1,
+					brightness: .68
+				};
+			}
+		}
+		//#endregion
+		//#region src/core/time.ts
+		/**
+		* Question sent-time formatting for the question-nav surface. Pure: no DSH
+		* imports, deterministic for a given (time, now) pair — unit-testable in
+		* isolation and safe to inline into the client bundle.
+		*
+		* @module dsh-question-nav/time
+		*/
+		function pad2(n) {
+			return n < 10 ? `0${n}` : String(n);
+		}
+		/** Whether `time` falls on the same calendar day as `now`. */
+		function isSameDay(time, now) {
+			const a = new Date(time);
+			const b = new Date(now);
+			return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+		}
+		/**
+		* Smart question sent-time, relative to `now`:
+		* - same calendar day → `HH:MM`
+		* - same calendar year → `MM-DD HH:MM`
+		* - otherwise → `YYYY-MM-DD HH:MM`
+		*
+		* Returns `''` for a missing/invalid timestamp (e.g. a live node that never
+		* reported one), so callers can hide the time line without branching.
+		*/
+		function formatQuestionTime(time, now) {
+			if (!Number.isFinite(time) || time <= 0) return "";
+			const d = new Date(time);
+			const hm = `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+			if (isSameDay(time, now)) return hm;
+			const md = `${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+			if (d.getFullYear() === new Date(now).getFullYear()) return `${md} ${hm}`;
+			return `${d.getFullYear()}-${md} ${hm}`;
+		}
 		//#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;pointer-events:auto;flex-direction:column;flex:0 auto;align-items:center;gap:6px;width:100%;min-height:0;max-height:60%;margin:auto 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,.TWf_pa_dot.TWf_pa_focused,.TWf_pa_dot.TWf_pa_active{background:var(--dsw-alias-brand-primary)}.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_hint{z-index:30;background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l1);max-width:260px;color:var(--dsw-alias-label-secondary);pointer-events:none;border-radius:6px;padding:6px 10px;font-size:12px;line-height:16px;position:fixed;box-shadow:0 2px 10px #0000002e}.TWf_pa_cascade{z-index:20;pointer-events:none;flex-direction:column;align-items:flex-start;gap:6px;display:flex;position:fixed}.TWf_pa_card{background:var(--dsw-alias-bg-layer-1);border:1px solid var(--dsw-alias-border-l1);width:380px;color:var(--dsw-alias-label-primary);white-space:normal;word-break:break-word;pointer-events:auto;cursor:pointer;border-radius:10px;padding:8px 12px 10px;font-size:13px;line-height:18px;transition:border-color .12s,box-shadow .12s;box-shadow:0 4px 14px #0000002e}.TWf_pa_card:hover{border-color:var(--dsw-alias-brand-primary);box-shadow:0 4px 16px #00000042}.TWf_pa_cardSelected{border-color:var(--dsw-alias-brand-primary)}.TWf_pa_cardTitle{color:var(--dsw-alias-label-tertiary);margin-bottom:4px;font-size:11px;font-weight:600}.TWf_pa_cardBody{scrollbar-width:thin;max-height:96px;overflow-y:auto}.TWf_pa_cardClamp{color:var(--dsw-alias-label-primary);word-break:break-word;-webkit-box-orient:vertical;font-size:13px;line-height:18px;display:-webkit-box;overflow:hidden}.TWf_pa_cardLine+.TWf_pa_cardLine{border-top:1px solid var(--dsw-alias-border-l1);margin-top:6px;padding-top:6px}.TWf_pa_cardTime{color:var(--dsw-alias-label-tertiary);margin-top:6px;font-size:11px}.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");
@@ -111,27 +192,47 @@ window.__ModuleLoader__.load({
 		}
 		var question_nav_module_css_default = {
 			"active": "TWf_pa_active",
+			"card": "TWf_pa_card",
+			"cardBody": "TWf_pa_cardBody",
+			"cardClamp": "TWf_pa_cardClamp",
+			"cardLine": "TWf_pa_cardLine",
+			"cardSelected": "TWf_pa_cardSelected",
+			"cardTime": "TWf_pa_cardTime",
+			"cardTitle": "TWf_pa_cardTitle",
+			"cascade": "TWf_pa_cascade",
 			"count": "TWf_pa_count",
 			"dot": "TWf_pa_dot",
 			"dots": "TWf_pa_dots",
 			"empty": "TWf_pa_empty",
+			"focused": "TWf_pa_focused",
+			"hint": "TWf_pa_hint",
 			"list": "TWf_pa_list",
 			"rail": "TWf_pa_rail",
-			"tooltip": "TWf_pa_tooltip",
-			"tooltipLine": "TWf_pa_tooltipLine",
-			"tooltipTitle": "TWf_pa_tooltipTitle"
+			"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"
 		};
 		//#endregion
 		//#region src/client/QuestionNavStrip.tsx
 		/**
 		* Question-nav minimap. Renders a vertical column of small round dots overlaid
 		* on the LEFT edge of the conversation column (via the frame-wide
-		* `shell.overlay` floating layer), vertically centered: one dot per turn that
-		* claimed at least one user question — strictly aligned with the Trajectory
-		* view's turn numbering (turns without a question produce no dot). Hover
-		* enlarges a dot and shows an instant tooltip (portal-rendered, no native
-		* delay) with the turn label and the turn's question text(s); clicking jumps
-		* the chat to that turn's first question.
+		* `shell.overlay` floating layer): one dot per turn that claimed at least one
+		* user question — strictly aligned with the Trajectory view's turn numbering
+		* (turns without a question produce no dot). The dot column is vertically
+		* centered and clamped to at most 60% of the conversation height, scrolling
+		* within that band when the session has more dots than fit.
+		*
+		* Hovering a dot "selects" it: the selected dot plus its two immediate
+		* neighbors on each side magnify (progressively smaller with distance), the
+		* selected dot reveals a frosted question card (turn label, full question
+		* text, sent time) with a decorative stack of blurred cards fanning out
+		* below it, and the rail auto-centers the selected dot. Clicking jumps the
+		* chat to that turn's first question.
 		*
 		* Data source: the host-folded `questionIndex` session projection (whole
 		* history, persisted host-side, pushed live through session/projection
@@ -160,8 +261,8 @@ window.__ModuleLoader__.load({
 			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. */
+		*  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++) {
@@ -179,10 +280,25 @@ window.__ModuleLoader__.load({
 			const [dots, setDots] = (0, react.useState)([]);
 			const [jumpingKey, setJumpingKey] = (0, react.useState)(null);
 			const [hint, setHint] = (0, react.useState)(null);
-			const [tooltip, setTooltip] = (0, react.useState)(null);
+			const [focus, setFocus] = (0, react.useState)(null);
+			const [align, setAlign] = (0, react.useState)(() => props.align());
 			const panelRef = (0, react.useRef)(null);
+			const listRef = (0, react.useRef)(null);
 			const hintTimerRef = (0, react.useRef)(null);
+			const clearFocusTimerRef = (0, react.useRef)(null);
 			const lastDotsRef = (0, react.useRef)([]);
+			const lastFocusedKeyRef = (0, react.useRef)(null);
+			const cancelClearFocus = () => {
+				if (clearFocusTimerRef.current !== null) {
+					window.clearTimeout(clearFocusTimerRef.current);
+					clearFocusTimerRef.current = null;
+				}
+			};
+			const scheduleClearFocus = () => {
+				cancelClearFocus();
+				clearFocusTimerRef.current = window.setTimeout(() => setFocus(null), 240);
+			};
+			(0, react.useEffect)(() => props.subscribeAlign(() => setAlign(props.align())), [props]);
 			const showHint = (message) => {
 				setHint(message);
 				if (hintTimerRef.current !== null) window.clearTimeout(hintTimerRef.current);
@@ -256,11 +372,21 @@ window.__ModuleLoader__.load({
 					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;
+					}
 					const left = `${convRect.left - frameRect.left}px`;
-					if (panel.style.top === top && panel.style.height === height && panel.style.left === left) return false;
+					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 = () => {
@@ -295,9 +421,22 @@ window.__ModuleLoader__.load({
 					observer?.disconnect();
 					window.removeEventListener("resize", wake);
 				};
-			}, [visible]);
+			}, [visible, align]);
+			(0, react.useLayoutEffect)(() => {
+				const key = focus?.key ?? null;
+				if (lastFocusedKeyRef.current === key) return;
+				lastFocusedKeyRef.current = key;
+				if (key === null) return;
+				const list = listRef.current;
+				if (list === null) return;
+				const target = list.querySelector("[data-question-nav-focused=\"true\"]");
+				if (target === null) return;
+				const center = target.offsetTop - list.offsetTop - (list.clientHeight - target.offsetHeight) / 2;
+				list.scrollTop = Math.max(0, Math.min(center, list.scrollHeight - list.clientHeight));
+			}, [focus]);
 			(0, react.useEffect)(() => () => {
 				if (hintTimerRef.current !== null) window.clearTimeout(hintTimerRef.current);
+				if (clearFocusTimerRef.current !== null) window.clearTimeout(clearFocusTimerRef.current);
 			}, []);
 			if (!visible) return null;
 			const onJump = (dot) => {
@@ -306,28 +445,37 @@ window.__ModuleLoader__.load({
 				props.jump(current, dot.key);
 				window.setTimeout(() => setJumpingKey((k) => k === dot.key ? null : k), 600);
 			};
-			const openTooltip = (dot, target) => {
+			const openFocus = (dot, target) => {
+				const index = dots.findIndex((d) => d.key === dot.key);
+				if (index < 0) return;
+				cancelClearFocus();
 				const r = target.getBoundingClientRect();
-				setTooltip({
-					title: dot.turn === null ? null : `Turn ${dot.turn}`,
-					lines: dot.texts,
-					left: r.right + 10,
-					top: r.top
+				const horizontal = align === "right" ? { right: window.innerWidth - r.left + 10 } : { left: r.right + 10 };
+				const lo = Math.max(0, index - 2);
+				const hi = Math.min(dots.length - 1, index + 2);
+				const items = [];
+				for (let i = lo; i <= hi; i++) items.push({
+					dot: dots[i],
+					distance: Math.abs(i - index)
+				});
+				setFocus({
+					key: dot.key,
+					items,
+					centerY: r.top + r.height / 2,
+					...horizontal
 				});
 			};
 			const t = props.t;
+			const selectedIndex = focus === null ? -1 : dots.findIndex((d) => d.key === focus.key);
 			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", {
-						className: question_nav_module_css_default.hint,
-						role: "status",
-						children: hint
-					}) : null,
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						ref: listRef,
 						className: question_nav_module_css_default.list,
+						onMouseLeave: scheduleClearFocus,
 						children: dots.length === 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 							className: question_nav_module_css_default.empty,
 							children: t("strip.empty")
@@ -336,33 +484,217 @@ window.__ModuleLoader__.load({
 							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 								className: question_nav_module_css_default.count,
 								children: dots.length
-							}), dots.map((dot) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-								className: jumpingKey === dot.key ? `${question_nav_module_css_default.dot} ${question_nav_module_css_default.active}` : question_nav_module_css_default.dot,
-								"aria-label": dot.texts[0] ?? "",
-								onMouseEnter: (e) => openTooltip(dot, e.currentTarget),
-								onMouseLeave: () => setTooltip(null),
-								onClick: () => onJump(dot)
-							}, dot.key))]
+							}), dots.map((dot, index) => {
+								const isFocused = focus !== null && focus.key === dot.key;
+								const tier = selectedIndex < 0 ? null : focusTier(index - selectedIndex);
+								const scale = jumpingKey === dot.key ? 1.6 : tier !== null ? focusScale(tier) : 1;
+								const cls = [question_nav_module_css_default.dot];
+								if (isFocused) cls.push(question_nav_module_css_default.focused);
+								if (jumpingKey === dot.key) cls.push(question_nav_module_css_default.active);
+								return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+									className: cls.join(" "),
+									style: { transform: `scale(${scale})` },
+									"data-question-nav-focused": isFocused ? "true" : void 0,
+									"data-question-nav-index": index,
+									"aria-label": dot.texts[0] ?? "",
+									onMouseEnter: (e) => openFocus(dot, e.currentTarget),
+									onClick: () => onJump(dot)
+								}, dot.key);
+							})]
 						})
 					}),
-					tooltip !== null ? (0, react_dom.createPortal)(/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-						className: question_nav_module_css_default.tooltip,
+					hint !== null ? (0, react_dom.createPortal)(/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: question_nav_module_css_default.hint,
+						style: align === "right" ? {
+							right: 60,
+							top: 20
+						} : {
+							left: 60,
+							top: 20
+						},
+						children: hint
+					}), document.body) : null,
+					focus !== null ? (0, react_dom.createPortal)(/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: question_nav_module_css_default.cascade,
 						style: {
-							left: tooltip.left,
-							top: tooltip.top
+							...focus.left !== void 0 ? { left: focus.left } : {},
+							...focus.right !== void 0 ? { right: focus.right } : {},
+							top: focus.centerY,
+							transform: "translateY(-50%)"
 						},
-						children: [tooltip.title !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-							className: question_nav_module_css_default.tooltipTitle,
-							children: tooltip.title
-						}) : null, tooltip.lines.map((line, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-							className: question_nav_module_css_default.tooltipLine,
-							children: line
-						}, index))]
+						onMouseEnter: cancelClearFocus,
+						onMouseLeave: scheduleClearFocus,
+						children: focus.items.map((item) => {
+							const metrics = focusCardMetrics(item.distance);
+							if (metrics === null) return null;
+							const isSelected = item.distance === 0;
+							const text = item.dot.texts.join(" · ");
+							const cls = isSelected ? `${question_nav_module_css_default.card} ${question_nav_module_css_default.cardSelected}` : question_nav_module_css_default.card;
+							return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								className: cls,
+								role: "button",
+								tabIndex: -1,
+								style: {
+									width: metrics.widthPx,
+									filter: `brightness(${metrics.brightness})`
+								},
+								onClick: () => onJump(item.dot),
+								children: [
+									isSelected && item.dot.turn !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+										className: question_nav_module_css_default.cardTitle,
+										children: ["Turn ", item.dot.turn]
+									}) : null,
+									/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+										className: isSelected ? question_nav_module_css_default.cardBody : question_nav_module_css_default.cardClamp,
+										style: isSelected ? void 0 : {
+											WebkitLineClamp: metrics.maxLines,
+											fontSize: metrics.fontSize
+										},
+										children: isSelected ? item.dot.texts.map((line, lineIndex) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+											className: question_nav_module_css_default.cardLine,
+											children: line
+										}, lineIndex)) : text
+									}),
+									/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+										className: question_nav_module_css_default.cardTime,
+										children: formatQuestionTime(item.dot.time, Date.now())
+									})
+								]
+							}, item.dot.key);
+						})
 					}), document.body) : null
 				]
 			});
 		}
 		//#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
@@ -373,14 +705,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
@@ -588,7 +930,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();
@@ -608,7 +950,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)
 			};
 		}
 		/**
@@ -622,7 +967,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",
@@ -630,6 +977,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;