dsh-width-tiers 1.0.6 → 1.0.8

package/README.md

@@ -10,11 +10,11 @@ ultra / full / custom).
 ## Why
 
 The DSH Web app caps the message column — and every table inside it — at
-`--dsh-chat-content-width` (0.1.7 default `clamp(680px, column × 0.64,
+`--dsh-chat-content-width` (0.1.7–0.2.0 default `clamp(680px, column × 0.64,
 920px)`), no matter how wide your window is, so wide tables always need
 horizontal scrolling.
 
-This plugin sets the width per tier through 0.1.7's **native width axis**
+This plugin sets the width per tier through the app's **native width axis**
 (`--dsh-chat-user-width` + the app's `dsh.conversation.contentWidth`
 preference), letting the app clamp every value to "column − 176px handle
 budget" — so the built-in drag handles keep working:
@@ -22,21 +22,35 @@ budget" — so the built-in drag handles keep working:
 | Tier | Content width | Sidebar |
 |---|---|---|
 | standard 标准 | app default | untouched |
-| medium 中等 | 960px | untouched |
+| medium 中等 | 1120px | untouched |
 | wide 宽 | 1280px | untouched |
 | ultra 超宽 | 1400px | untouched |
 | 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 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.
 
 The choice persists in `localStorage` and is restored on the next visit; the
 menu highlights the current tier, and the button's five level-bars show it at
-a glance (all lit for custom). Dragging one of 0.1.7's native edge handles
+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
@@ -62,8 +76,9 @@ Restart `dsh web` (the plugin loads at boot) and hard-refresh the page
 - `full` collapses the sidebar to the icon rail through the app's own toggle
   — it is never force-hidden or locked: click a rail icon any time to expand
   it, and it stays expanded.
-- Non-standard tiers also close the details panel (re-closed automatically if
-  reopened); `standard` leaves everything to the app.
+- The right panel (rightbar) is never touched: its track and panel are fully
+  owned by the app, and the conversation yields space to it on its own.
+  `standard` leaves the layout entirely to the app.
 
 ## Language
 
@@ -90,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. 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).
+  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

@@ -9,28 +9,38 @@ DeepSeek Harness Web GUI 的客户端插件：给对话区加**内容宽度档
 ## 为什么需要它
 
 DSH Web 把消息列——包括里面的所有表格——的宽度限制在
-`--dsh-chat-content-width`（0.1.7 默认 `clamp(680px, 列宽 × 0.64, 920px)`），
-不管窗口多宽都不变，宽表格只能横向滚动。
+`--dsh-chat-content-width`（0.1.7–0.2.0 默认
+`clamp(680px, 列宽 × 0.64, 920px)`），不管窗口多宽都不变，宽表格只能横向滚动。
 
-本插件通过 0.1.7 的**原生宽度通道**（`--dsh-chat-user-width` +
+本插件通过应用自身的**原生宽度通道**（`--dsh-chat-user-width` +
 `dsh.conversation.contentWidth` 偏好）按档位设定宽度，由应用自身钳制到
 「列宽 − 176px 手柄预留」，因此自带的原生拖拽手柄始终可用：
 
 | 档位 | 内容宽度 | 侧边栏 |
 |---|---|---|
 | 标准 | 应用默认 | 不动 |
-| 中等 | 960px | 不动 |
+| 中等 | 1120px | 不动 |
 | 宽 | 1280px | 不动 |
 | 超宽 | 1400px | 不动 |
 | 全宽 | 列宽减手柄预留（占满可用宽度） | 收起为图标轨道 |
 | 自定义 | 拖拽原生手柄得出，可在菜单回切 | 不动 |
 
+菜单与按钮标题中：中等 / 宽 / 超宽显示**固定标称值**（1120 / 1280 / 1400px），
+标准显示应用当前默认值（`clamp(680px, 列宽 × 0.64, 920px)`，如 710px），全宽
+显示当前列宽下的最大实际值（列宽 − 176px，如 934px），自定义显示已记录的
+宽度或「未设置」。实际生效宽度仍由应用按「列宽 − 176px」钳制；窄窗口下
+选定较高档位时，效果等同于「全宽」。
+
 窄窗口下超宽档位会自动被钳到可用宽度，不会溢出被侧栏覆盖。
 
 选择会记住（localStorage），下次打开自动恢复；菜单里当前档位高亮，按钮上
-的五条横条图标也直观显示当前档位（自定义档全亮）。拖动 0.1.7 自带的
+的五条横条图标也直观显示当前档位（自定义档全亮）。拖动应用自带的
 对话区边缘手柄会自动切到「自定义」档，插件让位于原生拖拽。
 
+若从未拖拽过，点击「自定义」不会静默套用某个宽度：右侧对话边缘会出现
+拖拽引导，手柄高亮；拖拽时气泡实时显示对话列宽度，松开后记为该档的值。
+之后每次拖拽手柄（无论从哪个档位开始）都会重新高亮手柄并显示实时宽度。
+
 ## 安装
 
 ```bash
@@ -55,7 +65,8 @@ bundle patch 会自动插入 `dsh-width-tiers` 加载项——无需手动改
 - 点圆形按钮 → 选择档位，当前档位高亮。
 - 「全宽」通过应用自己的收起按钮把侧边栏收成图标轨道——**不会被锁死**：
   随时点轨道图标展开，展开后保持展开。
-- 非标准档会关闭详情面板（被重新打开会自动再关）；标准档完全交给应用。
+- 插件**不碰右侧面板**：右栏的轨道与面板完全由应用管理，展开时对话内容
+  自适应让位；「标准」档完全交给应用。
 
 ## 多语言
 
@@ -76,9 +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 上验证；0.2.1-rc.1 的宽度轴经 bundle
+  对比确认一致。
 
 ## 卸载
 

package/lib/client.js

@@ -10,7 +10,7 @@ window.__ModuleLoader__.load({
 		 * dsh-width-tiers — chat content width tiers for the DSH Web GUI.
 		 *
 		 * The app derives the transcript width from
-		 * `--dsh-chat-content-width`, which 0.1.7-alpha.1 resolves as
+		 * `--dsh-chat-content-width`, which 0.1.7 and 0.2.0 resolve as
 		 * `var(--dsh-chat-user-width, clamp(680px, column * .64, 920px))` on
 		 * the conversation body. 0.1.7 also added native drag handles
 		 * (ConversationWidthControls) that publish
@@ -23,21 +23,32 @@ window.__ModuleLoader__.load({
 		 * `applyContentWidth`. Other invariants:
 		 *
 		 *   标准 standard  app default (no override)
-		 *   中等 medium    960px  (sidebar untouched)
+		 *   中等 medium    1120px (sidebar untouched)
 		 *   宽   wide      1280px (sidebar untouched)
 		 *   超宽 ultra     1400px (sidebar untouched)
 		 *   全宽 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 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.
 		 *  - The sidebar is only ever collapsed by the `full` tier, through the
 		 *    app's own toggle — never force-hidden, never locked. Going back to
 		 *    `standard` restores it only if this plugin collapsed it.
-		 *  - Non-standard tiers close the right panel (rightbar, self-heal
-		 *    while active); `standard` leaves everything to the app.
+		 *  - The rightbar is never touched: on 0.1.7+ its panel lives in its
+		 *    own seat, so closing the track would leave it overlaying the
+		 *    conversation; the app's width axis yields space on its own.
 		 *  - The chosen tier persists in localStorage and is restored on the
 		 *    next visit.
 		 *  - All copy is localized through the app's locale service: tier
@@ -54,6 +65,13 @@ window.__ModuleLoader__.load({
 		 * the horizontal budget both width handles + safe edges reserve. */
 		const CONTENT_MIN_PX = 640;
 		const CONTENT_EDGE_BUDGET_PX = 176;
+		/* 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;
 		const READY_TIMEOUT_MS = 30000;
 		/* Self-heal cadence: DOM-driven (MutationObserver scheduling on the
 		 * next animation frame — before paint, so the width never flashes
@@ -76,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}"
@@ -88,21 +108,26 @@ 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 — 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", value: "748px" },
-			{ id: "medium", key: "tier.medium", value: "960px" },
-			{ id: "wide", key: "tier.wide", value: "1280px" },
-			{ id: "ultra", key: "tier.ultra", value: "1400px" },
-			{ id: "full", key: "tier.full", value: "100%" },
-			/* Reached only by dragging a native width handle; the displayed
-			 * value is the dragged width, resolved at render time. */
-			{ id: "custom", key: "tier.custom", value: null }
+			{ 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 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" }
 		];
 
 		function tierOf(id) {
@@ -128,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
 
@@ -286,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(960, 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);
@@ -298,6 +329,25 @@ window.__ModuleLoader__.load({
 					}
 				}
 
+				/* 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) {
 					const root = findWidthRoot();
 					if (root === null) return;
@@ -383,12 +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; `custom` shows the dragged width. */
+				/* 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 def = tierOf(tierId);
-					if (def.value !== null) return def.value;
-					const px = readStoredNumber(CUSTOM_KEY);
-					return px === null ? "—" : `${Math.round(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 "—";
+					}
 				}
 
 				function syncButton() {
@@ -420,13 +496,27 @@ 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();
 					});
 					menu.appendChild(item);
 				}
 
+				/* Write only on change: syncMenu also runs on window resizes,
+				 * and untouched text should not churn the DOM (the plugin's own
+				 * MutationObserver watches childList). */
+				function setText(el, text) {
+					if (el.textContent !== text) el.textContent = text;
+				}
+
 				function syncMenu() {
 					const tier = currentTier();
 					const items = menu.querySelectorAll("button[data-tier]");
@@ -436,13 +526,9 @@ window.__ModuleLoader__.load({
 						items[i].classList.toggle("selected", on);
 						items[i].setAttribute("aria-checked", String(on));
 						const labelEl = items[i].querySelector(".dshwm-label");
-						if (labelEl) labelEl.textContent = t(tierOf(id).key);
+						if (labelEl) setText(labelEl, t(tierOf(id).key));
 						const valueEl = items[i].querySelector(".dshwm-value");
-						if (valueEl) valueEl.textContent = 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));
+						if (valueEl) setText(valueEl, tierValueText(id));
 					}
 				}
 
@@ -464,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
@@ -484,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");
@@ -499,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();
 				};
@@ -527,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);
 
@@ -551,6 +781,7 @@ window.__ModuleLoader__.load({
 					}
 					body().appendChild(btn);
 					body().appendChild(menu);
+					body().appendChild(guide);
 					syncButton();
 					const saved = getSavedTier();
 					if (saved !== "standard") applyTier(saved);
@@ -611,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;
@@ -665,6 +899,22 @@ window.__ModuleLoader__.load({
 					fallbackTimer = setInterval(() => heal(false), FALLBACK_HEAL_MS);
 				}
 
+				/* ---- 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 = () => {
+					if (resizeFrame !== null) return;
+					scheduleFrame(() => {
+						resizeFrame = null;
+						syncButton();
+						syncMenu();
+						positionGuide();
+					});
+				};
+				window.addEventListener("resize", onWindowResize);
+
 				/* ---- disposer ---- */
 				return () => {
 					unsubscribeLocale();
@@ -672,14 +922,19 @@ 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);
 					if (observer !== null) observer.disconnect();
 					document.removeEventListener("click", onDocClick);
 					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
@@ -689,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.6",
-  "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+, 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": {