@deepseek-ai/dsh-client-ui-commands 0.1.6-alpha.1 → 0.1.7-alpha.1

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-commands/README.md
-README.md: f802179e08009cd4db8a3b786e52e81b26bb21da
-README.zh.md: 1dee58ab42d67a62099d57d4e631e440d3349f21
+README.md: 7fada747562ff15a96997d8bffe9aeb6f9a18fb5
+README.zh.md: 2f532cbd0f3d33e304074644cc6cb02b7151d3e1

package/README.md

@@ -25,7 +25,7 @@ Typing a `/` command opens a registered popup, a client action, a host command's
 <a id="use-this-package"></a>
 ## Use this package
 
-Mount this plugin alongside `ui-input-trigger` and `ui-conversation`; the `/` source then appears in the trigger menu, and business packages register their command surfaces through `ctx.commandUi`. Typing `/model` opens the registered popup; a host command with an argument claim opens its input or executes directly. The composer's `+` button and a typed `/` open the same menu: an Add section (File, Goal, Plan, Feedback) and a Commands section (Compact, Permission, Model, Export) in usage order, each row with a glyph, a localized title and description, and the command name as an alias where the localized title differs from it.
+Mount this plugin alongside `ui-input-trigger` and `ui-conversation`; the `/` source then appears in the trigger menu, and business packages register their command surfaces through `ctx.commandUi`. Typing `/model` opens the registered popup; a host command with an argument claim opens its input or executes directly. The popup holds composer focus: typing filters the loaded rows locally, `↑`/`↓` walk them, Enter and `Tab` accept the highlighted row, and Escape and `Shift+Tab` return to the composer. The highlight opens on the row the options mark as the session's current value, so accepting on a freshly opened panel confirms it. The composer's `+` button and a typed `/` open the same menu: an Add section (File, Goal, Plan, Feedback) and a Commands section (Compact, Permission, Model, Export) in usage order, each row with a glyph, a localized title and description, and the command name as an alias where the localized title differs from it.
 
 ### Kinds and decorations
 
@@ -49,6 +49,8 @@ When the composer submits with images or generic files, only a host command decl
 
 `src/client/contract.ts` defines contribution and decoration registration, plus `dismiss(name)`, which closes that command's open popups and confirmations: dismissal aborts pending option loads, prevents their late results from reopening the popup, and preserves composer drafts. `CommandDirectory` owns the per-session wire cache and resolves typed commands through `resolution.ts`; that module owns first-party identity matching and localized input spellings. `matchSpace` reads the ready cache synchronously, while `matchEnter` waits for readiness and rejects on warmup failure or cancellation. Forwarded catalog and connection events invalidate the cache. After a matched Host execution, this browser emits `command/executed`; other clients observe only the durable command events. `PopupSelectController` owns popup state, and `PopupSelectView` occupies the input overlay. `presentation.ts` owns row labels, icons, and sections; its helpers and the resolution helpers stay internal to the plugin.
 
+Each command-directory fetch requires an existing retained Client Session and waits for its initial history open to succeed before sending `commands.list`. A temporary `commandCatalog` reference holds that Session until the fetch settles. An unretained Session or a failed open rejects without sending the RPC, so background catalog refreshes do not reopen closed Sessions.
+
 </details>
 
 -----

package/README.zh.md

@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-与 `ui-input-trigger` 及 `ui-conversation` 一起挂载本插件；`/` source 随即出现在触发菜单中，业务包经 `ctx.commandUi` 注册自己的命令表面。键入 `/model` 打开已注册的弹窗；带参数声明的宿主命令打开其输入或直接执行。composer 的 `+` 按钮与键入的 `/` 打开同一个菜单：「添加」小节（文件、目标、计划、反馈）与「指令」小节（压缩、权限、模型、下载日志）按使用频次排列，每行带图标、本地化的标题与说明，本地化标题与命令名不同时还显示命令名作为别名。
+与 `ui-input-trigger` 及 `ui-conversation` 一起挂载本插件；`/` source 随即出现在触发菜单中，业务包经 `ctx.commandUi` 注册自己的命令表面。键入 `/model` 打开已注册的弹窗；带参数声明的宿主命令打开其输入或直接执行。弹窗持有 composer 焦点：键入即在已加载的行上本地筛选，`↑`／`↓` 在行间移动，回车与 `Tab` 接受高亮行，Escape 与 `Shift+Tab` 把焦点还给 composer。高亮落在选项标记为会话当前值的行上，因此在刚打开的弹窗上接受即确认当前值。composer 的 `+` 按钮与键入的 `/` 打开同一个菜单：「添加」小节（文件、目标、计划、反馈）与「指令」小节（压缩、权限、模型、下载日志）按使用频次排列，每行带图标、本地化的标题与说明，本地化标题与命令名不同时还显示命令名作为别名。
 
 ### 种类与装饰
 
