@qilin-agent/client-ui-input-trigger 3.1.5 → 3.1.6

package/README.i18n.yaml

@@ -18,8 +18,8 @@
   en: 331a1247c318b1e3
   zh: 6689a92ce0c82942
 /qilin-agent-client-ui-input-trigger/use-this-package/keyboard-and-mouse:
-  en: b198d6256a961f99
-  zh: 292e0bb94c18c9ca
+  en: c206c2a507ba00c3
+  zh: ac6457cfb135a6bb
 /qilin-agent-client-ui-input-trigger/understand-the-implementation:
   en: 81ac247b6e84a670
   zh: a81221be009a1f47

package/README.md

@@ -29,7 +29,7 @@ Mount this plugin alongside `ui-conversation`; the menu then appears in the inpu
 
 ### Keyboard and mouse
 
-The composer surface keeps focus while the menu is open: rows pick on mousedown, the highlight rides `aria-activedescendant`, and a pointer press outside both the menu and the composer card dismisses it. Opening it from the launcher button puts the keyboard back in the editor before the menu opens, so the arrows drive it there too. Space and Enter adjudication polls the optional `matchSpace`/`matchEnter` hooks in registration order; the first non-undefined answer wins, and a source can refuse a submission it cannot consume whole. Tab acts on the highlighted completion: a candidate declaring `drill: true` routes through `onPick` with `action: 'drill'`, while an ordinary candidate settles through `action: 'pick'`; without a highlight Tab passes untouched so native focus traversal survives. Escape and Shift+Tab leave the menu instead, never settling: the exit gesture cannot consume or rewrite the draft. A dismissed menu stays dismissed: the same token re-tracked with the same query keeps its menu closed, so restoring the caret after a pointer dismissal — or after a settled command closes the surface it opened — cannot bring the menu back; typing a new query or moving to another token re-arms it. A drillable row's trailing chevron exposes the same second verb to pointer users. A source implementing the optional `header` hook additionally publishes crumbs above its group: the pipeline re-polls it on every hit with the live query and whether a drill, rather than typing, produced it, and a crumb pick routes back through `onPick` with `action: 'drill'`.
+The composer surface keeps focus while the menu is open: rows pick on mousedown, the highlight rides `aria-activedescendant`, and a pointer press outside both the menu and the composer card dismisses it. Opening it from the launcher button puts the keyboard back in the editor before the menu opens, so the arrows drive it there too. Space and Enter adjudication polls the optional `matchSpace`/`matchEnter` hooks in registration order; the first non-undefined answer wins, and a source can refuse a submission it cannot consume whole. Restore-time claim resolution polls its own optional `matchClaim` hook over the same registration order: it awaits the source's catalog and returns the claim a token names, never opening a popup, running an action, or executing the command. Tab acts on the highlighted completion: a candidate declaring `drill: true` routes through `onPick` with `action: 'drill'`, while an ordinary candidate settles through `action: 'pick'`; without a highlight Tab passes untouched so native focus traversal survives. Escape and Shift+Tab leave the menu instead, never settling: the exit gesture cannot consume or rewrite the draft. A dismissed menu stays dismissed: the same token re-tracked with the same query keeps its menu closed, so restoring the caret after a pointer dismissal — or after a settled command closes the surface it opened — cannot bring the menu back; typing a new query or moving to another token re-arms it. A drillable row's trailing chevron exposes the same second verb to pointer users. A source implementing the optional `header` hook additionally publishes crumbs above its group: the pipeline re-polls it on every hit with the live query and whether a drill, rather than typing, produced it, and a crumb pick routes back through `onPick` with `action: 'drill'`.
 
 A source may implement `openReference(session, reference)` to open a draft reference without submitting it. Acceptance may precede asynchronous catalog loading. Chips route by source name; editable tokens route through the current source lexicon. Returning `false`, a missing source, or a disposed controller leaves the editor gesture unchanged.
 

package/README.zh.md

@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 键盘与鼠标
 
