dsh-width-tiers 1.0.7 → 1.0.8

package/README.md

@@ -28,9 +28,13 @@ budget" — so the built-in drag handles keep working:
 | full 全宽 | column minus the handle budget (fills the available width) | collapsed to the icon rail |
 | custom 自定义 | your dragged width, re-selectable from the menu | untouched |
 
-The menu and the button title always show the width a tier resolves to **at
-the current column**, so on narrow windows a clamped tier reads its real
-value (e.g. `宽 668px`) instead of its nominal one.
+The menu and the button title show nominal px for the fixed tiers (medium
+1120px, wide 1280px, ultra 1400px). Standard shows the app default px it
+resolves right now (`clamp(680px, column × 0.64, 920px)`, e.g. 710px); full
+shows the live maximum (`column − 176px`, e.g. 934px); custom shows its
+recorded width or "Not set". The app still clamps the applied width to
+"column − 176px"; on a narrow window a higher tier therefore behaves like
+"full".
 
 On narrow windows wider tiers are clamped to the available column, so nothing
 overflows under the sidebar.
@@ -41,6 +45,12 @@ a glance (all lit for custom). Dragging one of the app's native edge handles
 switches the picker to the custom tier — the plugin stands aside for native
 drags.
 
+Before the first drag, picking custom does not silently keep a width: a guide
+appears at the conversation's right edge and highlights the width handle.
+While dragging, a bubble shows the live transcript width; releasing records it
+as the custom value. Every later handle drag opens the same highlight + live
+readout, no matter which tier was active.
+
 ## Install
 
 ```bash
@@ -95,10 +105,12 @@ language, and Chinese is the last resort. No plugin-side setting needed.
 ## Limitations
 
 - Content width cannot exceed the window: on a narrow window, wider tiers are
-  capped by the available column (the menu shows the capped value). Use
-  `full` (which also collapses the sidebar) for the maximum.
+  capped by the available column (the picker keeps showing the nominal value;
+  the live bubble during a drag shows the applied width). Use `full` (which
+  also collapses the sidebar) for the maximum.
 - Requires the DSH Web client plugin system (dsh ≥ 0.1.0-rc.x with a `web`
-  profile). Verified on dsh 0.1.7-alpha.1 and 0.2.0-rc.2.
+  profile). Verified on dsh 0.1.7-alpha.1 and 0.2.0-rc.2; the 0.2.1-rc.1
+  width axis matches by bundle diff.
 
 ## Uninstall
 

package/README.zh.md

@@ -25,8 +25,11 @@ DSH Web 把消息列——包括里面的所有表格——的宽度限制在
 | 全宽 | 列宽减手柄预留（占满可用宽度） | 收起为图标轨道 |
 | 自定义 | 拖拽原生手柄得出，可在菜单回切 | 不动 |
 
-菜单与按钮标题显示的是**当前列宽下实际生效的 px**：窄窗口下被钳制的档位会
-显示真实值（如「宽 668px」），而不是标称值。
+菜单与按钮标题中：中等 / 宽 / 超宽显示**固定标称值**（1120 / 1280 / 1400px），
+标准显示应用当前默认值（`clamp(680px, 列宽 × 0.64, 920px)`，如 710px），全宽
+显示当前列宽下的最大实际值（列宽 − 176px，如 934px），自定义显示已记录的
+宽度或「未设置」。实际生效宽度仍由应用按「列宽 − 176px」钳制；窄窗口下
+选定较高档位时，效果等同于「全宽」。
 
 窄窗口下超宽档位会自动被钳到可用宽度，不会溢出被侧栏覆盖。
 
@@ -34,6 +37,10 @@ DSH Web 把消息列——包括里面的所有表格——的宽度限制在
 的五条横条图标也直观显示当前档位（自定义档全亮）。拖动应用自带的
 对话区边缘手柄会自动切到「自定义」档，插件让位于原生拖拽。
 
+若从未拖拽过，点击「自定义」不会静默套用某个宽度：右侧对话边缘会出现
+拖拽引导，手柄高亮；拖拽时气泡实时显示对话列宽度，松开后记为该档的值。
+之后每次拖拽手柄（无论从哪个档位开始）都会重新高亮手柄并显示实时宽度。
+
 ## 安装
 
 ```bash
