@deepseek-ai/dsh-client-ui-commands 0.2.0-rc.1 → 0.2.0-rc.2

package/README.i18n.yaml

@@ -18,8 +18,8 @@
   en: 01adce72791579fa
   zh: 70eb55a1529038e7
 /deepseek-ai-dsh-client-ui-commands/use-this-package/kinds-and-decorations:
-  en: 86841942f6989fbb
-  zh: 901557d3a5d0528e
+  en: 57679a20574d8b3f
+  zh: 98d5e5a7781e6de1
 /deepseek-ai-dsh-client-ui-commands/use-this-package/built-in-row-faces:
   en: e96156be95ea87e3
   zh: f5350db26483ec9f
@@ -27,8 +27,8 @@
   en: 4feecdbec0c3f39e
   zh: 618944ecade8a3a2
 /deepseek-ai-dsh-client-ui-commands/understand-the-implementation:
-  en: 0fd2b19e41605440
-  zh: 52d5c653b877a1f0
+  en: 3aeeba6c91c3ef19
+  zh: d3afb3df6d15e17b
 /deepseek-ai-dsh-client-ui-commands/further-exploration:
   en: 409c04f534d23de7
   zh: 165022d7a0a554eb

package/README.md

@@ -31,6 +31,12 @@ Mount this plugin alongside `ui-input-trigger` and `ui-conversation`; the `/` so
 
 A contribution is a client-owned command; a host-name collision fails loudly. Its UI is a popupSelect spec or an action: a callback a bare invocation runs after the trigger token is consumed, without submitting a message. Business packages own their actions and availability; the composer registers File through this same API. A decoration adds a bare-invocation popup or action to an existing host command while preserving its catalog row, argument claim, and lifecycle logging; it never fires without a matching host row. Menu queries fuzzy-match ordered, case-insensitive subsequences of command names and titles, with prefixes first and no section headings.
 
+A popupSelect spec may supply `searchLabels()` to resolve its placeholder, empty-catalog text, and no-match text for each opening. Omitted labels retain the shell's generic copy; labels from one popup never carry into the next.
+
+Options may carry `group: { name, label }`: `name` identifies the group and `label` supplies its localized sticky heading. Equal names share one group; groups retain first-occurrence order in the loaded options, including when a query hides earlier rows. Ungrouped options form one headingless block at their first occurrence. Groups without matching rows are hidden.
+
+The optional `searchMode` defaults to `'substring'`, matching `label` and `detail` case-insensitively without ranking. `'fuzzy-label'` matches only labels as ordered, case-insensitive subsequences and ranks within each group: prefixes first, then alignment score, then original row order. Both modes ignore leading and trailing query spaces; a blank query keeps every row in group order. Rendering, keyboard navigation, and selection use the same filtered order. `/model` opts into `'fuzzy-label'`; other commands retain substring matching unless they opt in.
+
 ### Built-in row faces
 
 First-party command definitions carry stable `definitionId` values. The client selects their localized titles, descriptions, icons, and input spellings by identity; changing a Host description cannot change that selection. Same-name overrides without the matching identity keep their own copy and receive no first-party aliases. Chinese and English spellings resolve through the same effective Session catalog in every locale, preserving the typed spelling in the draft and submitting the registered Host name. Contributions supply their own `label`, `description`, and `icon`, read on every candidate pass. Empty-query section order follows names, with unlisted rows closing Commands.
@@ -44,7 +50,7 @@ When the composer submits with images or generic files, only a host command decl
 <a id="understand-the-implementation"></a>
 ## Understand the implementation
 
