dsh-width-tiers 1.0.7 → 1.0.9

package/lib/client.js

@@ -29,11 +29,26 @@ 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.
+		 *
+		 * The app preference stores the tier's configured target (nominal px,
+		 * the recorded custom width, or the live cap for full); only the
+		 * inline value is clamped. This lets the app restore the target when
+		 * the window widens instead of staying pinned to a narrow clamp.
+		 * The picker icon has one bar per tier (full lights five, custom all
+		 * six), tier changes sync across tabs, the menu supports
+		 * ArrowUp/Down/Home/End/Escape, and the sidebar's embedded
+		 * Conversation is excluded from the width-root lookup.
 		 *
 		 *  - Panels are driven through the layout service (ctx.layout), never
 		 *    by simulating clicks.
@@ -59,9 +74,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 +103,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 +117,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" }
 		];
 
@@ -136,15 +157,22 @@ window.__ModuleLoader__.load({
 			"#dsh-wide-toggle:not(:hover):not(:focus-visible) svg rect{width:6px;x:5px}",
 			"#dsh-wide-toggle.active{background:var(--dsw-alias-state-business-primary);border-color:transparent;color:var(--dsw-static-neutral-00);opacity:1}",
 			"#dsh-wide-toggle.pulse{animation:dsh-wide-pulse .65s ease-out}",
+			"@media (prefers-reduced-motion:reduce){#dsh-wide-toggle{transition:none}#dsh-wide-toggle.pulse{animation:none}}",
 			"@keyframes dsh-wide-pulse{0%{box-shadow:0 0 0 0 color-mix(in srgb,var(--dsw-alias-state-business-primary) 60%,transparent)}100%{box-shadow:0 0 0 14px transparent}}",
 			"#dsh-width-menu{position:fixed;right:20px;bottom:264px;z-index:1000;min-width:196px;padding:6px;border:1px solid var(--dsw-alias-border-l2);border-radius:12px;background:var(--dsw-specific-menu);box-shadow:0 8px 28px rgba(0,0,0,.24);display:flex;flex-direction:column;gap:2px}",
 			"#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:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:-2px}",
 			"#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]{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]::after{opacity:1}"
 		].join("");
 		//#endregion
 
@@ -224,6 +252,13 @@ window.__ModuleLoader__.load({
 				let widthRoot = null;
 				let widthPath = null;
 
+				/* Whether this plugin wrote the app's width preference. Native
+				 * drags also write it, so unload only removes a value this
+				 * plugin owns. */
+				let preferenceOwned = false;
+				let preferenceWritten = null;
+				let pulseTimer = null;
+
 				function hasWidthVar(el) {
 					return getComputedStyle(el)
 						.getPropertyValue("--dsh-chat-content-width")
@@ -242,14 +277,35 @@ window.__ModuleLoader__.load({
 					widthPath = path.length > 0 ? path : null;
 				}
 
+				/* Sidebar chat tabs render an embedded Conversation whose
+				 * `--dsh-chat-content-width` is a local min() and never reads
+				 * `--dsh-chat-user-width`. Writing there would be a no-op on
+				 * the visible column and could starve the real transcript. */
+				function isSidebarConversation(el) {
+					return typeof el.closest === "function"
+						&& el.closest("[data-sidebar-chat]") !== null;
+				}
+
+				function firstWidthRoot(list) {
+					for (let i = 0; i < list.length; i++) {
+						const el = list[i];
+						if (isSidebarConversation(el)) continue;
+						if (hasWidthVar(el)) return el;
+					}
+					return null;
+				}
+
 				function scanWidthRoot() {
-					const all = document.querySelectorAll("[class]");
-					for (let i = 0; i < all.length; i++) {
-						if (hasWidthVar(all[i])) {
-							widthRoot = all[i];
-							recordWidthPath(widthRoot);
-							return widthRoot;
-						}
+					/* Prefer the stable Conversation data attribute (one or two
+					 * elements) over every classed node in the document. The
+					 * [class] walk remains the compatibility fallback for older
+					 * clients that do not publish data-conversation-content. */
+					let found = firstWidthRoot(document.querySelectorAll("[data-conversation-content]"));
+					if (found === null) found = firstWidthRoot(document.querySelectorAll("[class]"));
+					if (found !== null) {
+						widthRoot = found;
+						recordWidthPath(widthRoot);
+						return widthRoot;
 					}
 					widthRoot = null;
 					widthPath = null;
@@ -257,14 +313,16 @@ window.__ModuleLoader__.load({
 				}
 
 				function findWidthRoot(allowScan) {
-					if (widthRoot !== null && document.contains(widthRoot)) return widthRoot;
+					if (widthRoot !== null && document.contains(widthRoot)
+						&& !isSidebarConversation(widthRoot)) return widthRoot;
 					if (widthPath !== null) {
 						let el = document.body;
 						for (let i = 0; i < widthPath.length; i++) {
 							el = el.children[widthPath[i]];
 							if (!el) break;
 						}
-						if (el && el !== widthRoot && document.contains(el) && hasWidthVar(el)) {
+						if (el && el !== widthRoot && document.contains(el)
+							&& !isSidebarConversation(el) && hasWidthVar(el)) {
 							widthRoot = el;
 							return widthRoot;
 						}
@@ -293,33 +351,51 @@ window.__ModuleLoader__.load({
 					}
 				}
 
-				/* Resolve a tier to the px the app would clamp it to
-				 * (resolveContentWidth: max = column - handle budget), or
-				 * null when the tier leaves the width to the app. */
-				function tierPx(tier, root) {
-					const cap = Math.max(CONTENT_MIN_PX, root.offsetWidth - CONTENT_EDGE_BUDGET_PX);
+				/* The tier's configured target, before the app's column clamp.
+				 * This is the value persisted to the app preference: on a
+				 * narrow column the app clamps it for display, and when the
+				 * window widens it restores the configured target instead of
+				 * staying pinned to the old clamp. `full` is inherently the
+				 * live maximum. */
+				function tierTargetPx(tier, root) {
 					switch (tier) {
-						case "medium": return Math.min(1120, cap);
-						case "wide": return Math.min(1280, cap);
-						case "ultra": return Math.min(1400, cap);
-						case "full": return cap;
-						case "custom": {
-							const dragged = readStoredNumber(CUSTOM_KEY);
-							return dragged === null ? null : Math.min(dragged, cap);
-						}
+						case "medium":
+						case "wide":
+						case "ultra":
+							return NOMINAL_WIDTH_PX[tier];
+						case "full":
+							return Math.max(CONTENT_MIN_PX, root.offsetWidth - CONTENT_EDGE_BUDGET_PX);
+						case "custom": return readStoredNumber(CUSTOM_KEY);
 						default: return null; /* standard: app default */
 					}
 				}
 
-				/* 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 px actually applied to the column (same floor/max as the
+				 * app's resolveContentWidth). */
+				function appliedTierPx(tier, root) {
+					const target = tierTargetPx(tier, root);
+					if (target === null) return null;
+					const cap = Math.max(CONTENT_MIN_PX, root.offsetWidth - CONTENT_EDGE_BUDGET_PX);
+					return Math.min(Math.max(target, CONTENT_MIN_PX), cap);
+				}
+
+				/* 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) {
@@ -329,28 +405,47 @@ window.__ModuleLoader__.load({
 					/* custom before the first drag has no width of its own —
 					 * leave whatever the app last published in place. */
 					if (tier === "custom" && readStoredNumber(CUSTOM_KEY) === null) return;
-					const px = tierPx(tier, root);
-					if (px === null) {
-						if (target.style.getPropertyValue("--dsh-chat-user-width") !== "") {
+					const targetPx = tierTargetPx(tier, root);
+					if (targetPx === null) {
+						/* standard: hand the width back to the app default. The
+						 * app's width preference is cleared as well; standard is
+						 * deliberately the reset to the app's default width. */
+						if (target.style.getPropertyValue("--dsh-chat-user-width") !== "" || preferenceOwned) {
 							target.style.removeProperty("--dsh-chat-user-width");
 							try {
 								window.localStorage.removeItem(APP_PREF_KEY);
 							} catch (e) {
 								/* ignore */
 							}
+							preferenceOwned = false;
+							preferenceWritten = null;
 						}
 						return;
 					}
-					/* Mirror into the app's preference so window resizes and
-					 * conversation remounts re-clamp through the app's own
-					 * publish cycle instead of relying on plugin healing. */
-					const next = String(Math.round(px));
-					if (target.style.getPropertyValue("--dsh-chat-user-width") !== next + "px") {
-						target.style.setProperty("--dsh-chat-user-width", next + "px");
+					const laidOut = root.offsetWidth > 0;
+					/* `full` derives its target from the live column; without a
+					 * layout box it would collapse to the 640px floor and pin a
+					 * narrow width. Wait for the fallback/resize pass. */
+					if (!laidOut && tier === "full") return;
+					if (laidOut) {
+						const px = appliedTierPx(tier, root);
+						if (px !== null) {
+							const next = String(Math.round(px));
+							if (target.style.getPropertyValue("--dsh-chat-user-width") !== next + "px") {
+								target.style.setProperty("--dsh-chat-user-width", next + "px");
+							}
+						}
 					}
+					/* Persist the unclamped target even while the root is not
+					 * laid out (fixed tiers / recorded custom width do not
+					 * depend on the column). The app clamps it for display and
+					 * restores it after a resize / remount. */
+					const preference = String(Math.round(targetPx));
 					try {
-						if (window.localStorage.getItem(APP_PREF_KEY) !== next) {
-							window.localStorage.setItem(APP_PREF_KEY, next);
+						if (window.localStorage.getItem(APP_PREF_KEY) !== preference) {
+							window.localStorage.setItem(APP_PREF_KEY, preference);
+							preferenceOwned = true;
+							preferenceWritten = preference;
 						}
 					} catch (e) {
 						/* ignore */
@@ -360,25 +455,30 @@ window.__ModuleLoader__.load({
 				/* true while the CURRENT tier is the one that collapsed the sidebar */
 				let collapsedByTier = false;
 
-				function applyTier(tier) {
+				/* `persist` is false when another tab already wrote the tier:
+				 * adopting it must not write localStorage again. */
+				function applyTier(tier, persist = true) {
 					body().setAttribute("data-dsh-width", tier);
-					try {
-						window.localStorage.setItem(KEY, tier);
-					} catch (e) {
-						/* storage unavailable — state still applies this session */
+					if (persist) {
+						try {
+							window.localStorage.setItem(KEY, tier);
+						} catch (e) {
+							/* storage unavailable — state still applies this session */
+						}
 					}
 					applyContentWidth(tier);
 					if (tier === "full") {
 						if (!isSidebarCollapsed()) {
 							collapseSidebar();
 							collapsedByTier = true;
-						} else {
-							collapsedByTier = false;
 						}
+						/* already collapsed: don't claim ownership we may not have */
 					} else if (tier === "standard") {
 						if (collapsedByTier && isSidebarCollapsed()) expandSidebar();
 						collapsedByTier = false;
-					} else {
+					} else if (!isSidebarCollapsed()) {
+						/* the user (or another panel) expanded it — the plugin no
+						 * longer owns the collapsed state */
 						collapsedByTier = false;
 					}
 					syncButton();
@@ -398,27 +498,49 @@ window.__ModuleLoader__.load({
 					for (let i = 0; i < TIERS.length; i++) {
 						if (TIERS[i].id === tier) idx = i;
 					}
-					const widths = [3.5, 5.5, 7.5, 10, 13];
+					/* One bar per tier so full (5 bars) and custom (6 bars,
+					 * all lit) remain distinguishable. */
+					const widths = [3.5, 5.3, 7.1, 8.9, 10.7, 12.5];
 					let bars = "";
-					for (let b = 0; b < 5; b++) {
-						const y = 0.5 + b * 3;
-						bars += `<rect x="1.5" y="${y}" width="${widths[b]}" height="2" rx="1" fill="currentColor" opacity="${b <= idx ? 1 : 0.3}"/>`;
+					for (let b = 0; b < TIERS.length; b++) {
+						const y = 0.75 + b * 2.55;
+						bars += `<rect x="1.5" y="${y}" width="${widths[b]}" height="1.6" rx="0.8" fill="currentColor" opacity="${b <= idx ? 1 : 0.3}"/>`;
 					}
 					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() {
@@ -447,12 +569,22 @@ window.__ModuleLoader__.load({
 					item.type = "button";
 					item.setAttribute("role", "menuitemradio");
 					item.setAttribute("data-tier", def.id);
+					/* Roving focus: the menu is opened by focusing one item, and
+					 * ArrowUp/Down/Home/End move between items. */
+					item.tabIndex = -1;
 					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(true);
+							return;
+						}
+						endGuide(false);
 						applyTier(def.id);
-						hideMenu();
+						hideMenu(true);
 					});
 					menu.appendChild(item);
 				}
@@ -476,40 +608,210 @@ 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));
 					}
 				}
 
+				function menuItems() {
+					return Array.from(menu.querySelectorAll("button[data-tier]"));
+				}
+
 				function showMenu() {
 					menu.hidden = false;
 					btn.setAttribute("aria-expanded", "true");
 					syncMenu();
+					const items = menuItems();
+					const selected = items.find((item) => item.getAttribute("data-tier") === currentTier()) || items[0];
+					if (selected && typeof selected.focus === "function") selected.focus();
 				}
 
-				function hideMenu() {
+				/* restoreFocus is true for Escape / item selection, false for a
+				 * click-away so the click target keeps focus. */
+				function hideMenu(restoreFocus) {
+					const hadFocus = menu.contains(document.activeElement);
 					menu.hidden = true;
 					btn.setAttribute("aria-expanded", "false");
+					if (restoreFocus && hadFocus && typeof btn.focus === "function") btn.focus();
 				}
 
 				btn.addEventListener("click", (e) => {
 					if (e && e.stopPropagation) e.stopPropagation();
 					if (menu.hidden) showMenu();
-					else hideMenu();
+					else hideMenu(true);
 				});
 
 				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(false);
+					/* 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") {
+						if (!menu.hidden) hideMenu(true);
+						if (guideActive) endGuide(true);
+						return;
+					}
+					if (menu.hidden) return;
+					if (e.key === "Tab") {
+						/* Let Tab move on, but do not leave an orphaned menu. */
+						hideMenu(false);
+						return;
+					}
+					const items = menuItems();
+					if (items.length === 0) return;
+					const current = items.indexOf(document.activeElement);
+					let next = -1;
+					if (e.key === "ArrowDown") next = current < 0 ? 0 : (current + 1) % items.length;
+					else if (e.key === "ArrowUp") next = current < 0 ? items.length - 1 : (current - 1 + items.length) % items.length;
+					else if (e.key === "Home") next = 0;
+					else if (e.key === "End") next = items.length - 1;
+					if (next < 0) return;
+					e.preventDefault();
+					const item = items[next];
+					if (typeof item.focus === "function") item.focus();
 				};
 				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 guideHandle = 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 handle the user actually grabbed
+				 * (it moves with the dragged edge); fall back to the right
+				 * handle / frame edge when the handle is not mounted yet
+				 * (menu-opened guide, hero or settling phase). */
+				function positionGuide() {
+					if (!guideActive) return;
+					const handle = guideHandle !== null && document.contains(guideHandle)
+						? guideHandle
+						: document.querySelector('[data-width-handle="right"]');
+					const viewport = window.innerWidth || 0;
+					if (handle === null || typeof handle.getBoundingClientRect !== "function" || 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;
+					guideHandle = null;
+					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(handle) {
+					window.clearTimeout(guideHideTimer);
+					guideActive = true;
+					guideDragging = true;
+					guideHandle = handle || null;
+					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";
+					guideHandle = null;
+					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,14 +823,15 @@ 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(e.target.closest("[data-width-handle]"));
+					if (currentTier() === "custom") return;
 					body().setAttribute("data-dsh-width", "custom");
 					try {
 						window.localStorage.setItem(KEY, "custom");
 					} catch (err) {
 						/* ignore */
 					}
-					collapsedByTier = false;
 					syncButton();
 					syncMenu();
 				};
@@ -536,39 +839,80 @@ 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();
+				};
+
+				/* A cancelled drag (touch gesture, window switch) ends without
+				 * pointerup; without this handler the bubble would stay stuck
+				 * in dragging mode and click-away would no longer dismiss it. */
+				const onHandlePointerCancel = () => {
+					/* The cancel target can be the capture element or the
+					 * document; while a drag is active, end it regardless. */
+					if (!guideActive || !guideDragging) return;
+					endGuide(false);
 					syncButton();
 					syncMenu();
 				};
 				document.addEventListener("pointerdown", onHandlePointerDown, true);
 				document.addEventListener("pointerup", onHandlePointerUp, true);
+				document.addEventListener("pointercancel", onHandlePointerCancel, true);
 
 				/* ---- feedback ring so every selection is visibly answered ---- */
 				function pulse() {
 					btn.classList.remove("pulse");
 					void btn.offsetWidth;
 					btn.classList.add("pulse");
-					window.setTimeout(() => btn.classList.remove("pulse"), 700);
+					window.clearTimeout(pulseTimer);
+					pulseTimer = window.setTimeout(() => {
+						btn.classList.remove("pulse");
+						pulseTimer = null;
+					}, 700);
 				}
 
 				/* ---- re-render localized copy when the app language changes ---- */
 				const renderTexts = () => {
 					syncButton();
 					syncMenu();
+					if (guideActive && !guideDragging && guide.dataset.mode === "hint") {
+						setText(guideTextEl, t("guide.hint"));
+					}
 				};
 				const unsubscribeLocale = ctx.locale.subscribe(renderTexts);
 
 				/* ---- attach once the app shell has mounted ---- */
 				let attached = false;
+				let readyTimer = null;
+				let slowTimer = null;
+				let readyTimeout = null;
+
+				function stopWaiting() {
+					if (readyTimer !== null) {
+						clearInterval(readyTimer);
+						readyTimer = null;
+					}
+					if (slowTimer !== null) {
+						clearInterval(slowTimer);
+						slowTimer = null;
+					}
+					if (readyTimeout !== null) {
+						window.clearTimeout(readyTimeout);
+						readyTimeout = null;
+					}
+				}
 
 				/* The old gate matched [data-sidebar-collapsed] /
 				 * [data-details-collapsed]. 0.1.5-rc.2 renders collapsed
@@ -581,6 +925,7 @@ window.__ModuleLoader__.load({
 					if (attached || !body()) return;
 					if (document.querySelector("[data-shell-overlay]") === null) return;
 					attached = true;
+					stopWaiting();
 					try {
 						window.localStorage.removeItem(OLD_KEY);
 					} catch (e) {
@@ -588,18 +933,39 @@ window.__ModuleLoader__.load({
 					}
 					body().appendChild(btn);
 					body().appendChild(menu);
+					body().appendChild(guide);
 					syncButton();
 					const saved = getSavedTier();
 					if (saved !== "standard") applyTier(saved);
 					startHealing();
+					if (widthRoot !== null) observeWidthTarget(widthRoot);
 				}
 
-				const readyTimer = setInterval(attach, 300);
-				window.addEventListener("load", attach);
-				const timeout = window.setTimeout(() => {
+				readyTimer = setInterval(attach, 300);
+				readyTimeout = window.setTimeout(() => {
+					if (attached) return;
 					clearInterval(readyTimer);
-					attach();
+					readyTimer = null;
+					/* A very slow boot should not leave the picker permanently
+					 * unmounted: keep a low-frequency retry instead of giving up. */
+					slowTimer = setInterval(attach, 2000);
 				}, READY_TIMEOUT_MS);
+				window.addEventListener("load", attach);
+
+				/* Tier changes from another tab: adopt the stored tier without
+				 * writing localStorage again (that would loop). */
+				const onStorage = (e) => {
+					if (!e || e.key !== KEY) return;
+					/* No storageArea identity check: spec does not require the
+					 * event object to be the same Storage instance as
+					 * window.localStorage, and dropping the event would break
+					 * cross-tab sync. */
+					const next = e.newValue;
+					if (typeof next !== "string" || !TIERS.some((tier) => tier.id === next)) return;
+					if (currentTier() === next) return;
+					applyTier(next, false);
+				};
+				window.addEventListener("storage", onStorage);
 
 				/* ---- self-heal: re-apply the width when the chat tree
 				 * remounts (conversation switch). Panels are never managed
@@ -618,15 +984,51 @@ window.__ModuleLoader__.load({
 				let rootRetryDelay = ROOT_RETRY_MIN_MS;
 				let rootRetryTimer = null;
 				let healFrame = null;
+				let resizeFrame = null;
 				let observer = null;
 				let fallbackTimer = null;
+				let widthObserver = null;
+				let observedTarget = null;
+
+				/* Return the frame id so heal and resize can be debounced and
+				 * cancelled independently. The old helper always wrote the
+				 * heal slot, so resizeFrame never became non-null and every
+				 * resize event scheduled another frame. */
+				function scheduleFrame(cb) {
+					return typeof requestAnimationFrame === "function"
+						? requestAnimationFrame(cb)
+						: window.setTimeout(cb, 0);
+				}
+				function cancelFrame(id) {
+					if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(id);
+					else window.clearTimeout(id);
+				}
 
-				const scheduleFrame = typeof requestAnimationFrame === "function"
-					? (cb) => { healFrame = requestAnimationFrame(cb); }
-					: (cb) => { healFrame = window.setTimeout(cb, 0); };
-				const cancelFrame = typeof cancelAnimationFrame === "function"
-					? (id) => cancelAnimationFrame(id)
-					: (id) => window.clearTimeout(id);
+				/* Watch the column that sizes the transcript. Sidebar/rightbar
+				 * changes and frame resizes alter it; `full` (and a clamped
+				 * fixed/custom width) must follow without polling every
+				 * mutation. Guarded for browsers/tests without ResizeObserver. */
+				function observeWidthTarget(root) {
+					if (typeof ResizeObserver === "undefined") return;
+					const target = widthTarget(root);
+					if (target === observedTarget && widthObserver !== null) return;
+					if (widthObserver !== null) {
+						widthObserver.disconnect();
+						widthObserver = null;
+					}
+					observedTarget = target;
+					widthObserver = new ResizeObserver(() => {
+						/* Never fight the app's native drag: it owns the width
+						 * while the user is moving a handle. */
+						if (guideActive && guideDragging) return;
+						const tier = currentTier();
+						if (tier === "standard") return;
+						applyContentWidth(tier);
+						syncButton();
+						syncMenu();
+					});
+					widthObserver.observe(target);
+				}
 
 				function scheduleRootRetry() {
 					if (rootRetryTimer !== null) return;
@@ -642,21 +1044,32 @@ window.__ModuleLoader__.load({
 						} else {
 							rootMissing = false;
 							rootRetryDelay = ROOT_RETRY_MIN_MS;
-							if (root !== prev) applyContentWidth(tier);
+							if (root !== prev) {
+								applyContentWidth(tier);
+								syncButton();
+								syncMenu();
+							}
+							observeWidthTarget(root);
 						}
 					}, rootRetryDelay);
 				}
 
 				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();
+					/* The app's native drag owns the inline width until release;
+					 * a heal must not restore the previous custom value on top. */
+					if (guideActive && guideDragging) return;
 					const tier = currentTier();
 					if (tier === "standard") return;
 					const prev = widthRoot;
 					let root;
-					if (rootMissing) {
-						/* Mid-remount: a mutation-driven heal only walks the
-						 * recorded path (O(depth)) — the backoff retry owns
-						 * full scans until the new root exists. */
-						root = fromObserver ? findWidthRoot(false) : findWidthRoot();
+					if (rootMissing || fromObserver) {
+						/* Mid-remount / mutation churn: walk the recorded path
+						 * only (O(depth)); the backoff retry owns full scans
+						 * until the new root exists. */
+						root = findWidthRoot(false);
 					} else {
 						root = findWidthRoot();
 					}
@@ -664,27 +1077,33 @@ window.__ModuleLoader__.load({
 						if (!rootMissing) {
 							rootMissing = true;
 							rootRetryDelay = ROOT_RETRY_MIN_MS;
-							scheduleRootRetry();
 						}
+						/* Idempotent: keep a backoff retry alive even if the
+						 * previous one ended while this tier was standard. */
+						scheduleRootRetry();
 						return;
 					}
 					if (rootMissing) {
 						rootMissing = false;
 						rootRetryDelay = ROOT_RETRY_MIN_MS;
 					}
-					if (root !== prev) applyContentWidth(tier);
-					/* full tracks the live column: after the sidebar collapse
-					 * animation settles the column widens, and the width must
-					 * follow (applyContentWidth is diff-checked, so steady
-					 * state writes nothing). */
-					if (tier === "full") applyContentWidth("full");
+					observeWidthTarget(root);
+					if (root !== prev) {
+						applyContentWidth(tier);
+						syncButton();
+						syncMenu();
+					} else if (!fromObserver) {
+						/* Fallback tick: retry an apply that was skipped while
+						 * the root had no layout box. */
+						applyContentWidth(tier);
+					}
 				}
 
 				function startHealing() {
 					if (typeof MutationObserver !== "undefined") {
 						observer = new MutationObserver(() => {
 							if (healFrame !== null) return;
-							scheduleFrame(() => {
+							healFrame = scheduleFrame(() => {
 								healFrame = null;
 								heal(true);
 							});
@@ -697,53 +1116,95 @@ window.__ModuleLoader__.load({
 						});
 					}
 					/* Low-frequency fallback so self-heal still runs if the
-					 * observer misses something — cheap: no scan while the
+					 * observer misses something — cheap: no full scan while the
 					 * cached root is alive. */
 					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. */
-				let resizeFrame = null;
-
+				/* ---- 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. ---- */
 				const onWindowResize = () => {
 					if (resizeFrame !== null) return;
-					scheduleFrame(() => {
+					resizeFrame = scheduleFrame(() => {
 						resizeFrame = null;
+						if (!(guideActive && guideDragging)) {
+							const tier = currentTier();
+							if (tier !== "standard") applyContentWidth(tier);
+						}
 						syncButton();
 						syncMenu();
+						positionGuide();
 					});
 				};
 				window.addEventListener("resize", onWindowResize);
 
+				/* All healing/observer state is initialized by now; try an
+				 * immediate mount instead of waiting for the first interval. */
+				attach();
+
 				/* ---- disposer ---- */
 				return () => {
 					unsubscribeLocale();
-					clearInterval(readyTimer);
+					stopWaiting();
 					clearInterval(fallbackTimer);
-					clearTimeout(timeout);
 					clearTimeout(rootRetryTimer);
+					clearTimeout(guideHideTimer);
+					clearTimeout(pulseTimer);
 					if (healFrame !== null) cancelFrame(healFrame);
 					if (resizeFrame !== null) cancelFrame(resizeFrame);
+					if (widthObserver !== null) {
+						widthObserver.disconnect();
+						widthObserver = null;
+						observedTarget = null;
+					}
 					window.removeEventListener("resize", onWindowResize);
+					window.removeEventListener("load", attach);
+					window.removeEventListener("storage", onStorage);
 					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("pointercancel", onHandlePointerCancel, 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
-					 * width survives a plugin reload — matching native-drag
-					 * semantics. */
+					/* Hand the width back to the app default. Only a value this
+					 * plugin wrote is removed, so a native drag preference that
+					 * predates the plugin survives unload. */
 					if (widthRoot !== null) {
 						widthTarget(widthRoot).style.removeProperty("--dsh-chat-user-width");
 					}
+					if (preferenceOwned) {
+						try {
+							/* Only remove the exact value this plugin wrote; a
+							 * native drag since then owns the preference. */
+							if (preferenceWritten !== null
+								&& window.localStorage.getItem(APP_PREF_KEY) === preferenceWritten) {
+								window.localStorage.removeItem(APP_PREF_KEY);
+							}
+						} catch (e) {
+							/* ignore */
+						}
+						preferenceOwned = false;
+						preferenceWritten = null;
+					}
+					/* Undo a collapse this plugin owned; a manual collapse is
+					 * left alone. */
+					if (collapsedByTier) {
+						try {
+							if (isSidebarCollapsed()) layout.toggleSidebar();
+						} catch (e) {
+							/* ignore */
+						}
+						collapsedByTier = false;
+					}
+					guideHandle = null;
 					body().removeAttribute("data-dsh-width");
+					body().removeAttribute("data-dsh-width-guide");
 				};
 			}, "dsh-width-tiers: ui");
 		}