-菜单打开期间 composer 表面保持焦点：行在 mousedown 时完成 pick，高亮由 `aria-activedescendant` 承载，指针落在菜单与所在 composer 卡片之外即关闭菜单。从 launcher 按钮打开菜单时会先把键盘还给编辑器再开菜单，因此方向键在那里同样可用。空格与回车裁决按注册序轮询可选的 `matchSpace`／`matchEnter` 钩子；第一个非 undefined 的应答胜出，source 也可以拒绝它无法整体消费的提交。Tab 会作用于高亮补全项：声明 `drill: true` 的候选项以 `action: 'drill'` 进入 `onPick`，普通候选项则以 `action: 'pick'` 完成选定；没有高亮项时 Tab 原样放行，原生焦点遍历不受影响。Escape 与 Shift+Tab 则是离开菜单——它们从不选定，因此退出动作不会消耗或改写草稿。被关闭的菜单保持关闭：同一个 token 以同一查询重新 track 时菜单不会重开——因此指针关闭之后恢复光标、或已选定的命令关闭它自己打开的界面，都不会把菜单召回来；输入新的查询或移到另一个 token 才会重新武装。可下钻行尾的 chevron 向指针用户提供同一个动词。实现可选 `header` 钩子的 source 还会在其分组上方发布面包屑：流水线在每次命中时用实时查询、以及该查询由下钻还是由键入产生这一事实重新询问它，点击面包屑经 `onPick` 以 `action: 'drill'` 回到该 source。
+菜单打开期间 composer 表面保持焦点：行在 mousedown 时完成 pick，高亮由 `aria-activedescendant` 承载，指针落在菜单与所在 composer 卡片之外即关闭菜单。从 launcher 按钮打开菜单时会先把键盘还给编辑器再开菜单，因此方向键在那里同样可用。空格与回车裁决按注册序轮询可选的 `matchSpace`／`matchEnter` 钩子；第一个非 undefined 的应答胜出，source 也可以拒绝它无法整体消费的提交。恢复期的认领解析按同一注册序轮询各自的 `matchClaim` 钩子：它等待该 source 的目录就绪，只返回 token 所指的认领，不打开弹窗、不运行 action、也不执行命令。Tab 会作用于高亮补全项：声明 `drill: true` 的候选项以 `action: 'drill'` 进入 `onPick`，普通候选项则以 `action: 'pick'` 完成选定；没有高亮项时 Tab 原样放行，原生焦点遍历不受影响。Escape 与 Shift+Tab 则是离开菜单——它们从不选定，因此退出动作不会消耗或改写草稿。被关闭的菜单保持关闭：同一个 token 以同一查询重新 track 时菜单不会重开——因此指针关闭之后恢复光标、或已选定的命令关闭它自己打开的界面，都不会把菜单召回来；输入新的查询或移到另一个 token 才会重新武装。可下钻行尾的 chevron 向指针用户提供同一个动词。实现可选 `header` 钩子的 source 还会在其分组上方发布面包屑：流水线在每次命中时用实时查询、以及该查询由下钻还是由键入产生这一事实重新询问它，点击面包屑经 `onPick` 以 `action: 'drill'` 回到该 source。
 
 来源可以实现 `openReference(session, reference)`，打开草稿引用而不提交。来源可以先接受预览请求，再异步加载目录。标签按来源名称路由；可编辑文本按来源当前的词表路由。返回 `false`、来源缺失或控制器已释放时，保留编辑器原有的手势处理。
 

package/lib/client.js

@@ -1287,6 +1287,24 @@ window.__ModuleLoader__.load({
 				}
 			}
 			/**
+			* Resolve the claim a persisted command chip names, polling sources'
+			* matchClaim in registration order; the first claim wins. Never acts on the
+			* token (see {@link InputTriggerSource.matchClaim}).
+			* @param token - command spelling without its argument separator, e.g. '/goal'.
+			* @param signal - abort for the caller's restore attempt.
+			* @returns the claim, or undefined when no source claims the token. Rejects
+			* when a polled source's warmup fails or `signal` aborts.
+			*/
+			async resolveClaim(token, signal) {
+				const projection = this.project();
+				for (const src of this.deps.roster.all()) {
+					if (signal.aborted) throw signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("command restore aborted");
+					if (src.matchClaim === void 0 || !token.startsWith(src.trigger)) continue;
+					const claim = await src.matchClaim(projection, token, signal);
+					if (claim !== void 0) return claim;
+				}
+			}
+			/**
 			* Drop the menu group of a disposed source (root registry change notification).
 			* @param source - the source whose registration was disposed.
 			*/

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

@@ -9,7 +9,7 @@
  */
 import type { Context as ClientContext } from '@qilin-agent/kylin';
 import { type SnapshotStore } from '@qilin-agent/client-store';
-import type { ArbitrateKey, ArbitrateOutcome, PickOutcome, ReferenceInsert } from '@qilin-agent/client-ui-conversation/client';
+import type { ArbitrateKey, ArbitrateOutcome, CommandClaim, PickOutcome, ReferenceInsert } from '@qilin-agent/client-ui-conversation/client';
 import type { SessionId } from '@qilin-agent/session/types';
 import type { MenuState, TriggerHit } from '../core/contract.ts';
 import type { InputTriggerCrumb, InputTriggerSource, PickAction, SubmitEnvelope, TriggerChar, TriggerGuard } from '../types.ts';
