@icen.ai/ui 0.8.1 → 0.10.0

package/dist/behaviors/ai-composer.d.mts

@@ -1,4 +1,5 @@
-import { AiUsage } from './ai-core.js';
+import { IconName } from './icons.js';
+import { AiContent, AiUsage } from './ai-core.js';
 import { PanelSizing } from './popover.js';
 import { AiTodoItem, AiUsageRingOpts } from './ai-panel.js';
 import { AiClient, AiAuditor } from './ai-provider.js';
@@ -22,17 +23,34 @@ interface AiComposerCurrentModel {
 }
 interface AiComposerCommand {
     name: string;
+    /** Human-readable name; /name remains the stable command identifier. */
+    label?: string;
     description?: string;
+    group?: string;
+    icon?: IconName;
+    keywords?: string[];
+    /** Unavailable choices remain discoverable, with a reason, but cannot execute. */
+    disabled?: boolean;
     /** 参数提示（如 "<path>"），弹层命令行右侧灰色展示 */
     argsHint?: string;
 }
-/** 引用 kind：内置 4 种 + 开放注册；`string & {}` 保自动补全同时放行 registerRefKind 注册的任意 kind（照 charts.ts ChartTone 手法） */
-type AiComposerRefKind = 'file' | 'folder' | 'doc' | 'agent' | (string & {});
+/** 引用 kind：内置 6 种 + 开放注册；`string & {}` 保自动补全同时放行 registerRefKind 注册的任意 kind（照 charts.ts ChartTone 手法） */
+type AiComposerRefKind = 'skill' | 'tool' | 'file' | 'folder' | 'doc' | 'agent' | (string & {});
 interface AiComposerRefSource {
     kind: AiComposerRefKind;
     id: string;
     label: string;
     sub?: string;
+    description?: string;
+    icon?: IconName;
+    keywords?: string[];
+    disabled?: boolean;
+}
+/** A snapshot of one submission. Existing text-only consumers remain compatible. */
+interface AiComposerSubmission {
+    text: string;
+    refs?: AiComposerRefSource[];
+    files?: File[];
 }
 /** 引用 kind 定义（registerRefKind 的注册面）。 */
 interface AiComposerRefDef {
@@ -51,16 +69,20 @@ interface AiComposerRefDef {
 declare function registerRefKind(kind: string, def: AiComposerRefDef): void;
 /**
  * 运行态切换（spec §4.3）：
- * el 传 composer 容器或其内部任意元素（含发送钮自身），就近解析 [data-ai-composer]。
+ * el 传 composer 容器或其内部任意元素（含发送钮自身），就近解析 [data-icen-ai-composer]。
  */
 declare function setComposerRunning(el: HTMLElement, running: boolean): void;
+/** Browse without remembering syntax. Resource choices toggle; commands are staged for review, never run here. */
+declare function openComposerLibrary(el: HTMLElement, category?: string): void;
+/** Read-only snapshot for upload adapters and application-owned draft persistence. */
+declare function getComposerDraft(el: HTMLElement): AiComposerSubmission;
 /**
- * 初始化 root 下的全部 [data-ai-composer]（root 自身匹配时包含自身）。
+ * 初始化 root 下的全部 [data-icen-ai-composer]（root 自身匹配时包含自身）。
  * 幂等；返回销毁函数（复刻 initBackTop 约定）。
  */
 declare function initAiComposer(root?: ParentNode): () => void;
 /**
- * 配置模型切换（§8）：工具条出现模型钮，弹层按 provider 分组 + 搜索过滤 + 当前勾选。
+ * 配置模型切换（§8）：工具条出现模型钮，弹层按 provider 分组 + 搜索过滤 + 当前轻高亮。
  * current 缺省取第一个 provider 的第一个模型（静默选中，不派事件）。
  * 选择派 icen:ai-model-change {provider, model, label, context}；
  * 选中模型的 context 自动成为 setComposerUsage 的 total 默认值（显式 opts.total 优先）。
@@ -97,12 +119,20 @@ interface AiComposerBindOpts {
     /**
      * 传入即托管对话（client 模式）：icen:ai-send → renderAiMessage 用户消息 + running +
      * client.stream → assistant 消息 + createAiStream 逐 chunk 追加 → done 收尾（meta 自动填
-     * token/成本）；错误 → setError + fail；stop → session.cancel()；排队消息每轮完成自动发送。
+     * token/成本）；错误 → setError + fail；stop → session.cancel()；成功后续发队列，停止/失败暂停。
      * 需要 messages 容器。history 由绑定层维护（system 消息可先经 client 直接对话时自带）。
      */
     client?: AiClient;
-    /** 消息挂载容器（.ai-chat-scroll 或任意元素；client 模式必填） */
+    /** 消息挂载容器（.icen-ai-chat-scroll 或任意元素；client 模式必填） */
     messages?: HTMLElement;
+    /** Resolve uploaded files / authorised resources into provider-neutral content parts.
+     * Called for the captured submission, with cancellation. No upload or tool execution is guessed.
+     * Files without an adapter produce a retryable error, rather than being silently dropped. */
+    prepareMessage?: (draft: AiComposerSubmission, context: {
+        signal: AbortSignal;
+    }) => AiContent | Promise<AiContent>;
+    /** Pure-event bindings may scope done events to one conversation; defaults to document for compatibility. */
+    eventTarget?: EventTarget;
     /**
      * 用量环自动更新（监听 document 的 icen:ai-done）：
      * 'context'（默认）= 上下文估算口径（ai-core contextEstimate——环语义正确）；
@@ -116,13 +146,15 @@ interface AiComposerBindOpts {
     /** 运行态自动管理（默认 true）：icen:ai-send → running；icen:ai-done → 解除 */
     running?: boolean;
     /**
-     * 三弹层（模型/命令/引用）尺寸的整体程序覆盖（PanelSizing 契约）：
-     * 优先于 composer 根上的 data-panel-*（三弹层共用的用户覆盖面）与各弹层内置默认，
-     * 一次设置对三个弹层同时生效。
+     * 四弹层（模型/命令/引用/目录）尺寸的整体程序覆盖（PanelSizing 契约）：
+     * 优先于 composer 根上的 data-panel-*（四弹层共用的用户覆盖面）与各弹层内置默认，
+     * 一次设置对四个弹层同时生效。
      */
     popoverSizing?: PanelSizing;
 }
 interface AiComposerBinding {
+    /** Retry the latest failed/stopped managed response in place. False when busy or unavailable. */
+    retry(): boolean;
     /** 解绑全部监听并中止进行中的托管会话（composer 本身的 init 不受影响） */
     unbind(): void;
 }
@@ -134,4 +166,4 @@ interface AiComposerBinding {
  */
 declare function bindComposer(el: HTMLElement, opts?: AiComposerBindOpts): AiComposerBinding;
 
-export { type AiComposerBindOpts, type AiComposerBinding, type AiComposerCommand, type AiComposerCurrentModel, type AiComposerRefDef, type AiComposerRefKind, type AiComposerRefSource, type AiProviderModelOption, type AiProviderOption, bindComposer, initAiComposer, registerRefKind, setComposerCommands, setComposerModels, setComposerRefs, setComposerRunning, setComposerTodo, setComposerUsage };
+export { type AiComposerBindOpts, type AiComposerBinding, type AiComposerCommand, type AiComposerCurrentModel, type AiComposerRefDef, type AiComposerRefKind, type AiComposerRefSource, type AiComposerSubmission, type AiProviderModelOption, type AiProviderOption, bindComposer, getComposerDraft, initAiComposer, openComposerLibrary, registerRefKind, setComposerCommands, setComposerModels, setComposerRefs, setComposerRunning, setComposerTodo, setComposerUsage };