@@ -80,10 +87,12 @@ bundle patch 会自动插入 `dsh-width-tiers` 加载项——无需手动改
 
 ## 已知限制
 
-- 内容宽度不可能超过窗口：窗口窄时，高档位会被可用列宽截断（菜单会显示
-  截断后的实际值）；想要最大空间请用「全宽」（同时收起侧边栏）。
+- 内容宽度不可能超过窗口：窗口窄时，高档位会被可用列宽截断（选择器仍显示
+  标称值，实际宽度以拖拽气泡/窗口效果为准）；想要最大空间请用「全宽」
+  （同时收起侧边栏）。
 - 依赖 DSH Web 客户端插件体系（带 web profile 的 dsh ≥ 0.1.0-rc.x）。
-  已在 dsh 0.1.7-alpha.1 与 0.2.0-rc.2 上验证。
+  已在 dsh 0.1.7-alpha.1、0.2.0-rc.2 上验证；0.2.1-rc.1 的宽度轴经 bundle
+  对比确认一致。
 
 ## 卸载
 

package/lib/client.js

@@ -29,11 +29,17 @@ window.__ModuleLoader__.load({
 		 *   全宽 full      column max (sidebar collapsed to the icon rail)
 		 *   自定义 custom  user-dragged width (plugin hands width over to
 		 *                  the app's native handles; the dragged value stays
-		 *                  re-selectable from the menu)
+		 *                  re-selectable from the menu). Before the first
+		 *                  drag, picking it opens a guide at the right edge
+		 *                  and the live column width is shown while dragging.
 		 *
-		 * The menu and title always show the px a tier resolves to at the
-		 * CURRENT column (see `tierValueText`), so a clamped tier never
-		 * claims its nominal width on a narrow window.
+		 * The menu and title show fixed px for medium/wide/ultra
+		 * (1120/1280/1400), the live app default px for standard, the live
+		 * maximum (column − 176) for full, and the recorded drag width or
+		 * "未设置" for custom. The app still clamps every applied px to
+		 * column − 176. Every handle press (not just the first custom one)
+		 * opens the live width readout, so repeat drags keep the highlight
+		 * and the px bubble.
 		 *
 		 *  - Panels are driven through the layout service (ctx.layout), never
 		 *    by simulating clicks.
@@ -59,9 +65,10 @@ window.__ModuleLoader__.load({
 		 * the horizontal budget both width handles + safe edges reserve. */
 		const CONTENT_MIN_PX = 640;
 		const CONTENT_EDGE_BUDGET_PX = 176;
-		/* The app's default transcript width (resolveContentWidth's
-		 * no-preference branch): clamp(680px, column × 0.64, 920px). Used to
-		 * show what `standard` actually resolves to at the current column. */
+		/* Nominal content widths of the fixed tiers (px). */
+		const NOMINAL_WIDTH_PX = { medium: 1120, wide: 1280, ultra: 1400 };
+		/* The app's no-preference formula: clamp(680px, column × 0.64, 920px).
+		 * Used as the last-resort live readout before the first drag. */
 		const DEFAULT_MIN_PX = 680;
 		const DEFAULT_MAX_PX = 920;
 		const DEFAULT_COLUMN_RATIO = 0.64;
@@ -87,6 +94,8 @@ window.__ModuleLoader__.load({
 			"tier.ultra": "超宽",
 			"tier.full": "全宽",
 			"tier.custom": "自定义",
+			"value.custom.unset": "未设置",
+			"guide.hint": "拖拽右侧边缘调整对话宽度",
 			"button.aria": "对话区宽度档位：{label}（{value}），点击选择档位",
 			"button.title.summary": "对话区宽度档位：{label}（{value}）",
 			"button.title.hint": "点击选择：{list}"
@@ -99,22 +108,25 @@ window.__ModuleLoader__.load({
 			"tier.ultra": "Ultra",
 			"tier.full": "Full",
 			"tier.custom": "Custom",
+			"value.custom.unset": "Not set",
+			"guide.hint": "Drag the right edge to resize",
 			"button.aria": "Chat width tier: {label} ({value}). Click to choose a tier.",
 			"button.title.summary": "Chat width tier: {label} ({value})",
 			"button.title.hint": "Click to choose: {list}"
 		};
 		//#endregion
 
-		/* Tier ids and label keys only — every displayed width is resolved at
-		 * render time from the live column (see tierValueText), so the menu
-		 * never claims a width the app would not actually apply. */
+		/* Tier ids and label keys only — the picker resolves displayed values
+		 * in tierValueText (fixed px for medium/wide/ultra, live px for
+		 * standard/full, recorded px for custom). */
 		const TIERS = [
 			{ id: "standard", key: "tier.standard" },
 			{ id: "medium", key: "tier.medium" },
 			{ id: "wide", key: "tier.wide" },
 			{ id: "ultra", key: "tier.ultra" },
 			{ id: "full", key: "tier.full" },
-			/* Reached only by dragging a native width handle. */
+			/* Reached by dragging a native width handle, or by picking it in
+			 * the menu and following the right-edge drag guide. */
 			{ id: "custom", key: "tier.custom" }
 		];
 
@@ -141,10 +153,15 @@ window.__ModuleLoader__.load({
 			"#dsh-width-menu[hidden]{display:none}",
 			"#dsh-width-menu button{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:8px 12px;border:none;border-radius:8px;background:transparent;color:var(--dsw-alias-label-primary);font:inherit;font-size:13px;line-height:18px;text-align:left;cursor:pointer}",
 			"#dsh-width-menu button:hover{background:var(--dsw-alias-interactive-bg-hover)}",
-			"#dsh-width-menu button.disabled{opacity:.45;cursor:default;pointer-events:none}",
 			"#dsh-width-menu button.selected{background:var(--dsw-alias-interactive-bg-hover-solid);color:var(--dsw-alias-state-business-primary)}",
 			"#dsh-width-menu .dshwm-value{color:var(--dsw-alias-label-tertiary);font-size:12px}",
-			"#dsh-width-menu button.selected .dshwm-value{color:var(--dsw-alias-state-business-primary)}"
+			"#dsh-width-menu button.selected .dshwm-value{color:var(--dsw-alias-state-business-primary)}",
+			"#dsh-width-guide{position:fixed;z-index:1001;display:flex;align-items:center;gap:8px;padding:8px 12px;border:1px solid var(--dsw-alias-border-l2);border-radius:10px;background:var(--dsw-specific-menu);color:var(--dsw-alias-label-primary);font-size:12px;line-height:16px;box-shadow:0 8px 28px rgba(0,0,0,.24);pointer-events:none;white-space:nowrap;transform:translateY(-50%)}",
+			"#dsh-width-guide[hidden]{display:none}",
+			"#dsh-width-guide svg{flex:none;color:var(--dsw-alias-state-business-primary)}",
+			"#dsh-width-guide[data-mode=live]{font-size:13px;font-weight:600;font-variant-numeric:tabular-nums}",
+			"body[data-dsh-width-guide] [data-width-handle=right]{background:linear-gradient(to bottom,transparent calc(50% - 64px),color-mix(in srgb,var(--dsw-alias-state-business-primary) 18%,transparent) calc(50% - 64px),color-mix(in srgb,var(--dsw-alias-state-business-primary) 18%,transparent) calc(50% + 64px),transparent calc(50% + 64px));border-radius:3px}",
+			"body[data-dsh-width-guide] [data-width-handle=right]::after{opacity:1}"
 		].join("");
 		//#endregion
 
@@ -299,9 +316,10 @@ window.__ModuleLoader__.load({
 				function tierPx(tier, root) {
 					const cap = Math.max(CONTENT_MIN_PX, root.offsetWidth - CONTENT_EDGE_BUDGET_PX);
 					switch (tier) {
-						case "medium": return Math.min(1120, cap);
-						case "wide": return Math.min(1280, cap);
-						case "ultra": return Math.min(1400, cap);
+						case "medium":
+						case "wide":
+						case "ultra":
+							return Math.min(NOMINAL_WIDTH_PX[tier], cap);
 						case "full": return cap;
 						case "custom": {
 							const dragged = readStoredNumber(CUSTOM_KEY);
@@ -311,15 +329,23 @@ window.__ModuleLoader__.load({
 					}
 				}
 
-				/* The px a tier resolves to right now, including the app's own
-				 * default formula for `standard`; null when the tier has no
-				 * width of its own yet (custom before the first drag). */
-				function resolvedWidthPx(tier, root) {
-					if (tier === "standard") {
-						const column = root.offsetWidth;
-						return Math.round(Math.max(DEFAULT_MIN_PX, Math.min(column * DEFAULT_COLUMN_RATIO, DEFAULT_MAX_PX)));
-					}
-					return tierPx(tier, root);
+				/* The transcript width the app currently resolves for the live
+				 * column (after its own clamp), used by the custom-drag guide.
+				 * During a drag the app writes the clamped px to the target's
+				 * inline `--dsh-chat-user-width`, so reading that is exact and
+				 * avoids relying on how a browser serializes a computed custom
+				 * property (which may stay as a var()/clamp() token stream). */
+				function liveWidthPx(root) {
+					const target = widthTarget(root);
+					const inline = Number.parseFloat(target.style.getPropertyValue("--dsh-chat-user-width"));
+					if (Number.isFinite(inline) && inline > 0) return Math.round(inline);
+					const raw = getComputedStyle(root).getPropertyValue("--dsh-chat-content-width");
+					const computed = Number.parseFloat(raw);
+					if (Number.isFinite(computed) && computed > 0) return Math.round(computed);
+					return Math.round(Math.max(
+						DEFAULT_MIN_PX,
+						Math.min(root.offsetWidth * DEFAULT_COLUMN_RATIO, DEFAULT_MAX_PX)
+					));
 				}
 
 				function applyContentWidth(tier) {
@@ -407,18 +433,38 @@ window.__ModuleLoader__.load({
 					return `<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true" focusable="false">${bars}</svg>`;
 				}
 
-				/* Display value for a tier: the px it resolves to at the live
-				 * column (what the app would actually apply), so narrow windows
-				 * show the clamped value instead of the nominal one. Falls back
-				 * to the recorded drag when the width root is not mounted. */
+				/* Value shown in the picker. Fixed tiers advertise their
+				 * nominal px; standard and full are inherently relative to the
+				 * current column, so they show the px the app resolves right
+				 * now (full is the column's maximum, not a word). */
 				function tierValueText(tierId) {
-					const root = findWidthRoot();
-					if (root !== null) {
-						const px = resolvedWidthPx(tierId, root);
-						if (px !== null) return `${px}px`;
+					switch (tierId) {
+						case "standard": {
+							const root = findWidthRoot();
+							if (root === null) return "—";
+							return `${Math.round(Math.max(
+								DEFAULT_MIN_PX,
+								Math.min(root.offsetWidth * DEFAULT_COLUMN_RATIO, DEFAULT_MAX_PX)
+							))}px`;
+						}
+						case "medium":
+						case "wide":
+						case "ultra":
+							return `${NOMINAL_WIDTH_PX[tierId]}px`;
+						case "full": {
+							const root = findWidthRoot();
+							if (root === null) return "—";
+							return `${Math.round(Math.max(
+								CONTENT_MIN_PX,
+								root.offsetWidth - CONTENT_EDGE_BUDGET_PX
+							))}px`;
+						}
+						case "custom": {
+							const dragged = readStoredNumber(CUSTOM_KEY);
+							return dragged === null ? t("value.custom.unset") : `${Math.round(dragged)}px`;
+						}
+						default: return "—";
 					}
-					const dragged = readStoredNumber(CUSTOM_KEY);
-					return dragged === null ? "—" : `${Math.round(dragged)}px`;
 				}
 
 				function syncButton() {
@@ -450,7 +496,14 @@ window.__ModuleLoader__.load({
 					item.innerHTML = `<span class="dshwm-label">${t(def.key)}</span><span class="dshwm-value">${tierValueText(def.id)}</span>`;
 					item.addEventListener("click", (e) => {
 						if (e && e.stopPropagation) e.stopPropagation();
-						if (item.classList.contains("disabled")) return;
+						/* Custom before the first drag has no width of its own:
+						 * open the right-edge guide instead of applying a value. */
+						if (def.id === "custom" && readStoredNumber(CUSTOM_KEY) === null) {
+							beginCustomGuide();
+							hideMenu();
+							return;
+						}
+						endGuide(false);
 						applyTier(def.id);
 						hideMenu();
 					});
@@ -476,10 +529,6 @@ window.__ModuleLoader__.load({
 						if (labelEl) setText(labelEl, t(tierOf(id).key));
 						const valueEl = items[i].querySelector(".dshwm-value");
 						if (valueEl) setText(valueEl, tierValueText(id));
-						/* custom is inert until the user has dragged once */
-						const disabled = id === "custom" && readStoredNumber(CUSTOM_KEY) === null;
-						items[i].classList.toggle("disabled", disabled);
-						items[i].setAttribute("aria-disabled", String(disabled));
 					}
 				}
 
@@ -501,15 +550,151 @@ window.__ModuleLoader__.load({
 				});
 
 				const onDocClick = (e) => {
-					if (menu.hidden) return;
-					if (e.target !== btn && !menu.contains(e.target)) hideMenu();
+					if (!menu.hidden && e.target !== btn && !menu.contains(e.target)) hideMenu();
+					/* Clicking anywhere but the guide's handle cancels a
+					 * pending custom guide and restores the previous tier. */
+					if (guideActive && !guideDragging && e.target !== btn && !menu.contains(e.target) && !isHandleEvent(e)) {
+						endGuide(true);
+					}
 				};
 				const onDocKey = (e) => {
-					if (e.key === "Escape" && !menu.hidden) hideMenu();
+					if (e.key !== "Escape") return;
+					if (!menu.hidden) hideMenu();
+					if (guideActive) endGuide(true);
 				};
 				document.addEventListener("click", onDocClick);
 				document.addEventListener("keydown", onDocKey);
 
+				/* ---- custom-drag guide ----
+				 * A first-time `custom` pick has no recorded width. Instead of
+				 * silently keeping the current width, point at the app's
+				 * right-edge width handle and show the live transcript width
+				 * while the user drags. The guide never writes the width
+				 * itself: the app's native drag does (and wins the cascade),
+				 * and the plugin only records the settled value on release. */
+				const guide = document.createElement("div");
+				guide.id = "dsh-width-guide";
+				guide.setAttribute("aria-hidden", "true");
+				guide.hidden = true;
+				guide.innerHTML =
+					'<svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true" focusable="false">' +
+					'<path d="M6 3 2 8l4 5M10 3l4 5-4 5" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>' +
+					'<span class="dshwg-text"></span>';
+				const guideTextEl = guide.querySelector(".dshwg-text");
+
+				let guideActive = false;
+				let guideDragging = false;
+				/* true while the bubble came from picking custom in the menu (its
+				 * cancel path restores the previous tier). Direct handle drags
+				 * open the same bubble but never "cancel" a tier. */
+				let guideFromMenu = false;
+				let guideHideTimer = null;
+				let tierBeforeGuide = "standard";
+
+				/* The px the app currently resolves for the transcript, after
+				 * its own clamp — what the guide's live readout shows. */
+				function guideValueText() {
+					const root = findWidthRoot();
+					const px = root === null ? null : liveWidthPx(root);
+					return px === null ? "—" : `${px}px`;
+				}
+
+				/* Keep the bubble beside the right handle (it moves with the
+				 * dragged edge); fall back to the frame's right edge when the
+				 * handle is not mounted yet (hero / settling phase). */
+				function positionGuide() {
+					if (!guideActive) return;
+					const handle = document.querySelector('[data-width-handle="right"]');
+					const viewport = window.innerWidth || 0;
+					if (handle === null || viewport === 0) {
+						guide.style.left = "auto";
+						guide.style.right = "24px";
+						guide.style.top = "50%";
+						return;
+					}
+					const rect = handle.getBoundingClientRect();
+					const gap = 10;
+					const width = guide.offsetWidth || 180;
+					guide.style.top = `${rect.top + rect.height / 2}px`;
+					guide.style.right = "auto";
+					if (viewport - rect.right >= width + gap) {
+						guide.style.left = `${rect.right + gap}px`;
+					} else {
+						guide.style.left = `${Math.max(8, rect.left - gap - width)}px`;
+					}
+				}
+
+				function setGuideText(mode, text) {
+					guide.dataset.mode = mode;
+					setText(guideTextEl, text);
+				}
+
+				function startGuide() {
+					guideFromMenu = true;
+					guideActive = true;
+					guideDragging = false;
+					guide.hidden = false;
+					body().setAttribute("data-dsh-width-guide", "custom");
+					setGuideText("hint", t("guide.hint"));
+					positionGuide();
+				}
+
+				/* Every handle press shows the live readout, not just the first
+				 * guided drag — a repeat custom drag must keep the handle
+				 * highlight and the width bubble. */
+				function startLiveGuide() {
+					window.clearTimeout(guideHideTimer);
+					guideActive = true;
+					guideDragging = true;
+					guide.hidden = false;
+					body().setAttribute("data-dsh-width-guide", "custom");
+					setGuideText("live", guideValueText());
+					positionGuide();
+				}
+
+				function beginCustomGuide() {
+					/* Remember the tier to restore on cancel only on the first
+					 * entry; re-picking custom while the guide is open must not
+					 * make "custom" the restore target. */
+					if (!guideActive) {
+						tierBeforeGuide = currentTier();
+						applyTier("custom");
+					}
+					startGuide();
+				}
+
+				/* Show the settled width briefly, then remove the guide. */
+				function finishGuide() {
+					if (!guideActive) return;
+					guideDragging = false;
+					setGuideText("live", guideValueText());
+					window.clearTimeout(guideHideTimer);
+					guideHideTimer = window.setTimeout(() => endGuide(false), 800);
+				}
+
+				/* `restoreTier` is for cancelling a menu-opened guide (click-away /
+				 * Escape): if it never recorded a width, go back to the tier the
+				 * user had before opening it. Drag-opened bubbles keep custom. */
+				function endGuide(restoreTier) {
+					if (!guideActive) return;
+					guideActive = false;
+					guideDragging = false;
+					window.clearTimeout(guideHideTimer);
+					guide.hidden = true;
+					guide.dataset.mode = "hint";
+					body().removeAttribute("data-dsh-width-guide");
+					const restore = restoreTier && guideFromMenu && readStoredNumber(CUSTOM_KEY) === null;
+					guideFromMenu = false;
+					if (restore) applyTier(tierBeforeGuide);
+				}
+
+				const onGuidePointerMove = () => {
+					if (!guideActive || !guideDragging) return;
+					setGuideText("live", guideValueText());
+					positionGuide();
+				};
+				document.addEventListener("pointermove", onGuidePointerMove, true);
+
 				/* ---- hand the width over to the app's native drag handles ----
 				 * Pressing a `[data-width-handle]` means the user is taking the
 				 * width over: switch to the `custom` tier so healing stops
@@ -521,7 +706,9 @@ window.__ModuleLoader__.load({
 					e.target instanceof Element && e.target.closest("[data-width-handle]") !== null;
 
 				const onHandlePointerDown = (e) => {
-					if (!isHandleEvent(e) || currentTier() === "custom") return;
+					if (!isHandleEvent(e)) return;
+					startLiveGuide();
+					if (currentTier() === "custom") return;
 					body().setAttribute("data-dsh-width", "custom");
 					try {
 						window.localStorage.setItem(KEY, "custom");
@@ -536,16 +723,19 @@ window.__ModuleLoader__.load({
 				const onHandlePointerUp = (e) => {
 					if (!isHandleEvent(e)) return;
 					const root = findWidthRoot();
-					if (root === null) return;
-					const px = Number.parseFloat(
-						widthTarget(root).style.getPropertyValue("--dsh-chat-user-width")
-					);
-					if (!Number.isFinite(px) || px <= 0) return;
-					try {
-						window.localStorage.setItem(CUSTOM_KEY, String(Math.round(px)));
-					} catch (err) {
-						/* ignore */
+					if (root !== null) {
+						const px = Number.parseFloat(
+							widthTarget(root).style.getPropertyValue("--dsh-chat-user-width")
+						);
+						if (Number.isFinite(px) && px > 0) {
+							try {
+								window.localStorage.setItem(CUSTOM_KEY, String(Math.round(px)));
+							} catch (err) {
+								/* ignore */
+							}
+						}
 					}
+					if (guideActive) finishGuide();
 					syncButton();
 					syncMenu();
 				};
@@ -564,6 +754,9 @@ window.__ModuleLoader__.load({
 				const renderTexts = () => {
 					syncButton();
 					syncMenu();
+					if (guideActive && !guideDragging && guide.dataset.mode === "hint") {
+						setText(guideTextEl, t("guide.hint"));
+					}
 				};
 				const unsubscribeLocale = ctx.locale.subscribe(renderTexts);
 
@@ -588,6 +781,7 @@ window.__ModuleLoader__.load({
 					}
 					body().appendChild(btn);
 					body().appendChild(menu);
+					body().appendChild(guide);
 					syncButton();
 					const saved = getSavedTier();
 					if (saved !== "standard") applyTier(saved);
@@ -648,6 +842,9 @@ window.__ModuleLoader__.load({
 				}
 
 				function heal(fromObserver) {
+					/* The right handle only mounts in the active phase; keep the
+					 * guide pinned to it once the chat tree settles. */
+					if (guideActive) positionGuide();
 					const tier = currentTier();
 					if (tier === "standard") return;
 					const prev = widthRoot;
@@ -702,10 +899,9 @@ window.__ModuleLoader__.load({
 					fallbackTimer = setInterval(() => heal(false), FALLBACK_HEAL_MS);
 				}
 
-				/* ---- keep the displayed px honest when the column changes ----
-				 * Window resizes (and layout handle drags) change what every
-				 * tier resolves to, so re-render the copy on the next frame.
-				 * The menu is also re-synced whenever it opens. */
+				/* ---- keep the picker and the guide aligned with the live
+				 * column. Standard/full re-resolve on resize, and the guide
+				 * must stay beside the handle when the frame resizes. ---- */
 				let resizeFrame = null;
 
 				const onWindowResize = () => {
@@ -714,6 +910,7 @@ window.__ModuleLoader__.load({
 						resizeFrame = null;
 						syncButton();
 						syncMenu();
+						positionGuide();
 					});
 				};
 				window.addEventListener("resize", onWindowResize);
@@ -725,6 +922,7 @@ window.__ModuleLoader__.load({
 					clearInterval(fallbackTimer);
 					clearTimeout(timeout);
 					clearTimeout(rootRetryTimer);
+					clearTimeout(guideHideTimer);
 					if (healFrame !== null) cancelFrame(healFrame);
 					if (resizeFrame !== null) cancelFrame(resizeFrame);
 					window.removeEventListener("resize", onWindowResize);
@@ -733,8 +931,10 @@ window.__ModuleLoader__.load({
 					document.removeEventListener("keydown", onDocKey);
 					document.removeEventListener("pointerdown", onHandlePointerDown, true);
 					document.removeEventListener("pointerup", onHandlePointerUp, true);
+					document.removeEventListener("pointermove", onGuidePointerMove, true);
 					if (btn.parentNode) btn.parentNode.removeChild(btn);
 					if (menu.parentNode) menu.parentNode.removeChild(menu);
+					if (guide.parentNode) guide.parentNode.removeChild(guide);
 					if (styleTag.parentNode) styleTag.parentNode.removeChild(styleTag);
 					/* Hand the width back to the app default; the app's own
 					 * preference (which this plugin mirrors) stays so the last
@@ -744,6 +944,7 @@ window.__ModuleLoader__.load({
 						widthTarget(widthRoot).style.removeProperty("--dsh-chat-user-width");
 					}
 					body().removeAttribute("data-dsh-width");
+					body().removeAttribute("data-dsh-width-guide");
 				};
 			}, "dsh-width-tiers: ui");
 		}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-width-tiers",
-  "version": "1.0.7",
-  "description": "DSH Web client plugin: chat content width tiers (standard / medium / wide / ultra / full / custom) with a floating picker button. Drives the app's native width axis on DSH 0.1.7+ (verified on 0.2.0-rc.2), so the built-in drag handles keep working. UI copy follows the app language (zh / en).",
+  "version": "1.0.8",
+  "description": "DSH Web client plugin: chat content width tiers (standard / medium / wide / ultra / full / custom) with a floating picker button. Drives the app's native width axis on DSH 0.1.7+ (0.2.1-rc.1 width axis checked), so the built-in drag handles keep working. UI copy follows the app language (zh / en).",
   "license": "MIT",
   "author": "aaronlei",
   "publishConfig": {