@@ -166,6 +166,16 @@ export declare class InputTriggerController {
      * the caller must not silently downgrade.
      */
     adjudicate(line: string, signal: AbortSignal, envelope: SubmitEnvelope): Promise<PickOutcome>;
+    /**
+     * Resolve the claim a persisted command chip names, polling sources'
+     * matchClaim in registration order; the first claim wins. Never acts on the
+     * token (see {@link InputTriggerSource.matchClaim}).
+     * @param token - command spelling without its argument separator, e.g. '/goal'.
+     * @param signal - abort for the caller's restore attempt.
+     * @returns the claim, or undefined when no source claims the token. Rejects
+     * when a polled source's warmup fails or `signal` aborts.
+     */
+    resolveClaim(token: string, signal: AbortSignal): Promise<CommandClaim | undefined>;
     /**
      * Drop the menu group of a disposed source (root registry change notification).
      * @param source - the source whose registration was disposed.

package/lib/types/types.d.ts

@@ -8,7 +8,7 @@
  * through the provider plugin's own root context captured at registration.
  */
 import type { ComponentType } from 'react';
-import type { PickOutcome, ReferenceInsert, TokenSpan } from '@qilin-agent/client-ui-conversation/client';
+import type { CommandClaim, PickOutcome, ReferenceInsert, TokenSpan } from '@qilin-agent/client-ui-conversation/client';
 import type { IconProps } from '@qilin-agent/client-ui-primitives';
 import type { SessionId } from '@qilin-agent/session/types';
 export type { ArbitrateKey, ArbitrateOutcome, BeginCommandRequest, CommandClaim, ConsumeTokenRequest, InsertReferenceRequest, InsertTextRequest, PickOutcome, ReferenceInsert, SubmitAttachment, SubmitOutcome, TokenSpan, } from '@qilin-agent/client-ui-conversation/client';
@@ -172,6 +172,14 @@ export interface InputTriggerSource {
      * submission intact.
      */
     matchEnter?(session: ClientSessionContext, line: string, signal: AbortSignal, envelope: SubmitEnvelope): Promise<PickOutcome>;
+    /**
+     * Restore-time claim resolution for a persisted command chip. Answers the
+     * claim `matchSpace` would make for `token` (e.g. '/goal') after awaiting
+     * the source's own warmup, and never acts: a token that would open a
+     * popup, run an action, or execute detached answers undefined. Rejects when
+     * the warmup fails or `signal` aborts.
+     */
+    matchClaim?(session: ClientSessionContext, token: string, signal: AbortSignal): Promise<CommandClaim | undefined>;
     /**
      * Scope-birth prewarm hook (fire-and-forget): the per-session controller
      * calls it once when the session scope comes alive so sources can fetch

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qilin-agent/client-ui-input-trigger",
   "description": "Input trigger pipeline: '/' and '@' detection, candidate menu, pick routing to registered sources",
-  "version": "3.1.5",
+  "version": "3.1.6",
   "publishConfig": {
     "access": "public"
   },
@@ -41,25 +41,25 @@
   },
   "license": "MIT",
   "peerDependencies": {
-    "@qilin-agent/kylin": "~4.0.3"
+    "@qilin-agent/kylin": "~4.0.5"
   },
   "devDependencies": {
     "@types/react": "~18.3.1",
     "react": "^18.2.0",
     "clsx": "^2.0.0",
-    "@qilin-agent/client-locale": "3.1.5",
-    "@qilin-agent/client-ui-conversation": "3.1.5",
-    "@qilin-agent/client-ui-renderer": "3.1.5",
-    "@qilin-agent/client-ui-slots": "3.1.5",
-    "@qilin-agent/client-test-runtime": "3.1.5",
-    "@qilin-agent/client-ui-primitives": "3.1.5",
-    "@qilin-agent/file-reference": "3.1.5",
-    "@qilin-agent/api-session-controller": "3.1.5",
-    "@qilin-agent/session": "3.1.5",
-    "@qilin-agent/client-store": "3.1.5",
-    "@qilin-agent/util-values": "3.1.5",
-    "@qilin-agent/client-ui-session": "3.1.5",
-    "@qilin-agent/kylin": "~4.0.3"
+    "@qilin-agent/client-locale": "3.1.6",
+    "@qilin-agent/client-ui-conversation": "3.1.6",
+    "@qilin-agent/client-ui-renderer": "3.1.6",
+    "@qilin-agent/client-ui-slots": "3.1.6",
+    "@qilin-agent/client-test-runtime": "3.1.6",
+    "@qilin-agent/client-ui-primitives": "3.1.6",
+    "@qilin-agent/kylin": "~4.0.5",
+    "@qilin-agent/api-session-controller": "3.1.6",
+    "@qilin-agent/file-reference": "3.1.6",
+    "@qilin-agent/client-store": "3.1.6",
+    "@qilin-agent/session": "3.1.6",
+    "@qilin-agent/util-values": "3.1.6",
+    "@qilin-agent/client-ui-session": "3.1.6"
   },
   "files": [
     "lib/index.js",