-Menus use the shared `MenuSurface` material, including the macOS backing for background blur; custom content follows the [menu rules](../../../docs/web-styling.md#component-rules).
+Popup selection panels fill the composer overlay's width, matching the slash menu. Popup search fields keep transparent backgrounds and borders in both palettes. Grouped options use [ui-primitives](../ui-primitives/README.md#understand-the-implementation)' shared `MenuGroup` headings and `observeStickyMenuGroups`; an ordinary effect owns the asynchronous observation and rebuilds it when rendered groups change. Menus use the shared `MenuSurface` material, including the macOS backing for background blur; custom content follows the [menu rules](../../../docs/web-styling.md#component-rules).
 
 <details>
 <summary>Implementation internals — click to expand</summary>

package/README.zh.md

@@ -31,6 +31,12 @@ kind: "package-reference"
 
 贡献项是客户端自有命令，与宿主命令同名会明确报错。它的 UI 是 popupSelect 规格或动作：裸调用消费触发 token 后运行回调，不提交消息。业务包负责自己的动作及可用性，输入框通过同一 API 注册「文件」。装饰为已有宿主命令添加裸调用弹窗或动作，并保留其目录行、参数认领与生命周期记录；没有匹配的宿主行时不触发。菜单查询按顺序、不区分大小写地模糊匹配命令名与标题的子序列，前缀优先，不显示小节标题。
 
+popupSelect 规格可提供 `searchLabels()`，在每次打开时解析占位文字、空目录提示和无匹配提示。未提供时保留外壳的通用文案；一个弹窗的文案不会沿用到下一个弹窗。
+
+选项可携带 `group: { name, label }`：`name` 标识分组，`label` 提供本地化吸顶标题。同名选项归入同一组；分组保持在已加载选项中首次出现的顺序，即使查询隐藏了较早的行也不变。未分组选项在首次出现的位置组成一个无标题区块。没有匹配行的分组会隐藏。
+
+可选的 `searchMode` 默认为 `'substring'`，不区分大小写地匹配 `label` 与 `detail` 的子串，不进行相关性排序。`'fuzzy-label'` 仅匹配标签中按顺序、不区分大小写的子序列，并在组内排序：前缀优先，其次按匹配得分，最后按原始行顺序。两种模式均忽略查询首尾空格；空查询按分组顺序保留所有行。渲染、键盘导航与选择使用相同的筛选顺序。`/model` 启用 `'fuzzy-label'`；其他命令未显式启用时仍使用子串匹配。
+
 ### 内置行的展示面
 
 内置命令定义携带稳定的 `definitionId`。客户端按标识选择本地化标题、说明、图标和输入写法，修改宿主说明不会改变选择结果。没有匹配标识的同名覆盖保留自己的文案，也不获得内置别名。在任何界面语言下，中英文写法都通过同一个会话有效目录解析，草稿保留手输写法，提交使用宿主注册名。贡献项提供自己的 `label`、`description` 和 `icon`，每次生成候选项时读取。空查询按名称确定小节顺序，未列出的行排在「指令」末尾。
@@ -44,7 +50,7 @@ composer 携带图片或通用文件提交时，只有声明了 `input.attachmen
 <a id="understand-the-implementation"></a>
 ## 理解实现
 
-菜单采用共享 `MenuSurface` 材质，包括用于背景模糊的 macOS 底层；自定义内容遵循[菜单规则](../../../docs/web-styling.zh.md#component-rules)。
+弹窗选择面板撑满 composer 浮层宽度，与斜杠菜单一致。弹窗搜索框在浅／深色主题下均保持背景和边框透明。分组选项使用 [ui-primitives](../ui-primitives/README.zh.md#understand-the-implementation) 共享的 `MenuGroup` 标题与 `observeStickyMenuGroups`；普通 effect 负责异步观察，并在渲染分组变化时清理和重建观察器。菜单采用共享 `MenuSurface` 材质，包括用于背景模糊的 macOS 底层；自定义内容遵循[菜单规则](../../../docs/web-styling.zh.md#component-rules)。
 
 <details>
 <summary>实现细节——点击展开</summary>

package/lib/client.js

@@ -334,6 +334,27 @@ window.__ModuleLoader__.load({
 			return signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("command directory wait aborted");
 		}
 		//#endregion
+		//#region lib/types/client/option-groups.js
+		/**
+		* Group rows by their caller-owned group name, without sorting groups or rows.
+		* Ungrouped rows occupy one block at their first occurrence.
+		* @param options - Options in display order.
+		* @returns groups in first-occurrence order, with original option objects.
+		*/
+		function groupOptions(options) {
+			const groups = /* @__PURE__ */ new Map();
+			for (const option of options) {
+				const name = option.group?.name;
+				const existing = groups.get(name);
+				if (existing !== void 0) existing.rows.push(option);
+				else groups.set(name, {
+					group: option.group,
+					rows: [option]
+				});
+			}
+			return [...groups.values()];
+		}
+		//#endregion
 		//#region lib/types/client/popup.js
 		/**
 		* Headless popupSelect shell state: one controller per client
@@ -352,6 +373,8 @@ window.__ModuleLoader__.load({
 			status: "pending",
 			options: [],
 			search: "",
+			searchLabels: null,
+			searchMode: "substring",
 			active: 0,
 			submitting: false,
 			confirming: null,
@@ -359,16 +382,23 @@ window.__ModuleLoader__.load({
 			error: null
 		};
 		/**
-		* Filter option rows against the shell's local search text (case-insensitive
-		* substring over label and detail; blank search keeps every row).
+		* Filter rows using substring matching, or rank labels fuzzily within each group.
+		* Blank search keeps every row; fuzzy matching preserves group order.
 		* @param options - the loaded rows.
 		* @param search - the shell's search text.
-		* @returns the rows the shell shows and highlights over.
+		* @param mode - the command's policy; defaults to substring over label and detail.
+		* @returns the original option objects in the order shown and used for selection.
 		*/
-		function filterOptions(options, search) {
+		function filterOptions(options, search, mode = "substring") {
 			const query = search.trim().toLowerCase();
-			if (query === "") return options;
-			return options.filter((o) => o.label.toLowerCase().includes(query) || (o.detail?.toLowerCase().includes(query) ?? false));
+			const groups = groupOptions(options);
+			const ordered = groups.some((group) => group.group !== void 0) ? groups.flatMap((group) => group.rows) : options;
+			if (query === "") return ordered;
+			if (mode === "fuzzy-label") return groups.flatMap((group) => (0, _deepseek_ai_dsh_client_ui_primitives.rankByName)(group.rows.map((option) => ({
+				name: option.label,
+				option
+			})), query).map((row) => row.option));
+			return ordered.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
@@ -377,10 +407,11 @@ window.__ModuleLoader__.load({
 		* 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).
+		* @param mode - the command's search policy.
 		* @returns index into the filtered rows.
 		*/
-		function currentIndex(options, search) {
-			const at = filterOptions(options, search).findIndex((option) => option.active === true);
+		function currentIndex(options, search, mode) {
+			const at = filterOptions(options, search, mode).findIndex((option) => option.active === true);
 			return at === -1 ? 0 : at;
 		}
 		/** The shell's error-strip line for a settlement failure. */
@@ -414,6 +445,7 @@ window.__ModuleLoader__.load({
 			* @param segment - open-time token segment snapshot for post-select consumption.
 			*/
 			open(command, spec, context, segment) {
+				const searchLabels = spec.searchLabels?.() ?? null;
 				this.binding?.abort.abort();
 				const binding = {
 					command,
@@ -426,7 +458,9 @@ window.__ModuleLoader__.load({
 				this.state.set({
 					...CLOSED,
 					open: true,
-					command
+					command,
+					searchLabels,
+					searchMode: spec.searchMode ?? "substring"
 				});
 				this.load(binding);
 			}
@@ -439,7 +473,7 @@ window.__ModuleLoader__.load({
 						...current,
 						status: "ready",
 						options,
-						active: currentIndex(options, current.search),
+						active: currentIndex(options, current.search, current.searchMode),
 						error: null
 					});
 				}, (error) => {
@@ -489,7 +523,7 @@ window.__ModuleLoader__.load({
 			move(dir) {
 				const s = this.state.getSnapshot();
 				if (!s.open || s.status !== "ready" || s.submitting || s.confirming !== null) return;
-				const rows = filterOptions(s.options, s.search);
+				const rows = filterOptions(s.options, s.search, s.searchMode);
 				if (rows.length === 0) return;
 				const active = (s.active + dir + rows.length) % rows.length;
 				this.state.set({
@@ -505,7 +539,7 @@ window.__ModuleLoader__.load({
 			highlight(index) {
 				const s = this.state.getSnapshot();
 				if (!s.open || s.status !== "ready" || s.submitting || s.confirming !== null) return;
-				if (index < 0 || index >= filterOptions(s.options, s.search).length || index === s.active) return;
+				if (index < 0 || index >= filterOptions(s.options, s.search, s.searchMode).length || index === s.active) return;
 				this.state.set({
 					...s,
 					active: index
@@ -525,7 +559,7 @@ window.__ModuleLoader__.load({
 				const binding = this.binding;
 				const s = this.state.getSnapshot();
 				if (binding === null || !s.open || s.status !== "ready" || s.submitting || s.confirming !== null) return;
-				const option = filterOptions(s.options, s.search)[index];
+				const option = filterOptions(s.options, s.search, s.searchMode)[index];
 				if (option === void 0) return;
 				if (option.confirmation !== void 0) {
 					this.state.set({
@@ -1129,7 +1163,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);--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;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{border-radius:var(--dsw-radius-md);cursor:pointer;color:var(--dsw-alias-label-primary);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);border-radius:var(--dsw-radius-md);color:var(--dsw-alias-label-primary);background:0 0;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);border-radius:var(--dsw-radius-sm);color:var(--dsw-alias-label-primary);cursor:pointer;background:0 0;padding:2px 7px;font-size:11px}";
+		const css = ".mufS8W_card{box-sizing:border-box;z-index:100;--dsh-scrollbar-thumb:var(--dsw-alias-scrollbar-bg-l2);--dsh-scrollbar-thumb-hover:var(--dsw-alias-scrollbar-hover-l2);--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;outline:none;flex-direction:column;padding:3px;display:flex;position:absolute;bottom:calc(100% + 4px);left:0;right:0;overflow:hidden}.mufS8W_viewport{flex-direction:column;min-height:0;display:flex;overflow-y:auto}.mufS8W_row{border-radius:var(--dsw-radius-md);cursor:pointer;color:var(--dsw-alias-label-primary);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-radius:var(--dsw-radius-md);color:var(--dsw-alias-label-primary);background:0 0;border:.5px solid #0000;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);border-radius:var(--dsw-radius-sm);color:var(--dsw-alias-label-primary);cursor:pointer;background:0 0;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");
@@ -1179,12 +1213,33 @@ window.__ModuleLoader__.load({
 			const state = (0, react.useSyncExternalStore)((fn) => popup.state.subscribe(fn), () => popup.state.getSnapshot());
 			const cardRef = (0, react.useRef)(null);
 			const searchRef = (0, react.useRef)(null);
+			const viewportRef = (0, react.useRef)(null);
+			const rows = (0, react.useMemo)(() => filterOptions(state.options, state.search, state.searchMode), [
+				state.options,
+				state.search,
+				state.searchMode
+			]);
+			const groups = (0, react.useMemo)(() => groupOptions(rows), [rows]);
+			(0, react.useEffect)(() => {
+				const viewport = viewportRef.current;
+				if (viewport === null) return;
+				return (0, _deepseek_ai_dsh_client_ui_primitives.observeStickyMenuGroups)(viewport);
+			}, [
+				state.open,
+				state.status,
+				state.confirming,
+				groups
+			]);
 			const maxHeight = (0, _deepseek_ai_dsh_client_ui_primitives.useAnchoredMaxHeight)(cardRef, MAX_HEIGHT, state);
 			const active = state.open ? state.active : null;
 			(0, react.useEffect)(() => {
 				if (active === null) return;
 				cardRef.current?.querySelector("[aria-selected=\"true\"]")?.scrollIntoView({ block: "nearest" });
-			}, [active]);
+			}, [
+				active,
+				rows,
+				state.confirming
+			]);
 			(0, react.useEffect)(() => {
 				if (!state.open || state.confirming !== null) return;
 				const onPointerDown = (ev) => {
@@ -1204,8 +1259,8 @@ window.__ModuleLoader__.load({
 				if (state.open && state.confirming === null) searchRef.current?.focus();
 			}, [state.open, state.confirming]);
 			if (!state.open) return null;
-			const rows = filterOptions(state.options, state.search);
 			const confirmation = state.confirming?.confirmation;
+			const emptyLabel = state.searchLabels === null ? t("status.empty") : state.options.length === 0 ? state.searchLabels.empty : state.searchLabels.noResults;
 			const onKeyDown = (ev) => {
 				switch (ev.key) {
 					case "ArrowDown":
@@ -1233,6 +1288,39 @@ window.__ModuleLoader__.load({
 					default:
 				}
 			};
+			const renderOption = (option, index) => (0, react_jsx_runtime.jsxs)("div", {
+				role: "option",
+				"aria-selected": index === state.active,
+				"aria-label": option.badge === void 0 ? void 0 : `${option.label} ${option.badge}`,
+				className: clsx(PopupSelectView_module_css_default.row, index === state.active && PopupSelectView_module_css_default.rowActive),
+				onClick: () => {
+					popup.select(index);
+				},
+				onMouseEnter: () => {
+					popup.highlight(index);
+				},
+				children: [
+					(0, react_jsx_runtime.jsxs)("span", {
+						className: PopupSelectView_module_css_default.label,
+						children: [(0, react_jsx_runtime.jsx)("span", {
+							className: PopupSelectView_module_css_default.labelText,
+							children: option.label
+						}), option.badge !== void 0 && (0, react_jsx_runtime.jsx)("sup", {
+							className: PopupSelectView_module_css_default.badge,
+							children: option.badge
+						})]
+					}),
+					option.detail !== void 0 && (0, react_jsx_runtime.jsx)("span", {
+						className: PopupSelectView_module_css_default.detail,
+						children: option.detail
+					}),
+					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.IconCheckOutlineRegular, {})
+					})
+				]
+			}, option.id);
+			let optionIndex = 0;
 			return (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [state.confirming === null && (0, react_jsx_runtime.jsxs)(_deepseek_ai_dsh_client_ui_primitives.MenuSurface, {
 				ref: cardRef,
 				className: PopupSelectView_module_css_default.card,
@@ -1244,7 +1332,7 @@ window.__ModuleLoader__.load({
 						ref: searchRef,
 						className: PopupSelectView_module_css_default.search,
 						type: "text",
-						placeholder: t("search.placeholder"),
+						placeholder: state.searchLabels?.placeholder ?? t("search.placeholder"),
 						"aria-label": t("search.aria"),
 						value: state.search,
 						readOnly: state.submitting,
@@ -1277,44 +1365,17 @@ window.__ModuleLoader__.load({
 					}),
 					state.status === "ready" && rows.length === 0 && (0, react_jsx_runtime.jsx)("div", {
 						className: PopupSelectView_module_css_default.status,
-						children: t("status.empty")
+						children: emptyLabel
 					}),
 					state.status === "ready" && (0, react_jsx_runtime.jsx)("div", {
+						ref: viewportRef,
 						role: "listbox",
 						"aria-label": t("listbox.aria", { command: String(state.command) }),
 						className: PopupSelectView_module_css_default.viewport,
-						children: rows.map((option, index) => (0, react_jsx_runtime.jsxs)("div", {
-							role: "option",
-							"aria-selected": index === state.active,
-							"aria-label": option.badge === void 0 ? void 0 : `${option.label} ${option.badge}`,
-							className: clsx(PopupSelectView_module_css_default.row, index === state.active && PopupSelectView_module_css_default.rowActive),
-							onClick: () => {
-								popup.select(index);
-							},
-							onMouseEnter: () => {
-								popup.highlight(index);
-							},
-							children: [
-								(0, react_jsx_runtime.jsxs)("span", {
-									className: PopupSelectView_module_css_default.label,
-									children: [(0, react_jsx_runtime.jsx)("span", {
-										className: PopupSelectView_module_css_default.labelText,
-										children: option.label
-									}), option.badge !== void 0 && (0, react_jsx_runtime.jsx)("sup", {
-										className: PopupSelectView_module_css_default.badge,
-										children: option.badge
-									})]
-								}),
-								option.detail !== void 0 && (0, react_jsx_runtime.jsx)("span", {
-									className: PopupSelectView_module_css_default.detail,
-									children: option.detail
-								}),
-								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.IconCheckOutlineRegular, {})
-								})
-							]
-						}, option.id))
+						children: groups.map(({ group, rows: groupRows }) => group === void 0 ? (0, react_jsx_runtime.jsx)(react.Fragment, { children: groupRows.map((option) => renderOption(option, optionIndex++)) }, "ungrouped") : (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.MenuGroup, {
+							label: group.label,
+							children: groupRows.map((option) => renderOption(option, optionIndex++))
+						}, `group:${group.name}`))
 					})
 				]
 			}), confirmation !== void 0 && (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.RiskConfirmation, {

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

@@ -15,6 +15,13 @@ export interface SelectConfirmation {
     readonly cancelLabel: string;
     readonly confirmLabel: string;
 }
+/** Caller-owned group name and localized heading for popup options. */
+export interface SelectOptionGroup {
+    readonly name: string;
+    readonly label: string;
+}
+/** Search behavior selected by the popup owner. */
+export type PopupSearchMode = 'substring' | 'fuzzy-label';
 /** One option row of a popupSelect shell. */
 export interface SelectOption {
     readonly id: string;
@@ -22,6 +29,8 @@ export interface SelectOption {
     /** Optional short marker rendered as a superscript beside the label. */
     readonly badge?: string;
     readonly detail?: string;
+    /** Equal group names share a sticky heading; groups retain first-occurrence order. */
+    readonly group?: SelectOptionGroup;
     /**
      * 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
@@ -32,6 +41,14 @@ export interface SelectOption {
     /** Optional in-page risk gate owned by the shared popup shell. */
     readonly confirmation?: SelectConfirmation;
 }
+/** Command-owned search copy, resolved when its popup opens. */
+export interface PopupSearchLabels {
+    readonly placeholder: string;
+    /** Empty catalog, before filtering. */
+    readonly empty: string;
+    /** Nonempty catalog with no matching rows. */
+    readonly noResults: string;
+}
 /**
  * Business registration for the popupSelect command kind. Data is
  * self-served: options/onSelect use the business package's own protocol.
@@ -40,6 +57,13 @@ export interface SelectOption {
  */
 export interface PopupSelectSpec {
     readonly kind: 'popupSelect';
+    /** Defaults to substring search; fuzzy-label ranks names within each group. */
+    readonly searchMode?: PopupSearchMode;
+    /**
+     * Supply localized search copy for this opening; omitted uses the shell's generic copy.
+     * @returns search placeholder and empty-state labels.
+     */
+    searchLabels?(): PopupSearchLabels;
     options(session: ClientSessionContext, signal: AbortSignal): Promise<readonly SelectOption[]>;
     onSelect(option: SelectOption, session: ClientSessionContext): void | Promise<void>;
 }

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

@@ -14,7 +14,7 @@ export type { CommandDescriptor, DirectoryStatus } from './directory.ts';
 export { filterOptions, PopupSelectController } from './popup.ts';
 export type { PopupSelectDeps, PopupSpec, PopupState, TokenSegment } from './popup.ts';
 export type { PopupSelectInjected, PopupSelectViewProps } from './PopupSelectView.tsx';
-export type { ActionSpec, CommandContribution, CommandDecoration, CommandUiContract, CommandUiSpec, PopupSelectSpec, SelectConfirmation, SelectOption, } from './contract.ts';
+export type { ActionSpec, CommandContribution, CommandDecoration, CommandUiContract, CommandUiSpec, PopupSearchLabels, PopupSelectSpec, SelectConfirmation, SelectOption, SelectOptionGroup, PopupSearchMode, } from './contract.ts';
 export type { CommandKey } from './locales.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {

package/lib/types/client/option-groups.d.ts

@@ -0,0 +1,15 @@
+/** Stable grouping shared by popup filtering and rendering. */
+import type { SelectOption, SelectOptionGroup } from './contract.ts';
+interface OptionGroup {
+    readonly group: SelectOptionGroup | undefined;
+    readonly rows: readonly SelectOption[];
+}
+/**
+ * Group rows by their caller-owned group name, without sorting groups or rows.
+ * Ungrouped rows occupy one block at their first occurrence.
+ * @param options - Options in display order.
+ * @returns groups in first-occurrence order, with original option objects.
+ */
+export declare function groupOptions(options: readonly SelectOption[]): OptionGroup[];
+export {};
+//# sourceMappingURL=option-groups.d.ts.map

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

@@ -1,6 +1,6 @@
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
 import type { TokenSpan } from '@deepseek-ai/dsh-client-ui-input-trigger/client';
-import type { SelectOption } from './contract.ts';
+import type { PopupSearchLabels, PopupSearchMode, PopupSelectSpec, SelectOption } from './contract.ts';
 /**
  * The command token segment snapshotted at shell-open time, replayed to the
  * injected {@link PopupSelectDeps.consume} callback after a successful
@@ -21,7 +21,7 @@ export type TokenSegment = {
  * session wiring passes its session projection; the controller only carries
  * it from open() to the callbacks).
  */
-export interface PopupSpec<TCtx> {
+export interface PopupSpec<TCtx> extends Pick<PopupSelectSpec, 'searchLabels' | 'searchMode'> {
     /** Load the option rows once per open (retry after failure reuses the same signal). */
     options(context: TCtx, signal: AbortSignal): Promise<readonly SelectOption[]>;
     /** Settle the picked option against the open-time context. */
@@ -51,6 +51,10 @@ export interface PopupState {
     readonly options: readonly SelectOption[];
     /** Local filter text over the loaded options. */
     readonly search: string;
+    /** Command-owned copy for this opening; null uses generic shell labels. */
+    readonly searchLabels: PopupSearchLabels | null;
+    /** Search policy resolved from the command spec at opening. */
+    readonly searchMode: PopupSearchMode;
     /**
      * Highlight index into the filtered row list: 0 until options land; afterwards
      * the row the loaded list marks as the current value
@@ -68,13 +72,14 @@ export interface PopupState {
     readonly error: string | null;
 }
 /**
- * Filter option rows against the shell's local search text (case-insensitive
- * substring over label and detail; blank search keeps every row).
+ * Filter rows using substring matching, or rank labels fuzzily within each group.
+ * Blank search keeps every row; fuzzy matching preserves group order.
  * @param options - the loaded rows.
  * @param search - the shell's search text.
- * @returns the rows the shell shows and highlights over.
+ * @param mode - the command's policy; defaults to substring over label and detail.
+ * @returns the original option objects in the order shown and used for selection.
  */
-export declare function filterOptions(options: readonly SelectOption[], search: string): readonly SelectOption[];
+export declare function filterOptions(options: readonly SelectOption[], search: string, mode?: PopupSearchMode): readonly SelectOption[];
 /**
  * Headless controller of one session's popupSelect shell. Late settlements
  * lose their write rights through binding identity: dismiss/dispose/reopen

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.2.0-rc.1",
+  "version": "0.2.0-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -44,22 +44,22 @@
     "@types/react": "~18.3.1",
     "react": "^18.2.0",
     "clsx": "^2.0.0",
-    "@deepseek-ai/dsh-api-remotes": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-connection": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-test-runtime": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-api-session-controller": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-commands": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-session": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-util-values": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-session": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-store": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-api-remotes": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-connection": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-test-runtime": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-input-trigger": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-commands": "0.2.0-rc.2",
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-client-ui-input-trigger": "0.2.0-rc.1"
+    "@deepseek-ai/dsh-api-session-controller": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-store": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-util-values": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2"
   },
   "files": [
     "lib/index.js",