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

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
@@ -42,5 +42,5 @@
   en: cfce26d6a603cb7d
   zh: 8332a8d1ad44abcf
 /deepseek-ai-dsh-client-ui-commands/known-limitations-and-deferred-work/dev-note:
-  en: 2f5e19244ac6c305
-  zh: e43b52ae5b4af798
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

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>
@@ -95,5 +101,3 @@ These limits define the current command surface. They are current package constr
 None.
 
 </details>
-
-**Runtime invariant:** No companion is published. This browser-side source uses the wire command directory; it emits no Cordis events and owns no cross-plugin mutable state. Its dispatch and cache behavior are asserted by this package's specs.

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>
@@ -95,5 +101,3 @@ composer 携带图片或通用文件提交时，只有声明了 `input.attachmen
 无。
 
 </details>
-
-**运行时不变式：** 不发布伴生入口。这是基于 wire 命令目录的浏览器侧 source，不发出 Cordis 事件，也不持有跨插件可变状态；dispatch 与 cache 行为由包测试覆盖。

package/lib/client.js

@@ -9,8 +9,642 @@ 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/partial-json.ts
+		/**
+		* Lazily scanned view of one JSON object's top-level fields, built from text
+		* that may still be streaming or from an already parsed object. Nothing is
+		* scanned until a reader asks; the view remembers every question it answered
+		* and reports changed answers when the owner refreshes for publication.
+		* Used for model tool-call arguments: a row reads the fields it
+		* cares about at whatever granularity it displays, at every stage of the call.
+		* @module @deepseek-ai/dsh-util-values/src/partial-json
+		*/
+		const SIMPLE_ESCAPES = {
+			"\"": "\"",
+			"\\": "\\",
+			"/": "/",
+			b: "\b",
+			f: "\f",
+			n: "\n",
+			r: "\r",
+			t: "	"
+		};
+		const CONTENT_ESCAPE = /[\\\u0000-\u001f]/u;
+		function isWhitespace(c) {
+			return c === " " || c === "\n" || c === "\r" || c === "	";
+		}
+		function isHex(c) {
+			return c >= "0" && c <= "9" || c >= "a" && c <= "f" || c >= "A" && c <= "F";
+		}
+		(class PartialArguments {
+			/** The view of a call with no arguments available. */
+			static EMPTY = PartialArguments.fromObject({});
+			/**
+			* View finished argument text without scanning it until a reader asks.
+			* @param text - the complete argument JSON text.
+			* @returns a sealed view.
+			*/
+			static fromText(text) {
+				const view = new PartialArguments();
+				view.append(text);
+				view.sealed = true;
+				return view;
+			}
+			/**
+			* View an already parsed argument payload, such as a PTC dispatch object.
+			* @param value - the parsed argument value.
+			* @returns a sealed view; a non-object payload has no fields.
+			*/
+			static fromObject(value) {
+				const view = new PartialArguments();
+				view.object = typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+				view.sealed = true;
+				return view;
+			}
+			/**
+			* The source: text so far or a parsed object, plus whether it can still grow.
+			* These are the only enumerable fields, so two views over the same source
+			* compare equal structurally however far each has been read.
+			*/
+			chunks = [];
+			object;
+			sealed = false;
+			#ends = [];
+			#size = 0;
+			#consumed = 0;
+			#mode = "root";
+			#escape = false;
+			#keyStart = 0;
+			#keyEscaped = false;
+			#key = "";
+			#current = null;
+			#nestedEnds = [];
+			#nestedInString = false;
+			#invalidAt;
+			#invalidValue = false;
+			#entries = /* @__PURE__ */ new Map();
+			#order = [];
+			#reads = /* @__PURE__ */ new Map();
+			/** Whether this view rejects further appends; does not scan text or register reads. */
+			get isSealed() {
+				return this.sealed;
+			}
+			/** Whether indexing or a content read found invalid JSON; unread value contents are not validated. */
+			get invalid() {
+				this.scan();
+				return this.#mode === "invalid" || this.#invalidValue;
+			}
+			/**
+			* Retain streamed argument text without scanning or comparing observed answers.
+			* @param fragment - the text following every fragment appended before.
+			*/
+			append(fragment) {
+				if (this.sealed) throw new Error("PartialArguments: cannot append to a sealed view");
+				if (fragment.length === 0) return;
+				this.chunks.push(fragment);
+				this.#size += fragment.length;
+				this.#ends.push(this.#size);
+			}
+			/**
+			* Reconcile a streamed prefix with authoritative complete text without joining the fragments.
+			* @param text - the final argument text, which replaces missing or conflicting deltas.
+			* @returns this view sealed with its caches retained when every character matches; otherwise a new sealed view.
+			*/
+			settle(text) {
+				if (this.object !== void 0 || text.length !== this.#size) return PartialArguments.fromText(text);
+				let offset = 0;
+				for (const chunk of this.chunks) {
+					if (!text.startsWith(chunk, offset)) return PartialArguments.fromText(text);
+					offset += chunk.length;
+				}
+				this.chunks = text.length === 0 ? [] : [text];
+				this.#ends = text.length === 0 ? [] : [text.length];
+				this.sealed = true;
+				return this;
+			}
+			/**
+			* Compare observed answers and advance their publication baseline. Unread views remain unscanned.
+			* @returns whether any observed answer changed since its first read or the preceding refresh.
+			*/
+			refresh() {
+				if (this.#reads.size === 0) return false;
+				this.scan();
+				let changed = false;
+				let completions = false;
+				for (const read of this.#reads.values()) {
+					if (read.completion) {
+						completions = true;
+						continue;
+					}
+					changed = this.refreshRead(read) || changed;
+				}
+				if (completions) {
+					for (const read of this.#reads.values()) if (read.completion) changed = this.refreshRead(read) || changed;
+				}
+				if (this.sealed) this.#reads.clear();
+				return changed;
+			}
+			refreshRead(read) {
+				const now = read.answer();
+				if (Object.is(now, read.last)) return false;
+				read.last = now;
+				return true;
+			}
+			/**
+			* Check whether no further fields can arrive.
+			* @returns whether the outer object closed, indexing failed, or the view is sealed; unread values are not validated.
+			*/
+			closed() {
+				return this.remember("closed", "", () => this.closedNow());
+			}
+			/**
+			* List discovered fields in first-appearance order.
+			* @returns top-level keys seen so far, in first-appearance order.
+			*/
+			keys() {
+				return this.remember("keys", "", () => this.keysNow(), (keys) => keys.length);
+			}
+			/**
+			* Check whether a top-level field has appeared.
+			* @param key - argument name.
+			* @returns whether the field has appeared (a string opened or another value began).
+			*/
+			has(key) {
+				return this.remember("has", key, () => this.hasNow(key));
+			}
+			/**
+			* Check whether a field's closing delimiter has arrived, without validating its contents.
+			* @param key - argument name.
+			* @returns whether its delimiter arrived and no content reader has reported an error for this value.
+			*/
+			complete(key) {
+				return this.remember("complete", key, () => this.completeNow(key));
+			}
+			/**
+			* Read string length without materializing its text.
+			* @param key - argument name.
+			* @param options - change granularity for a streaming string.
+			* @returns decoded UTF-16 length of the string field so far; undefined when absent or not a string.
+			*/
+			stringLength(key, options) {
+				const step = Math.max(1, Math.floor(options?.step ?? 1));
+				const offset = options?.offset ?? 0;
+				return this.remember(`length:${step}:${offset}`, key, () => this.lengthNow(key), (length) => length === void 0 ? void 0 : Math.ceil((length + offset) / step));
+			}
+			/**
+			* Check a string against a decoded UTF-16 length limit without materializing it.
+			* @param key - argument name.
+			* @param maxLength - decoded UTF-16 limit, floored to at least zero.
+			* @returns whether the string is longer than the limit; false when absent or not a string.
+			*/
+			stringExceeds(key, maxLength) {
+				const limit = Math.max(0, Math.floor(maxLength));
+				return this.remember(`exceeds:${limit}`, key, () => (this.lengthNow(key, limit + 1) ?? 0) > limit);
+			}
+			/**
+			* Read a decoded string, including a streaming prefix.
+			* @param key - argument name.
+			* @returns the string field's decoded text so far; undefined when absent or not a string.
+			*/
+			text(key) {
+				return this.remember("text", key, () => this.textNow(key));
+			}
+			/**
+			* Read at most the first decoded UTF-16 units of a string.
+			* @param key - argument name.
+			* @param maxLength - maximum decoded UTF-16 length, floored to at least one.
+			* @returns the bounded string prefix; undefined when absent or not a string.
+			*/
+			textPrefix(key, maxLength) {
+				const limit = Math.max(1, Math.floor(maxLength));
+				return this.remember(`prefix:${limit}`, key, () => this.textPrefixNow(key, limit));
+			}
+			/**
+			* Read a completed non-string argument.
+			* @param key - argument name.
+			* @returns the parsed non-string value once it closed; undefined while open, absent, or a string.
+			*/
+			value(key) {
+				return this.remember("value", key, () => this.valueNow(key));
+			}
+			/** Answer a question and, on a streaming view, remember it for change detection. */
+			remember(kind, key, read, comparison) {
+				this.scan();
+				const result = read();
+				if (!this.sealed) {
+					const id = `${kind}/${key}`;
+					if (!this.#reads.has(id)) this.#reads.set(id, {
+						completion: kind === "complete",
+						answer: comparison === void 0 ? read : () => comparison(read()),
+						last: comparison === void 0 ? result : comparison(result)
+					});
+				}
+				return result;
+			}
+			closedNow() {
+				return this.sealed || this.#mode === "closed" || this.#mode === "invalid";
+			}
+			keysNow() {
+				return this.object === void 0 ? this.#order : Object.keys(this.object);
+			}
+			hasNow(key) {
+				return this.object === void 0 ? this.#entries.has(key) : Object.hasOwn(this.object, key);
+			}
+			completeNow(key) {
+				if (this.object !== void 0) return Object.hasOwn(this.object, key);
+				const entry = this.#entries.get(key);
+				return entry !== void 0 && entry.end >= 0 && (entry.kind === "string" ? entry.invalidAt === void 0 : !entry.invalid);
+			}
+			lengthNow(key, limit = Number.POSITIVE_INFINITY) {
+				if (this.object !== void 0) {
+					const field = Object.hasOwn(this.object, key) ? this.object[key] : void 0;
+					return typeof field === "string" ? field.length : void 0;
+				}
+				const entry = this.#entries.get(key);
+				if (entry?.kind !== "string") return void 0;
+				if (entry.text !== void 0 && entry.text.at === entry.end) return entry.text.length;
+				const read = entry.length ??= {
+					at: entry.start,
+					length: 0,
+					text: ""
+				};
+				this.readString(entry, read, limit, false);
+				return read.length;
+			}
+			textNow(key) {
+				if (this.object !== void 0) {
+					const field = Object.hasOwn(this.object, key) ? this.object[key] : void 0;
+					return typeof field === "string" ? field : void 0;
+				}
+				const entry = this.#entries.get(key);
+				if (entry?.kind !== "string") return void 0;
+				if (entry.text === void 0 && entry.end >= 0 && entry.needsDecoding && entry.invalidAt === void 0) {
+					let text;
+					try {
+						text = JSON.parse(`"${this.slice(entry.start, entry.end)}"`);
+					} catch (_error) {}
+					if (text !== void 0) entry.text = {
+						at: entry.end,
+						length: text.length,
+						text
+					};
+				}
+				const read = entry.text ??= {
+					at: entry.start,
+					length: 0,
+					text: ""
+				};
+				this.readString(entry, read, Number.POSITIVE_INFINITY, true);
+				return read.text;
+			}
+			textPrefixNow(key, maxLength) {
+				if (this.object !== void 0) {
+					const field = Object.hasOwn(this.object, key) ? this.object[key] : void 0;
+					return typeof field === "string" ? field.slice(0, maxLength) : void 0;
+				}
+				const entry = this.#entries.get(key);
+				if (entry?.kind !== "string") return void 0;
+				const prefixes = entry.prefixes ??= /* @__PURE__ */ new Map();
+				let read = prefixes.get(maxLength);
+				if (read === void 0) {
+					read = {
+						at: entry.start,
+						length: 0,
+						text: ""
+					};
+					prefixes.set(maxLength, read);
+				}
+				this.readString(entry, read, maxLength, true);
+				return read.text;
+			}
+			valueNow(key) {
+				if (this.object !== void 0) {
+					if (!Object.hasOwn(this.object, key)) return void 0;
+					const field = this.object[key];
+					return typeof field === "string" ? void 0 : field;
+				}
+				const entry = this.#entries.get(key);
+				if (entry?.kind !== "value" || entry.end < 0 || entry.invalid) return void 0;
+				if (entry.parsed === void 0) try {
+					entry.parsed = JSON.parse(this.slice(entry.start, entry.end));
+				} catch (_error) {
+					entry.invalid = true;
+					this.#invalidValue = true;
+				}
+				return entry.parsed;
+			}
+			chunkAt(at) {
+				let low = 0;
+				let high = this.#ends.length;
+				while (low < high) {
+					const mid = low + high >>> 1;
+					if (this.#ends[mid] <= at) low = mid + 1;
+					else high = mid;
+				}
+				return low;
+			}
+			/** Materialize only a requested range, never the cumulative source. */
+			slice(start, end) {
+				if (start >= end) return "";
+				const first = this.chunkAt(start);
+				const last = this.chunkAt(end - 1);
+				const base = first === 0 ? 0 : this.#ends[first - 1];
+				if (first === last) return this.chunks[first].slice(start - base, end - base);
+				const parts = [this.chunks[first].slice(start - base)];
+				for (let i = first + 1; i < last; i++) parts.push(this.chunks[i]);
+				parts.push(this.chunks[last].slice(0, end - this.#ends[last - 1]));
+				return parts.join("");
+			}
+			readString(entry, read, limit, materialize) {
+				const end = Math.min(entry.end < 0 ? this.#consumed : entry.end, entry.invalidAt ?? Number.POSITIVE_INFINITY, this.#invalidAt ?? Number.POSITIVE_INFINITY);
+				if (!entry.needsDecoding) {
+					const length = Math.min(end - read.at, limit - read.length);
+					if (length <= 0) return;
+					if (materialize) read.text += this.slice(read.at, read.at + length);
+					read.at += length;
+					read.length += length;
+					return;
+				}
+				let chunkIndex = this.chunkAt(read.at);
+				while (read.at < end && read.length < limit) {
+					const base = chunkIndex === 0 ? 0 : this.#ends[chunkIndex - 1];
+					const chunk = this.chunks[chunkIndex];
+					const remaining = chunk.slice(read.at - base, Math.min(chunk.length, end - base));
+					const boundary = remaining.search(CONTENT_ESCAPE);
+					const length = Math.min(boundary < 0 ? remaining.length : boundary, limit - read.length);
+					if (length > 0) {
+						if (materialize) read.text += remaining.slice(0, length);
+						read.at += length;
+						read.length += length;
+						if (read.at === base + chunk.length) chunkIndex++;
+						continue;
+					}
+					const type = remaining.length > 1 ? remaining[1] : read.at + 1 < end ? this.chunks[chunkIndex + 1][0] : void 0;
+					let decoded;
+					let width = 2;
+					if (remaining[0] === "\\" && type === void 0 && entry.end < 0) return;
+					if (remaining[0] === "\\" && type === "u") {
+						const hex = this.slice(read.at + 2, Math.min(end, read.at + 6));
+						let valid = true;
+						for (let i = 0; i < hex.length; i++) if (!isHex(hex[i])) valid = false;
+						if (valid) {
+							if (hex.length < 4 && entry.end < 0) return;
+							if (hex.length === 4) decoded = String.fromCharCode(Number.parseInt(hex, 16));
+						}
+						width = 6;
+					} else if (remaining[0] === "\\" && type !== void 0) decoded = SIMPLE_ESCAPES[type];
+					if (decoded === void 0) {
+						entry.invalidAt = read.at;
+						this.#invalidValue = true;
+						return;
+					}
+					if (materialize) read.text += decoded;
+					read.length++;
+					read.at += width;
+					while (chunkIndex < this.chunks.length && read.at >= this.#ends[chunkIndex]) chunkIndex++;
+				}
+			}
+			/** Locate new field ranges without decoding or parsing their contents. */
+			scan() {
+				if (this.object !== void 0 || this.#consumed === this.#size) return;
+				for (let i = this.chunkAt(this.#consumed); i < this.chunks.length && this.#invalidAt === void 0; i++) {
+					const pending = this.chunks[i];
+					const base = i === 0 ? 0 : this.#ends[i - 1];
+					for (let index = this.#consumed - base; index < pending.length && this.#mode !== "invalid"; index++) {
+						if (this.#mode === "string" || this.#mode === "nested" && this.#nestedInString) {
+							const end = this.stringBoundary(pending, index);
+							this.#consumed += end - index;
+							index = end;
+							if (index === pending.length) break;
+						}
+						this.step(pending[index], this.#consumed);
+						this.#consumed++;
+					}
+				}
+			}
+			/** Only raw quotes and their preceding backslash runs can terminate a string. */
+			stringBoundary(fragment, start) {
+				let at = start;
+				while (true) {
+					const quote = fragment.indexOf("\"", at);
+					const end = quote < 0 ? fragment.length : quote;
+					if (this.#mode === "string") {
+						const entry = this.#current;
+						if (!entry.needsDecoding && CONTENT_ESCAPE.test(fragment.slice(at, end))) entry.needsDecoding = true;
+					}
+					let slashStart = end;
+					while (slashStart > at && fragment[slashStart - 1] === "\\") slashStart--;
+					const escaped = (end - slashStart) % 2 === 1 !== (slashStart === at && this.#escape);
+					this.#escape = quote < 0 && escaped;
+					if (quote < 0 || !escaped) return end;
+					at = quote + 1;
+				}
+			}
+			step(c, at) {
+				switch (this.#mode) {
+					case "root":
+						if (isWhitespace(c)) return;
+						if (c === "{") {
+							this.#mode = "key-or-end";
+							return;
+						}
+						this.fail();
+						return;
+					case "key-or-end":
+						if (isWhitespace(c)) return;
+						if (c === "}") {
+							this.#mode = "closed";
+							return;
+						}
+						if (c === "\"") {
+							this.beginKey(at);
+							return;
+						}
+						this.fail();
+						return;
+					case "key-only":
+						if (isWhitespace(c)) return;
+						if (c === "\"") {
+							this.beginKey(at);
+							return;
+						}
+						this.fail();
+						return;
+					case "key":
+						this.stepKey(c, at);
+						return;
+					case "colon":
+						if (isWhitespace(c)) return;
+						if (c === ":") {
+							this.#mode = "value";
+							return;
+						}
+						this.fail();
+						return;
+					case "value":
+						this.beginValue(c, at);
+						return;
+					case "string": {
+						const entry = this.#current;
+						entry.end = at;
+						this.#current = null;
+						this.#mode = "comma-or-end";
+						return;
+					}
+					case "scalar":
+						this.stepScalar(c, at);
+						return;
+					case "nested":
+						this.stepNested(c, at);
+						return;
+					case "comma-or-end":
+						if (isWhitespace(c)) return;
+						if (c === ",") {
+							this.#mode = "key-only";
+							return;
+						}
+						if (c === "}") {
+							this.#mode = "closed";
+							return;
+						}
+						this.fail();
+						return;
+					case "closed":
+						if (isWhitespace(c)) return;
+						this.fail();
+						return;
+					/* v8 ignore next 2 -- scan() stops stepping once the view is invalid. */
+					case "invalid": return;
+					/* v8 ignore next 2 -- Every scanner mode has a handler above. */
+					default: assertNever(this.#mode);
+				}
+			}
+			fail() {
+				this.#invalidAt = this.#consumed;
+				this.#mode = "invalid";
+				this.#current = null;
+			}
+			beginKey(at) {
+				this.#mode = "key";
+				this.#keyStart = at + 1;
+				this.#keyEscaped = false;
+				this.#escape = false;
+			}
+			stepKey(c, at) {
+				if (c < " ") {
+					this.fail();
+					return;
+				}
+				if (this.#escape) {
+					this.#escape = false;
+					return;
+				}
+				if (c === "\\") {
+					this.#escape = true;
+					this.#keyEscaped = true;
+					return;
+				}
+				if (c !== "\"") return;
+				const raw = this.slice(this.#keyStart, at);
+				if (this.#keyEscaped) try {
+					this.#key = JSON.parse(`"${raw}"`);
+				} catch (_error) {
+					this.fail();
+					return;
+				}
+				else this.#key = raw;
+				this.#mode = "colon";
+			}
+			open(entry) {
+				if (!this.#entries.has(this.#key)) this.#order.push(this.#key);
+				this.#entries.set(this.#key, entry);
+				this.#current = entry;
+			}
+			beginValue(c, at) {
+				if (isWhitespace(c)) return;
+				if (c === "\"") {
+					this.open({
+						kind: "string",
+						start: at + 1,
+						end: -1,
+						needsDecoding: false,
+						invalidAt: void 0,
+						length: void 0,
+						text: void 0,
+						prefixes: void 0
+					});
+					this.#escape = false;
+					this.#mode = "string";
+					return;
+				}
+				if (c === "}" || c === "," || c === ":" || c === "]") {
+					this.fail();
+					return;
+				}
+				this.open({
+					kind: "value",
+					start: at,
+					end: -1,
+					parsed: void 0,
+					invalid: false
+				});
+				if (c === "{" || c === "[") {
+					this.#mode = "nested";
+					this.#nestedEnds = [c === "{" ? "}" : "]"];
+					this.#nestedInString = false;
+					this.#escape = false;
+					return;
+				}
+				this.#mode = "scalar";
+			}
+			stepScalar(c, at) {
+				if (c !== "," && c !== "}" && !isWhitespace(c)) return;
+				this.closeValue(at);
+				this.#mode = c === "," ? "key-only" : c === "}" ? "closed" : "comma-or-end";
+			}
+			stepNested(c, at) {
+				if (this.#nestedInString) {
+					this.#nestedInString = false;
+					return;
+				}
+				if (c === "\"") {
+					this.#nestedInString = true;
+					return;
+				}
+				if (c === "{" || c === "[") {
+					this.#nestedEnds.push(c === "{" ? "}" : "]");
+					return;
+				}
+				if (c === "}" || c === "]") {
+					if (this.#nestedEnds.pop() !== c) {
+						this.fail();
+						return;
+					}
+					if (this.#nestedEnds.length === 0) {
+						this.closeValue(at + 1);
+						this.#mode = "comma-or-end";
+					}
+				}
+			}
+			closeValue(end) {
+				const entry = this.#current;
+				entry.end = end;
+				this.#current = null;
+			}
+		});
+		//#endregion
 		//#region ../../util/values/src/index.ts
 		/**
+		* Mark an unreachable closed-union branch.
+		* @param value - impossible value; an unhandled typed variant fails at the call site.
+		* @param context - optional switch-site label included in the failure message.
+		* @returns never; a runtime value that escaped its type always throws.
+		*/
+		function assertNever(value, context) {
+			const rendered = JSON.stringify(value) ?? String(value);
+			throw new Error(`unreachable variant${context ? ` in ${context}` : ""}: ${rendered}`);
+		}
+		/**
 		* 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
@@ -334,6 +968,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 +1007,8 @@ window.__ModuleLoader__.load({
 			status: "pending",
 			options: [],
 			search: "",
+			searchLabels: null,
+			searchMode: "substring",
 			active: 0,
 			submitting: false,
 			confirming: null,
@@ -359,16 +1016,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 +1041,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 +1079,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 +1092,9 @@ window.__ModuleLoader__.load({
 				this.state.set({
 					...CLOSED,
 					open: true,
-					command
+					command,
+					searchLabels,
+					searchMode: spec.searchMode ?? "substring"
 				});
 				this.load(binding);
 			}
@@ -439,7 +1107,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 +1157,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 +1173,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 +1193,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 +1797,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 +1847,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 +1893,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 +1922,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 +1966,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 +1999,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.1-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -38,28 +38,28 @@
   },
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "~4.0.4"
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
   },
   "devDependencies": {
     "@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/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-client-ui-input-trigger": "0.2.0-rc.1"
+    "@deepseek-ai/dsh-api-remotes": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-locale": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-test-runtime": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-ui-input-trigger": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-connection": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.1-alpha.1",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
+    "@deepseek-ai/dsh-api-session-controller": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-store": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-util-values": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-ui-session": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-commands": "0.2.1-alpha.1"
   },
   "files": [
     "lib/index.js",