@@ -49,6 +49,8 @@ composer 携带图片或通用文件提交时，只有声明了 `input.attachmen
 
 `src/client/contract.ts` 定义贡献项和装饰的注册接口，以及 `dismiss(name)`：它关闭该命令已打开的弹窗与确认对话框，中止待完成的选项加载，阻止晚到结果重新打开弹窗，并保留 composer 草稿。`CommandDirectory` 负责会话级协议缓存，并通过 `resolution.ts` 解析输入命令；该模块负责内置命令标识匹配和本地化输入写法。`matchSpace` 同步读取就绪缓存，`matchEnter` 等待缓存就绪，预热失败或取消时拒绝。转发的目录和连接事件使缓存失效。宿主执行匹配的命令后，本浏览器发布 `command/executed`，其他客户端只观察持久命令事件。`PopupSelectController` 负责弹窗状态，`PopupSelectView` 占据输入浮层。`presentation.ts` 负责行标题、图标和分节，展示与解析辅助函数均留在插件内部。
 
+每次命令目录拉取都要求客户端已持有该会话，并等待首次历史打开成功后才发送 `commands.list`。临时的 `commandCatalog` 引用持续持有会话，直到拉取结束。未被持有的会话或打开失败会直接拒绝，不发送 RPC，因此后台目录刷新不会重新打开已关闭的会话。
+
 </details>
 
 -----

package/lib/client.js

@@ -9,6 +9,69 @@ window.__ModuleLoader__.load({
 		let _deepseek_ai_dsh_client_store = require("@deepseek-ai/dsh-client-store");
 		let react_jsx_runtime = require("react/jsx-runtime");
 		let react = require("react");
+		//#region ../../util/values/src/index.ts
+		/**
+		* Weak-key lookup with a strongly retained iterable set of associated values.
+		*
+		* Each value must belong to only one key. The container performs no automatic
+		* cleanup; owners delete associations or clear the container at lifecycle end.
+		*/
+		var WeakMapWithValues = class {
+			keys = /* @__PURE__ */ new WeakMap();
+			valueSet = /* @__PURE__ */ new Set();
+			/** Live strongly retained values in insertion order. */
+			values = this.valueSet;
+			/**
+			* Read the value associated with a key.
+			* @param key - weakly held lookup key.
+			* @returns the associated value, or absence.
+			*/
+			get(key) {
+				return this.keys.get(key);
+			}
+			/**
+			* Test whether a key has an association.
+			* @param key - weakly held lookup key.
+			* @returns whether the key is present.
+			*/
+			has(key) {
+				return this.keys.has(key);
+			}
+			/**
+			* Associate one key with one caller-unique value.
+			* @param key - weakly held lookup key.
+			* @param value - strongly retained value that belongs to no other key.
+			* @returns this container.
+			*/
+			set(key, value) {
+				if (this.keys.has(key)) {
+					const previous = this.keys.get(key);
+					if (previous === value) return this;
+					this.valueSet.delete(previous);
+				}
+				this.keys.set(key, value);
+				this.valueSet.add(value);
+				return this;
+			}
+			/**
+			* Remove one association and its strongly retained value.
+			* @param key - weakly held lookup key.
+			* @returns whether an association was removed.
+			*/
+			delete(key) {
+				if (!this.keys.has(key)) return false;
+				const value = this.keys.get(key);
+				const deleted = this.keys.delete(key);
+				this.valueSet.delete(value);
+				return deleted;
+			}
+			/** Remove every association and strongly retained value. */
+			clear() {
+				this.keys = /* @__PURE__ */ new WeakMap();
+				this.valueSet.clear();
+			}
+		};
+		//#endregion
 		//#region lib/types/client/locales.js
 		/**
 		* `command` namespace dictionaries: the composer menu's section headings,
@@ -307,6 +370,19 @@ window.__ModuleLoader__.load({
 			if (query === "") return options;
 			return options.filter((o) => o.label.toLowerCase().includes(query) || (o.detail?.toLowerCase().includes(query) ?? false));
 		}
+		/**
+		* Highlight index for a freshly loaded row list: the row marked as the current
+		* value when the live search still shows it, else the top row. Opening parks
+		* the highlight on the value the session already uses, so an accept gesture
+		* made without looking confirms that value instead of the topmost row.
+		* @param options - the loaded rows.
+		* @param search - the shell's live filter text (non-empty after a retry).
+		* @returns index into the filtered rows.
+		*/
+		function currentIndex(options, search) {
+			const at = filterOptions(options, search).findIndex((option) => option.active === true);
+			return at === -1 ? 0 : at;
+		}
 		/** The shell's error-strip line for a settlement failure. */
 		function errorText(error) {
 			return error instanceof Error ? error.message : String(error);
@@ -358,11 +434,12 @@ window.__ModuleLoader__.load({
 			load(binding) {
 				binding.spec.options(binding.context, binding.abort.signal).then((options) => {
 					if (this.binding !== binding) return;
+					const current = this.state.getSnapshot();
 					this.state.set({
-						...this.state.getSnapshot(),
+						...current,
 						status: "ready",
 						options,
-						active: 0,
+						active: currentIndex(options, current.search),
 						error: null
 					});
 				}, (error) => {
@@ -391,7 +468,8 @@ window.__ModuleLoader__.load({
 			}
 			/**
 			* Replace the local search text (pure local filter — the provider is never
-			* re-queried) and rebase the highlight onto the new filtered list.
+			* re-queried) and rebase the highlight to the top of the new filtered list:
+			* typing searches for something other than the current value.
 			* @param search - the shell search input's text.
 			*/
 			setSearch(search) {
@@ -565,12 +643,12 @@ window.__ModuleLoader__.load({
 		}
 		/** Built-in Host commands whose client face this package owns. */
 		const HOST_FACES = new Map([
-			hostFace("goal", _deepseek_ai_dsh_client_ui_primitives.IconGoalOutline16),
-			hostFace("plan", _deepseek_ai_dsh_client_ui_primitives.IconPlanOutline14),
-			hostFace("feedback", _deepseek_ai_dsh_client_ui_primitives.IconPaperPlaneOutline14),
-			hostFace("compact", _deepseek_ai_dsh_client_ui_primitives.IconCompactOutline16),
-			hostFace("permission", _deepseek_ai_dsh_client_ui_primitives.IconShieldOutline16),
-			hostFace("export", _deepseek_ai_dsh_client_ui_primitives.IconDownloadOutline16)
+			hostFace("goal", _deepseek_ai_dsh_client_ui_primitives.IconGoalOutlineRegular),
+			hostFace("plan", _deepseek_ai_dsh_client_ui_primitives.IconPlanOutlineRegular),
+			hostFace("feedback", _deepseek_ai_dsh_client_ui_primitives.IconPaperPlaneOutlineRegular),
+			hostFace("compact", _deepseek_ai_dsh_client_ui_primitives.IconCompactOutlineRegular),
+			hostFace("permission", _deepseek_ai_dsh_client_ui_primitives.PermissionIconFullAccessRegular),
+			hostFace("export", _deepseek_ai_dsh_client_ui_primitives.IconDownloadOutlineRegular)
 		]);
 		/**
 		* The localized menu face of a catalog row.
@@ -626,6 +704,8 @@ window.__ModuleLoader__.load({
 		* `rankByName`). A host/contribution name collision fails loud. Every
 		* execute addresses the session's agent by sessionId — sessions are always
 		* agent-backed.
+		* Catalog RPCs retain an existing Client Session through completion and
+		* wait for its initial history open to succeed before contacting the Host.
 		*/
 		/** Recover the command name from a line the Host confirmed as executed. */
 		function submittedCommandName(line) {
@@ -645,7 +725,7 @@ window.__ModuleLoader__.load({
 			live = {
 				contributions: /* @__PURE__ */ new Map(),
 				decorations: /* @__PURE__ */ new Map(),
-				popups: /* @__PURE__ */ new Map()
+				popups: new WeakMapWithValues()
 			};
 			/** `command`-namespace translator (composer refusal notices). */
 			t;
@@ -659,10 +739,16 @@ window.__ModuleLoader__.load({
 				if (locale === void 0) throw new Error("ui-commands: locale service unavailable");
 				this.t = locale.bind("command");
 				this.directory = new CommandDirectory(async (sessionId) => {
-					if (this.sessions().subagentAddress(sessionId) !== void 0) return [];
-					const result = await ctx.remote.commands.list(sessionId);
-					if (!result.ok) throw new Error(`command.list failed: ${result.error.code}: ${result.error.message}`);
-					return result.value;
+					const sessions = this.sessions();
+					if (sessions.subagentAddress(sessionId) !== void 0) return [];
+					if (sessions.binding(sessionId) === void 0) throw new Error(`command catalog requires a retained session "${sessionId}"`);
+					return sessions.using(sessionId, { source: "commandCatalog" }, async (reference) => {
+						const state = reference.binding.session.getSnapshot();
+						if (state.openState !== "open") throw state.openError ?? /* @__PURE__ */ new Error(`session "${sessionId}" is not open`);
+						const result = await ctx.remote.commands.list(sessionId);
+						if (!result.ok) throw new Error(`command.list failed: ${result.error.code}: ${result.error.message}`);
+						return result.value;
+					});
 				});
 				const inputTriggers = ctx.get("inputTriggers");
 				if (inputTriggers === void 0) throw new Error("ui-commands: slash service unavailable");
@@ -731,24 +817,27 @@ window.__ModuleLoader__.load({
 			* @param name - command name without the leading slash.
 			*/
 			dismiss(name) {
-				for (const popup of this.live.popups.values()) if (popup.state.getSnapshot().command === name) popup.dismiss();
+				for (const popup of this.live.popups.values) if (popup.state.getSnapshot().command === name) popup.dismiss({ focusComposer: true });
 			}
 			/**
 			* Resolve the per-session popup controller (lazy; dies with the session
 			* scope). The controller's consume callback dispatches the scoped
 			* consume-token event back to this session; focusComposer reaches the
-			* composer through the overlay slot currency.
+			* session's composer through the conversation input face.
 			* @param actx - session-scope ctx.
 			* @returns the resident controller.
+			* @throws when the Context no longer belongs to a retained Session generation.
 			*/
 			popupFor(actx) {
-				const id = this.sessions().scopeOf(actx);
-				if (id === void 0) throw new Error("command.popupFor requires a session scope");
+				const sessions = this.sessions();
+				const session = sessions.sessionOf(actx);
+				const binding = session === void 0 ? void 0 : sessions.binding(session.sessionId);
+				if (binding === void 0 || binding.session !== session) throw new Error("command.popupFor requires a retained Session scope");
 				const { popups } = this.live;
-				const existing = popups.get(id);
+				const existing = popups.get(binding);
 				if (existing !== void 0) return existing;
 				const controller = new PopupSelectController({
-					consume: (segment) => actx.bail(actx, "slash/input-consume-token", { guard: segment.via === "menu" ? {
+					consume: (segment) => binding.ctx.bail(binding.ctx, "slash/input-consume-token", { guard: segment.via === "menu" ? {
 						kind: "span",
 						span: segment.span
 					} : {
@@ -756,31 +845,16 @@ window.__ModuleLoader__.load({
 						token: segment.token
 					} }) === true,
 					focusComposer: () => {
-						this.focusHooks.get(id)?.();
+						binding.ctx.get("conversation")?.input.for(binding.ctx).focus();
 					}
 				});
-				popups.set(id, controller);
-				actx.effect(() => () => {
+				popups.set(binding, controller);
+				binding.ctx.effect(() => () => {
 					controller.dispose();
-					popups.delete(id);
-					this.focusHooks.delete(id);
+					popups.delete(binding);
 				}, "command: session popup");
 				return controller;
 			}
-			/** Composer focus hooks by session (the overlay wiring binds the textarea focus here). */
-			focusHooks = /* @__PURE__ */ new Map();
-			/**
-			* Bind one session's composer-focus hook (overlay slot wiring; unbind on unmount).
-			* @param id - session id.
-			* @param focus - textarea focus callback.
-			* @returns the unbind disposer.
-			*/
-			bindComposerFocus(id, focus) {
-				this.focusHooks.set(id, focus);
-				return () => {
-					if (this.focusHooks.get(id) === focus) this.focusHooks.delete(id);
-				};
-			}
 			/**
 			* Menu candidates: host catalog + contribution availability, built-in rows
 			* localized, then position filtering; sections for an empty query, the
@@ -1055,7 +1129,7 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 		//#region \0dsh-css:/home/runner/work/deepseek-harness/deepseek-harness/packages/client/ui-commands/src/client/PopupSelectView.module.css.mjs
-		const css = ".mufS8W_card{z-index:100;--dsh-scrollbar-thumb:var(--dsw-alias-scrollbar-bg-l2);--dsh-scrollbar-thumb-hover:var(--dsw-alias-scrollbar-hover-l2);background:var(--dsw-specific-menu);--dsw-elevation-stroke-color:var(--dsw-alias-border-l1);min-width:min(220px,100%);max-width:100%;max-height:320px;box-shadow:var(--dsw-elevation-prominent);border:0;border-radius:20px;outline:none;flex-direction:column;padding:4px;display:flex;position:absolute;bottom:calc(100% + 4px);left:0;overflow:hidden}.mufS8W_viewport{flex-direction:column;min-height:0;display:flex;overflow-y:auto}.mufS8W_row{cursor:pointer;color:var(--dsw-alias-label-primary);border-radius:8px;align-items:center;gap:8px;padding:6px 8px;font-size:13px;display:flex}.mufS8W_rowActive{background:var(--dsw-alias-interactive-bg-hover)}.mufS8W_label{flex:0 auto;align-items:baseline;gap:4px;min-width:0;display:flex}.mufS8W_labelText{white-space:nowrap;text-overflow:ellipsis;min-width:0;overflow:hidden}.mufS8W_badge{color:var(--dsw-alias-label-tertiary);letter-spacing:.2px;flex:none;align-self:flex-start;margin-top:-1px;font-size:8px;font-weight:600;line-height:10px}.mufS8W_detail{min-width:0;color:var(--dsw-alias-label-tertiary);white-space:nowrap;text-overflow:ellipsis;flex:1;font-size:12px;overflow:hidden}.mufS8W_check{color:var(--dsw-alias-label-primary);flex:none;margin-left:auto;display:inline-flex}.mufS8W_status{color:var(--dsw-alias-label-tertiary);padding:8px 10px;font-size:13px}.mufS8W_search{border:.5px solid var(--dsw-alias-border-inverted);color:var(--dsw-alias-label-primary);background:0 0;border-radius:8px;outline:none;margin:2px 2px 4px;padding:6px 8px;font-size:13px}.mufS8W_error{color:var(--dsw-alias-state-error-primary);align-items:center;gap:8px;padding:6px 8px;font-size:12px;display:flex}.mufS8W_errorText{text-overflow:ellipsis;flex:1;overflow:hidden}.mufS8W_retry{border:.5px solid var(--dsw-alias-border-inverted);color:var(--dsw-alias-label-primary);cursor:pointer;background:0 0;border-radius:6px;padding:2px 8px;font-size:12px}";
+		const css = ".mufS8W_card{z-index:100;--dsh-scrollbar-thumb:var(--dsw-alias-scrollbar-bg-l2);--dsh-scrollbar-thumb-hover:var(--dsw-alias-scrollbar-hover-l2);background:var(--dsw-specific-menu);min-width:min(220px,100%);max-width:100%;max-height:320px;backdrop-filter:var(--dsw-menu-backdrop-filter);--dsw-elevation-stroke-color:var(--dsw-alias-border-l1);box-shadow:var(--dsw-elevation-prominent);border:0;border-radius:16px;outline:none;flex-direction:column;padding:3px;display:flex;position:absolute;bottom:calc(100% + 4px);left:0;overflow:hidden}.mufS8W_viewport{flex-direction:column;min-height:0;display:flex;overflow-y:auto}.mufS8W_row{cursor:pointer;color:var(--dsw-alias-label-primary);border-radius:7px;align-items:center;gap:6px;padding:5px 7px;font-size:12px;display:flex}.mufS8W_rowActive{background:var(--dsw-alias-interactive-bg-hover)}.mufS8W_label{flex:0 auto;align-items:baseline;gap:4px;min-width:0;display:flex}.mufS8W_labelText{white-space:nowrap;text-overflow:ellipsis;min-width:0;overflow:hidden}.mufS8W_badge{color:var(--dsw-alias-label-tertiary);letter-spacing:.2px;flex:none;align-self:flex-start;margin-top:-1px;font-size:8px;font-weight:600;line-height:10px}.mufS8W_detail{min-width:0;color:var(--dsw-alias-label-tertiary);white-space:nowrap;text-overflow:ellipsis;flex:1;font-size:11px;overflow:hidden}.mufS8W_check{color:var(--dsw-alias-label-primary);flex:none;margin-left:auto;display:inline-flex}.mufS8W_check svg{width:14px;height:14px}.mufS8W_status{color:var(--dsw-alias-label-tertiary);padding:7px 8px;font-size:12px}.mufS8W_search{border:.5px solid var(--dsw-alias-border-inverted);color:var(--dsw-alias-label-primary);background:0 0;border-radius:8px;outline:none;margin:2px 2px 3px;padding:5px 7px;font-size:12px}.mufS8W_error{color:var(--dsw-alias-state-error-primary);align-items:center;gap:6px;padding:5px 7px;font-size:11px;display:flex}.mufS8W_errorText{text-overflow:ellipsis;flex:1;overflow:hidden}.mufS8W_retry{border:.5px solid var(--dsw-alias-border-inverted);color:var(--dsw-alias-label-primary);cursor:pointer;background:0 0;border-radius:6px;padding:2px 7px;font-size:11px}";
 		const tagId = "@deepseek-ai/dsh-client-ui-commands/PopupSelectView.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
 			const tag = document.createElement("style");
@@ -1087,11 +1161,12 @@ window.__ModuleLoader__.load({
 		* store into the conversation.input.overlay anchor. Unlike the slash menu
 		* (combobox — textarea keeps focus), this shell HOLDS focus while open: the
 		* inner search input takes focus, plain typing filters the loaded options
-		* locally, Enter/↑↓ drive the filtered highlight (scrolled into view), Escape
-		* dismisses back to the composer, and ←→ keep the search input's native
-		* caret. Any pointer interaction outside the box dismisses (the click's own
-		* target takes focus). Closed state renders null; the overlay slot stays
-		* mounted. The card height clamps to the space above the composer.
+		* locally, Enter and Tab accept the filtered highlight, ↑↓ walk it (wrapping,
+		* scrolled into view), and Escape and Shift+Tab dismiss back to the composer.
+		* ←→ keep the search input's native caret. Any pointer interaction outside the
+		* box dismisses (the click's own target takes focus). Closed state renders
+		* null; the overlay slot stays mounted. The card height clamps to the space
+		* above the composer.
 		*/
 		/** Design cap on the card height (same MenuDropdown family as the slash menu). */
 		const MAX_HEIGHT = 320;
@@ -1145,6 +1220,12 @@ window.__ModuleLoader__.load({
 						ev.preventDefault();
 						popup.select(state.active);
 						return;
+					case "Tab":
+						if (!ev.shiftKey && (state.status !== "ready" || rows.length === 0)) return;
+						ev.preventDefault();
+						if (ev.shiftKey) popup.dismiss({ focusComposer: true });
+						else popup.select(state.active);
+						return;
 					case "Escape":
 						ev.preventDefault();
 						popup.dismiss({ focusComposer: true });
@@ -1230,7 +1311,7 @@ window.__ModuleLoader__.load({
 								}),
 								option.active === true && (0, react_jsx_runtime.jsx)("span", {
 									className: PopupSelectView_module_css_default.check,
-									children: (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconCheckOutline16, {})
+									children: (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconCheckOutlineRegular, {})
 								})
 							]
 						}, option.id))

package/lib/types/client/contract.d.ts

@@ -22,6 +22,12 @@ export interface SelectOption {
     /** Optional short marker rendered as a superscript beside the label. */
     readonly badge?: string;
     readonly detail?: string;
+    /**
+     * The row the shell's highlight parks on when the panel opens, so an accept
+     * gesture made without looking confirms the value in use. A business package
+     * that marks a row `active` for presentation alone would make that row the
+     * default pick.
+     */
     readonly active?: boolean;
     /** Optional in-page risk gate owned by the shared popup shell. */
     readonly confirmation?: SelectConfirmation;

package/lib/types/client/popup.d.ts

@@ -51,7 +51,12 @@ export interface PopupState {
     readonly options: readonly SelectOption[];
     /** Local filter text over the loaded options. */
     readonly search: string;
-    /** Highlight index into the filtered row list (0 when empty/pending). */
+    /**
+     * Highlight index into the filtered row list: 0 until options land; afterwards
+     * the row the loaded list marks as the current value
+     * ({@link SelectOption.active}), else 0. A search rebases it to the top of the
+     * filtered rows.
+     */
     readonly active: number;
     /** A select() settlement is in flight: further select/search/highlight no-op until it settles. */
     readonly submitting: boolean;
@@ -101,7 +106,8 @@ export declare class PopupSelectController<TCtx = unknown> {
     retry(): void;
     /**
      * Replace the local search text (pure local filter — the provider is never
-     * re-queried) and rebase the highlight onto the new filtered list.
+     * re-queried) and rebase the highlight to the top of the new filtered list:
+     * typing searches for something other than the current value.
      * @param search - the shell search input's text.
      */
     setSearch(search: string): void;

package/lib/types/client/service.d.ts

@@ -9,6 +9,8 @@
  * `rankByName`). A host/contribution name collision fails loud. Every
  * execute addresses the session's agent by sessionId — sessions are always
  * agent-backed.
+ * Catalog RPCs retain an existing Client Session through completion and
+ * wait for its initial history open to succeed before contacting the Host.
  */
 import { Service } from '@deepseek-ai/cordis';
 import type { Context } from '@deepseek-ai/cordis';
@@ -18,6 +20,12 @@ import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import type { ClientSessionContext } from '@deepseek-ai/dsh-client-ui-input-trigger/client';
 import type { CommandContribution, CommandDecoration, CommandUiContract } from './contract.ts';
 import { PopupSelectController } from './popup.ts';
+declare module '@deepseek-ai/dsh-api-session-controller/client' {
+    interface SessionReferenceSourceMap {
+        /** A command-catalog fetch waiting for initial history and its RPC result. */
+        commandCatalog: unknown;
+    }
+}
 declare module '@deepseek-ai/cordis' {
     interface Events {
         /**
@@ -68,20 +76,12 @@ export declare class CommandUiRuntime extends Service implements CommandUiContra
      * Resolve the per-session popup controller (lazy; dies with the session
      * scope). The controller's consume callback dispatches the scoped
      * consume-token event back to this session; focusComposer reaches the
-     * composer through the overlay slot currency.
+     * session's composer through the conversation input face.
      * @param actx - session-scope ctx.
      * @returns the resident controller.
+     * @throws when the Context no longer belongs to a retained Session generation.
      */
     popupFor(actx: ClientContext): PopupSelectController<ClientSessionContext>;
-    /** Composer focus hooks by session (the overlay wiring binds the textarea focus here). */
-    private readonly focusHooks;
-    /**
-     * Bind one session's composer-focus hook (overlay slot wiring; unbind on unmount).
-     * @param id - session id.
-     * @param focus - textarea focus callback.
-     * @returns the unbind disposer.
-     */
-    bindComposerFocus(id: SessionId, focus: () => void): () => void;
     /**
      * Menu candidates: host catalog + contribution availability, built-in rows
      * localized, then position filtering; sections for an empty query, the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-commands",
   "description": "Client command surface: global directory cache, '/' source, three command UI kinds, popupSelect registry",
-  "version": "0.1.6-alpha.1",
+  "version": "0.1.7-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -38,27 +38,28 @@
   },
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.3"
   },
   "devDependencies": {
     "@types/react": "~18.3.1",
     "react": "^18.2.0",
     "clsx": "^2.0.0",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-test-runtime": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-connection": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-commands": "^0.1.6-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-api-session-controller": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-store": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-session": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-ui-input-trigger": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-ui-session": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.6-alpha.1"
+    "@deepseek-ai/dsh-client-locale": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-test-runtime": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-commands": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.3",
+    "@deepseek-ai/dsh-api-session-controller": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-store": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-ui-session": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-ui-input-trigger": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-util-values": "^0.1.7-alpha.1"
   },
   "files": [
     "lib/index.js",