weifuwu 0.85.0 → 0.87.0

package/dist/client/vdom/core/transform/table.d.ts

@@ -0,0 +1,28 @@
+/**
+ * vdom transform — table（转换表——状态机核心）
+ *
+ * 转换表：oldState × newState → 策略函数（各状态文件实现）——
+ * 同态（对角）走「就地 patch」（text→setText / element→就地 diff /
+ * component→同类型复用 / hole→no-op）；异态走「转换」——
+ * 占位法核心：**锚 ↔ 真实节点 replaceChild 互换**（childNodes 长度恒定——
+ * 同构不变量——禁止 removeChild 塌缩）。
+ *
+ * 转换策略（各文件实现）：
+ *   text.ts      —— text ↔ element/component/fragment（文本节点 ↔ 结构）
+ *   hole.ts      —— hole ↔ element/component/fragment/text
+ *                  （**null <-> component / null <-> fragment 主场景**——
+ *                  条件渲染 cond ? <X/> : null 的类型切换）
+ *   element.ts   —— element ↔ component/fragment/hole/text
+ *   component.ts —— component ↔ element/fragment/hole（同类型复用——
+ *                   异类型卸载 + 重建）
+ *   fragment.ts  —— fragment ↔ element/component/hole（多节点展开 ↔ 单节点）
+
+ */
+import type { VNodeChild } from '../vnode.ts';
+import type { NodeState, TransformContext, TransitionFn } from './index.ts';
+/** 转换表（old × new → 策略）——同态 = 就地 patch（diff 层处理——表中为 null） */
+export declare const TRANSITIONS: Record<NodeState, Record<NodeState, TransitionFn | null>>;
+/** 转换调度（old × next → 策略）——同态返回 null（diff 就地 patch——不重建） */
+export declare function transitionOf(oldState: NodeState, newState: NodeState): TransitionFn | null;
+/** 执行转换（diff 调用——自动降级：同态/null 策略 → no-op） */
+export declare function runTransition(oldState: NodeState, newState: NodeState, oldNode: unknown, nextNode: VNodeChild, ctx: TransformContext): Promise<void> | void;

package/dist/client/vdom/core/transform/text.d.ts

@@ -0,0 +1,10 @@
+/**
+ * vdom transform — text（文本转换——text ↔ X）
+ *
+ * 场景：条件渲染/列表项类型切换（'a' <-> <div/> <-> 组件...）。
+ * 转换职责（old=text → new=X）：旧文本节点移除（让位）——新节点由 diff
+ * 渲染到同一位置。同态 text → text 不在本表（就地 setText——diff 层）。
+ */
+import type { TransitionFn } from './index.ts';
+/** text → X：旧文本节点移除（让位） */
+export declare const transitionText: TransitionFn;

package/dist/client/vdom/core/vnode.d.ts

@@ -0,0 +1,45 @@
+/**
+ * vdom core — vnode 纯数据面（独立实现——零引用 ui-dom）
+ *
+ * 设计（对齐 vdom-x 契约 + 设计规则 §4.0/§6.3）：
+ * ① vnode 纯数据——零回填字段（el/_render/_id 等全部在影子层——可自由克隆/
+ *    比较/序列化——用户写 JSX 就能推导 vnode 形状）
+ * ② h() 除 key 剥离外零转换——children 原样（false/嵌套数组保留——不 filter）
+ * ③ key 业务身份声明协议：key 从 props 剥离进 vnode.key（组件 props 不见 key）
+ * ④ children 值域协议：vnode/string/number/boolean/空洞(null/undefined)/嵌套数组
+ *    （数组 = 隐式 Fragment——递归展开统一在 childrenOf——单一规则源——
+ *    空洞保留——占位法保长度恒定）
+ * ⑤ 组件两阶段：工厂 = mount（一次——初始化状态/订阅/数据预取）；
+ *    renderFn = 每次渲染（同步或 async——异步边界 = ctx.data 管道——不挂起）
+ * ⑥ Fragment 内部符号——公共面不导出（数组 = 隐式 Fragment；
+ *    `<></>` 经 jsx-runtime 子路径）
+ */
+import type { UIContext } from '../context/UIContext.ts';
+/** vnode——纯数据 */
+export interface VNode {
+    /** 标签名 / 组件 / 内部符号（Fragment） */
+    type: string | symbol | Component;
+    props: Record<string, unknown>;
+    /** 业务身份声明（无自动生成——无 key = 位置身份） */
+    key: string | null;
+    children?: VNodeChild[];
+}
+/** children 值域：vnode/string/number/boolean/空洞/嵌套数组（数组 = 隐式 Fragment） */
+export type VNodeChild = VNode | string | number | boolean | null | undefined | VNodeChild[];
+/** renderFn——每次渲染（读最新 props——同步或 async——异步边界 = ctx.data） */
+export type RenderFn<P = Record<string, unknown>> = (props: P) => VNode | null | (VNode | null)[] | Promise<VNode | null | (VNode | null)[]>;
+/** 组件（两阶段）：
+ *  工厂 = mount（一次——初始化状态/订阅/数据预取（await ctx.data——管道保证））
+ *  renderFn = 每次渲染（ctx.render()/props 变化触发） */
+export type Component<P = Record<string, unknown>, C = UIContext> = (initProps: P, ctx: C) => RenderFn<P> | Promise<RenderFn<P>>;
+type HType = string | symbol | Component<any, any>;
+/** h()——创建 vnode（纯数据——除 key 剥离外零转换）
+ *  children 原样：单子节点直接存、多子节点存数组、无子节点不存——false/嵌套
+ *  数组保留（不 filter——空洞占位法在消费侧） */
+export declare function h(type: HType, props?: Record<string, unknown> | null, ...children: VNodeChild[]): VNode;
+/** jsx 运行时（自动导入——`<div/>` 编译目标——React 兼容签名 jsx(type, props, key)——
+ *  props 内 key 同样剥离；jsxs/jsxDEV 同形状（children 已在 props.children） */
+export declare function jsx(type: HType, props: Record<string, unknown> | null, key?: string | null): VNode;
+export declare const jsxs: typeof jsx;
+export declare const jsxDEV: typeof jsx;
+export {};

package/dist/client/vdom/dev/effect-guard.d.ts

@@ -0,0 +1,8 @@
+/** renderFn 执行窗口（begin/end——渲染路径副作用检测） */
+export declare function beginRender(): void;
+export declare function endRender(): void;
+/** 安装守卫（幂等——patch 一次）：
+ *  @param target 浏览器 window / node globalThis（SSR 端）
+ *  @param ssrOnly SSR 端——warn + noop（timer 不执行——unhandledRejection
+ *  崩溃链阻断——服务器进程保护）；浏览器端 warn-only */
+export declare function installEffectGuard(target: unknown, ssrOnly?: boolean): void;

package/dist/client/vdom/hooks/ai-stream.d.ts

@@ -0,0 +1,46 @@
+/**
+ * vdom hooks — ai-stream（流式 AI 工具——P2 组件迁移移植——零 ui-dom）
+ *
+ * wf: SSE 协议流式解析（event: <name> / data: <json> 块）——分发到
+ * onToken/onToolCall/onApproval 等回调——AbortController 取消——
+ * onError 统一（HTTP 状态映射/网络失败/解析失败）——provider 协议
+ * 类型来自 server/ai/types（服务端同源契约）。
+ *
+ * 组件消费（SheetGrid/SlideCanvas/Editor——AI 公式/生成）——
+ * 非公共面（内部路径导入——公共面保持 h/jsx/uiServe/UIRouter）。
+ */
+import type { WfApprovalRequest, WfDone, WfError, WfStreamEvent, WfToolCall, WfToolProgress, WfToolResult, WfUsage } from '../../../server/ai/types.ts';
+/** 事件回调面（组件消费） */
+export interface AiStreamCallbacks {
+    onToken?: (text: string) => void;
+    onToolCall?: (call: WfToolCall) => void;
+    onToolResult?: (result: WfToolResult) => void;
+    onToolProgress?: (p: WfToolProgress) => void;
+    onStep?: (step: {
+        type: 'llm' | 'tool';
+        content?: string;
+        toolCallId?: string;
+        name?: string;
+    }) => void;
+    onApproval?: (req: WfApprovalRequest) => void;
+    onUsage?: (u: WfUsage) => void;
+    onDone?: (d: WfDone) => void;
+    onError?: (e: WfError) => void;
+    /** 未知/x:* 事件兜底 */
+    onEvent?: (name: string, data: unknown) => void;
+}
+export interface AiStreamOptions extends AiStreamCallbacks {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    traceId?: string;
+    /** 事件记录（record 开关——默认开——RECORD_LIMIT 环） */
+    record?: boolean;
+}
+export interface AiStreamHandle {
+    abort(): void;
+    done: Promise<void>;
+    traceId: string;
+    events: WfStreamEvent[];
+}
+/** wf: SSE 流式请求（POST——事件回调分发——Abort 取消） */
+export declare function aiStream(url: string, body: unknown, options?: AiStreamOptions): AiStreamHandle;

package/dist/client/vdom/hooks/basic.d.ts

@@ -0,0 +1,42 @@
+/**
+ * vdom hooks — 基础 hooks（useStableRef/useOpen/useGlobalKey）
+ *
+ * 设计（render-only 模型——设计规则 §4.2）：
+ * - useStableRef：稳定引用容器（跨渲染保持——hooks 内部传递——引擎责任）
+ * - useOpen：受控/非受控开关（**受控缺回调 warn**——设计规则 §5.2——
+ *   静默不可用防护）；非受控内部状态 + 显式渲染
+ * - useGlobalKey：全局键盘监听（Escape 关闭等——unmount 自动清理——
+ *   经 ctx.browser.window——零全局直接访问）
+ */
+import type { HookEnv } from './env.ts';
+/** 稳定引用容器（跨渲染保持——回调稳定引用——hooks 内部传递） */
+export interface StableRef<T> {
+    current: T;
+}
+/** 稳定引用（**双形状**：容器 { current }——vdom 内部；ref 回调
+ *  (el) => void——ui-dom 兼容——Select 用 `useStableRef(init, cleanup)`） */
+export declare function useStableRef<T>(env: HookEnv, initial: T | ((el: T | null) => void), cleanup?: () => void): StableRef<T> | ((el: T | null) => void);
+/** useOpen 结果（getter open——渲染期读最新） */
+export interface OpenState {
+    open: boolean;
+    setOpen(v: boolean): void;
+    toggle(): void;
+}
+/** useOpen 选项（ui-dom 兼容对象形状——组件消费：{ open, onOpenChange, name }） */
+export interface UseOpenOptions {
+    open?: boolean;
+    onOpenChange?: (v: boolean) => void;
+    openOnFocus?: boolean;
+    name?: string;
+}
+/** 受控/非受控开关（受控：open 由父独占——onOpenChange 唯一出口）
+ *  **渲染期调用**（renderFn 内 ctx.ui.useOpen）——hook 状态缓存（per-instance
+ *  index）——受控值读最新 props（设计规则 §3.1——renderFn 读最新 props）
+ *  **双形状**：`useOpen(init, controlled?)`（vdom 既有）/
+ *  `useOpen({ open, onOpenChange, name })`（ui-dom 兼容——组件消费） */
+export declare function useOpen(env: HookEnv, initOrOpts: boolean | UseOpenOptions, controlled?: {
+    open?: boolean;
+    onOpenChange?: (v: boolean) => void;
+}): OpenState;
+/** 全局键盘监听（Escape 关闭等——unmount 自动清理） */
+export declare function useGlobalKey(env: HookEnv, matchOrHandler: string | ((e: KeyboardEvent) => boolean) | ((e: KeyboardEvent) => void), handler?: (e: KeyboardEvent) => void): () => void;

package/dist/client/vdom/hooks/chat.d.ts

@@ -0,0 +1,91 @@
+/**
+ * vdom hooks — useChat（AI 对话会话——流式消息累积）
+ *
+ * 设计（设计规则 §4.2——useChat 会话：消息累积/工具调用/HITL 审批——
+ * handle 带 subscribe(cb)——ctx.ui.useExternal(chat) 订阅会话变化——
+ * 流式事件 → notify → 订阅组件自动重渲染——高频 notify 由写者控制频率）：
+ * - send(text)：用户消息 + 助手流式累积（SSE/NDJSON 行解析——fetch POST）
+ * - handle 兼容 ExternalStore（state = messages getter——useExternal 消费）
+ * - stop：AbortController 中断流式
+ * - 消息形状：role/content/toolCalls/status/approval（HITL 审批位）
+ */
+import type { HookEnv } from './env.ts';
+import type { ExternalStore } from '../store.ts';
+/** 聊天消息（AI 会话——工具调用/HITL 审批位） */
+/** 工具调用（assistant 发起——HITL 审批——ui-dom 兼容 call/progress/result 状态面） */
+export interface ChatToolCall {
+    id: string;
+    name: string;
+    args: unknown;
+    approved?: boolean;
+    feedback?: string;
+    status?: 'running' | 'ok' | 'error';
+    call?: unknown;
+    progress?: unknown;
+    result?: unknown;
+    /** HITL 审批请求（ui-dom 兼容——AiChat 读 toolCall 级 approval） */
+    approval?: import('../../../server/ai/types.ts').WfApprovalRequest;
+}
+export interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    /** 推理过程（wf:done 后挂上——ReasoningBlock 展示——ui-dom 兼容） */
+    reasoning?: string;
+    /** 工具调用（assistant 发起——HITL 审批） */
+    toolCalls?: ChatToolCall[];
+    /** 消息状态（流式中/错误） */
+    status?: 'streaming' | 'error';
+    /** 用量（ui-dom 兼容） */
+    usage?: import('../../../server/ai/types.ts').WfUsage;
+    /** HITL 审批请求（ui-dom 兼容——AiChat 读消息级 approval） */
+    approval?: import('../../../server/ai/types.ts').WfApprovalRequest;
+    /** 错误（ui-dom 兼容） */
+    error?: import('../../../server/ai/types.ts').WfError;
+}
+export interface ChatOptions {
+    /** 会话端点（默认 /api/chat——POST——NDJSON 流式响应） */
+    url?: string | (() => string);
+    /** 系统提示（首条 system 消息） */
+    system?: string;
+    /** 初始消息 */
+    initialMessages?: ChatMessage[];
+    /** 流式分块解析（默认：每行 JSON——{ content }） */
+    parseChunk?: (line: string) => {
+        content?: string;
+        toolCalls?: ChatMessage['toolCalls'];
+    } | null;
+}
+/** 会话状态 */
+export type ChatStatus = 'idle' | 'streaming' | 'error';
+/** 会话 handle（兼容 ExternalStore——useExternal(chat) 订阅） */
+export interface ChatHandle extends ExternalStore<ChatMessage[]> {
+    /** 消息列表（= state——getter） */
+    messages: ChatMessage[];
+    /** 发送消息（用户消息 + 助手流式累积——无参用 state.input——ui-dom 兼容） */
+    send(text?: string): Promise<void>;
+    /** 中断流式 */
+    stop(): void;
+    /** 重试（ui-dom 兼容——AiChat onRetry——重发最后一条用户消息） */
+    retry(): void;
+    /** 清空会话 */
+    reset(): void;
+    /** 会话状态 */
+    status: ChatStatus;
+    /** 输入态（ui-dom 兼容——AiChat 受控输入） */
+    input: string;
+    setInput(v: string): void;
+    /** 流式中（ui-dom 兼容） */
+    streaming: boolean;
+    /** 最近错误（ui-dom 兼容） */
+    error: import('../../../server/ai/types.ts').WfError | null;
+    /** 用量（ui-dom 兼容——wf:usage） */
+    usage: import('../../../server/ai/types.ts').WfUsage | null;
+    /** 最近 wf:step（思考/工具指示——done/error 清空） */
+    step: import('../../../server/ai/types.ts').WfStep | null;
+    /** 响应 HITL 审批（协议 §4.5——ui-dom 兼容：
+     *  approve(decision, note?, modifiedArgs?)——modified 决策带修改后参数） */
+    approve(decision: string, note?: string, modifiedArgs?: Record<string, unknown>): Promise<void>;
+}
+/** useChat（工厂调用——会话生命周期——订阅经 useExternal） */
+export declare function useChat(env: HookEnv, opts: ChatOptions): ChatHandle;

package/dist/client/vdom/hooks/controlled.d.ts

@@ -0,0 +1,27 @@
+/**
+ * vdom hooks — useControlled（受控值——受控 props 语义）
+ *
+ * 规则（设计规则 §5.2/§5.3）：受控值由父独占——onChange 唯一出口；
+ * 非受控内部状态（hook 状态缓存——渲染期调用——读最新 props）；
+ * 受控缺回调 warn（静默不可用防护）。
+ */
+import type { HookEnv } from './env.ts';
+/** useControlled 选项（ui-dom 兼容——含 name——组件消费） */
+export interface ControlledOptions<T> {
+    value?: T;
+    onChange?: (v: T) => void;
+    name?: string;
+}
+/** useControlled 结果 */
+export interface ControlledValue<T> {
+    /** 当前值（受控读 props——非受控读内部状态） */
+    value: T;
+    /** 设置（受控 → onChange 回调；非受控 → 内部 + 重渲染） */
+    setValue(v: T): void;
+    /** 原受控选项（ui-dom 兼容——组件读 controlled 原引用） */
+    controlled: ControlledOptions<T>;
+}
+/** 受控/非受控值（渲染期调用——受控读最新 props）
+ *  **双形状**：useControlled(controlled, defaultValue?)——defaultValue 可选
+ *  （ui-dom 兼容单参对象——无默认值时非受控初始为 undefined） */
+export declare function useControlled<T>(env: HookEnv, controlled: ControlledOptions<T>, defaultValue?: T): ControlledValue<T>;

package/dist/client/vdom/hooks/drag-media.d.ts

@@ -0,0 +1,52 @@
+/**
+ * vdom hooks — drag/breakpoint（useDragDrop + useMedia/useBreakpoint）
+ *
+ * - useDragDrop：拖拽（draggable enumerated 属性显式 'true'——field/
+ *   attributes 已处理；drag 事件回调——unmount 清理）
+ * - useMedia：媒体查询匹配（matchMedia——change 监听 → 重渲染——
+ *   经 ctx.browser.window——零全局直接访问；环境无 matchMedia → 恒 false）
+ * - useBreakpoint：命名断点（min-width 语义——当前匹配的最大宽度断点）
+ */
+import type { HookEnv } from './env.ts';
+/** useDragDrop 结果（拖拽属性——应用于拖拽源/放置目标） */
+export interface DragDrop {
+    /** 拖拽源属性（draggable + drag 事件） */
+    draggableProps: {
+        draggable: true;
+        onDragStart: (e: DragEvent) => void;
+        onDragEnd: (e: DragEvent) => void;
+    };
+    /** 拖拽源属性别名（ui-dom 兼容——Kanban 用） */
+    dragProps: {
+        draggable: true;
+        onDragStart: (e: DragEvent) => void;
+        onDragEnd: (e: DragEvent) => void;
+    };
+    /** 放置目标属性 */
+    dropProps: {
+        onDragOver: (e: DragEvent) => void;
+        onDragLeave: (e: DragEvent) => void;
+        onDrop: (e: DragEvent) => void;
+    };
+}
+export interface DragDropOptions {
+    onDragStart?: (e: DragEvent, data?: unknown) => void;
+    onDragEnd?: (e: DragEvent) => void;
+    onDragOver?: (e: DragEvent) => void;
+    onDragLeave?: (e: DragEvent) => void;
+    onDrop?: (e: DragEvent, data?: unknown) => void;
+    /** 拖拽数据（dataTransfer 传递） */
+    data?: unknown;
+}
+/** 拖拽（draggable enumerated 显式 'true'——事件回调——组件层传 data） */
+export declare function useDragDrop(env: HookEnv, opts: DragDropOptions): DragDrop;
+/** 媒体查询匹配（**getter 形态——2026-08**）——返回 `() => boolean`：
+ *  任何时刻调用都返回最新匹配值——mount 闭包持有 getter 永远最新——
+ *  「必须在 renderFn 内调用」的调用位置规则**在 API 形状上不存在**
+ *  （旧快照返回：mount 闭包读一次永不更新——契约 6 静默失效类）
+ *  **登记幂等（按 query 的实例级 keyed——不依赖调用顺序）**：任意位置
+ *  任意次数调用不重复监听——change → 更新 + requestRender → 重渲染 */
+export declare function useMedia(env: HookEnv, query: string): () => boolean;
+/** 命名断点（min-width 语义——**getter 形态**——`bp()` 任何时刻最新——
+ *  事件驱动重渲染——内部 useMedia 按 query 幂等登记） */
+export declare function useBreakpoint(env: HookEnv, breakpoints: Record<string, number>): () => string;

package/dist/client/vdom/hooks/env.d.ts

@@ -0,0 +1,119 @@
+/**
+ * vdom hooks — env（hooks 环境——per 组件实例）
+ *
+ * 设计（2026-12）：hooks 经 **ctx.ui 面**调用（`ctx.ui.useXXX`）——
+ * instCtx.ui = createUi(env)——env 闭包绑定**当前组件实例**（compId 渲染
+ * 触发/卸载注册）——无全局状态（零全局依赖——测试隔离天然）。
+ *
+ * requestRender = 组件级重渲染触发（当前实现：页面级 render——组件复用
+ * 保持状态——组件级精准渲染为后续优化）。
+ */
+import type { ExternalStore } from '../store.ts';
+import { type PopupHandle, type PopupOpenOptions } from './popup-manager.ts';
+import { type TweenOptions } from './stable.ts';
+/** hooks 环境（per 组件实例——renderComponent 注入） */
+export interface HookEnv {
+    /** 组件级渲染触发（store 变化/事件驱动 hooks → 重渲染） */
+    requestRender(): void;
+    /** 卸载注册（useExternal 退订等清理） */
+    onUnmount(fn: () => void): void;
+    /** 浏览器环境（全局监听等——零全局直接访问） */
+    getBrowser(): import('../browser/Browser.ts').Browser | null;
+    /** hook 状态缓存（渲染期调用——按调用顺序 index——per-instance） */
+    nextHookIndex(): number;
+    getHookState<T>(idx: number): T | undefined;
+    setHookState<T>(idx: number, v: T): void;
+    /** **实例级 keyed 登记（2026-08——getter 化 hooks）**：按业务 key 幂等——
+     *  不依赖调用顺序（useMedia/useExternal 可在任意位置任意次数调用——
+     *  订阅注册幂等按 key——「调用位置规则」在 API 形状上不存在） */
+    getInstanceData(): Map<unknown, unknown>;
+    /** 渲染完成后回调（挂载后动作——目标元素已就绪） */
+    scheduleAfterRender(fn: () => void): void;
+    /** 共享 ctx（portal 独立通道——浮层内容组件继承 sharedCtx 独立实例） */
+    getSharedContext(): import('../context/UIContext.ts').UIContext | null;
+}
+/** hooks 注入面（ctx.ui）
+ *
+ * **getter 化纪律（2026-08——返回值形态 = 语义的载体）**：
+ * - `() => T`（getter）：会随时间变化——**任何位置调用返回最新值**——
+ *   mount 闭包持有永远最新——不存在「调用位置规则」（useExternal/
+ *   useMedia/useBreakpoint——旧快照形态的静默失效类）
+ * - `{...}`（handle）：一次性创建的资源/服务——mount 期获取长期持有
+ * - 直接值：纯计算/常量
+ * - **登记幂等**：getter 类 hook 按业务 key 登记（不依赖调用顺序）——
+ *   任意位置任意次数调用不重复订阅/监听 */
+export interface Ui {
+    /** 共享状态订阅（**getter 形态**——`get()` 永远最新——store 变化 →
+     *  组件重渲染——unmount 自动退订——订阅幂等（重复调用不重复订阅）） */
+    useExternal<T>(store: ExternalStore<T>): () => T;
+    /** 响应式信号（顶层 createSignal——getter 读 + set/update 写 + 订阅——
+     *  useExternal 同源消费（Signal 兼容 ExternalStore）） */
+    signal<T>(initial: T): import('../store.ts').Signal<T>;
+    /** 资源注册（**hold 语义**：声明的资源在组件卸载时自动释放——等价
+     *  onUnmount——推荐名——「我持有的东西，卸载时释放」） */
+    hold(fn: () => void): void;
+    /** 稳定引用（双形状：容器 { current } / ref 回调 (el) => void——ui-dom 兼容） */
+    useStableRef<T>(initial: T | ((el: T | null) => void), cleanup?: () => void): import('./basic.ts').StableRef<T> | ((el: T | null) => void);
+    /** 受控/非受控开关（受控缺回调 warn——静默不可用防护——
+     *  双形状：useOpen(init, controlled?) / useOpen({ open, onOpenChange, name })） */
+    useOpen(initOrOpts: boolean | import('./basic.ts').UseOpenOptions, controlled?: {
+        open?: boolean;
+        onOpenChange?: (v: boolean) => void;
+    }): import('./basic.ts').OpenState;
+    /** 卸载注册（ui-dom 兼容——ctx.ui.onUnmount） */
+    onUnmount(fn: () => void): void;
+    /** 全局键盘监听（Escape 关闭等——unmount 自动清理——
+     *  ui-dom 兼容单参：useGlobalKey((e) => ...) 无条件监听） */
+    useGlobalKey(matchOrHandler: string | ((e: KeyboardEvent) => boolean) | ((e: KeyboardEvent) => void), handler?: (e: KeyboardEvent) => void): () => void;
+    /** 命令式弹窗（唯一形态——2027-03：ctx.popup.open——toast 心智——
+     *  调用点构建内容——内核自管理挂载/更新/卸载——组件内部句柄同步样板） */
+    openPopup(opts: PopupOpenOptions): PopupHandle;
+    /** 弹层位置跟踪（scroll/resize 重算——Affix 阈值/宽度——0-rect 防护） */
+    usePopupPosition(options: import('./popup.ts').PopupPositionOptions): {
+        top: number;
+        left: number;
+        refresh: () => void;
+    };
+    /** 受控值（受控 props 语义——onChange 唯一出口——受控缺回调 warn） */
+    useControlled<T>(controlled: import('./controlled.ts').ControlledOptions<T>, defaultValue?: T): import('./controlled.ts').ControlledValue<T>;
+    /** 滚动位置跟踪（rAF 节流——事件驱动重渲染——视口/内部容器通用——
+     *  ui-dom 兼容：{ getScroller } 对象 / 字符串 / 元素 / 函数） */
+    useScrollPosition(target?: import('./observe.ts').ScrollTarget): import('./observe.ts').ScrollPosition;
+    /** 可见性观察（IntersectionObserver——isIn 响应式——环境无 IO → 恒 false——
+     *  ui-dom 兼容：{ root, threshold, target } 对象 / 元素 / 函数——
+     *  返回 observe/disconnect/ready——组件自管模式） */
+    useInView(options?: import('./observe.ts').UseInViewOptions | HTMLElement | (() => HTMLElement | null)): import('./observe.ts').InView;
+    /** 受控输入（内部输入态——焦点保持——IME 门控——选中回填） */
+    useControlledInput(controlled: {
+        value?: string;
+        onChange?: (v: string) => void;
+        name?: string;
+    }, opts?: {
+        name?: string;
+    }): import('./input.ts').ControlledInput;
+    /** 拖拽（draggable enumerated + drag 事件——dataTransfer 数据） */
+    useDragDrop(opts: import('./drag-media.ts').DragDropOptions): import('./drag-media.ts').DragDrop;
+    /** 媒体查询匹配（**getter 形态**——`match()` 任何时刻最新——变更→
+     *  自动重渲染——注册幂等按 query——任意位置调用） */
+    useMedia(query: string): () => boolean;
+    /** 命名断点（min-width 语义——**getter 形态**——`bp()` 当前最大断点） */
+    useBreakpoint(breakpoints: Record<string, number>): () => string;
+    /** AI 对话会话（流式消息累积——handle 兼容 useExternal 订阅） */
+    useChat(opts: import('./chat.ts').ChatOptions): import('./chat.ts').ChatHandle;
+    /** 数值补间（rAF + ease + reduced-motion 直落——目标变化自动补间——
+     *  **对象 getter**：`tween.value` 永远最新——mount 闭包持有安全） */
+    useTween(target: number, opts?: TweenOptions): {
+        readonly value: number;
+        reset: (to: number) => void;
+    };
+    /** 指针拖拽（pointerdown 捕获 → window move/up 活动期监听——卸载释放） */
+    useDrag(options: import('./stable.ts').DragOptions): {
+        onPointerDown: (e: PointerEvent) => void;
+    };
+    /** 可视视口跟踪（键盘弹起/缩放——vv 不可用 → window resize fallback） */
+    useVisualViewport(): import('./stable.ts').VisualViewportHandle;
+    /** 响应式系统偏好（prefers-reduced-motion——mount 期一次判定） */
+    useReducedMotion(): boolean;
+}
+/** 创建 ctx.ui 面（env 绑定当前组件实例） */
+export declare function createUi(env: HookEnv): Ui;

package/dist/client/vdom/hooks/input.d.ts

@@ -0,0 +1,43 @@
+/**
+ * vdom hooks — useControlledInput（受控输入——设计规则 §5.3 纪律）
+ *
+ * 核心（受控输入纪律）：**输入态不依赖受控 value 回流**——
+ * - keyword：内部输入态（输入期间 value 走内部态——不触发 onChange 回流——
+ *   父组件 render 不重挂 input——**焦点保持**）
+ * - setValue：触发 onChange（受控回流）
+ * - selectedLabel：选中回填（关闭后 input 回填选中 label——受控 onChange
+ *   不渲染时 props.value 不回流——input 空的坑）
+ * - **IME composition 门控**：中文输入法组合期间受控 value 重置打断——
+ *   isComposing 门控 + onCompositionEnd 处理最终值
+ */
+import type { HookEnv } from './env.ts';
+export interface ControlledInput {
+    /** 原受控选项（ui-dom 兼容——Mentions 读 controlled 原引用） */
+    controlled: {
+        value?: string;
+        onChange?: (v: string) => void;
+        name?: string;
+    };
+    /** 受控值（渲染期读 props） */
+    value: string;
+    /** 触发 onChange（受控回流） */
+    setValue(v: string): void;
+    /** 内部输入态（输入期间——不回流——焦点保持） */
+    keyword: string;
+    setKeyword(v: string): void;
+    /** 选中回填（关闭后 input 回填选中 label） */
+    selectedLabel: string;
+    setSelectedLabel(v: string): void;
+    /** IME 组合门控（中文输入法） */
+    isComposing: boolean;
+    onCompositionStart(): void;
+    onCompositionEnd(): void;
+}
+/** 受控输入（渲染期调用——受控值读最新 props——内部态 hook 缓存） */
+export declare function useControlledInput(env: HookEnv, controlled: {
+    value?: string;
+    onChange?: (v: string) => void;
+    name?: string;
+}, opts?: {
+    name?: string;
+}): ControlledInput;

package/dist/client/vdom/hooks/observe.d.ts

@@ -0,0 +1,60 @@
+/**
+ * vdom hooks — observe（事件驱动响应式 hooks：useScrollPosition/useInView）
+ *
+ * 设计（设计规则 §4.2——hooks 是事件驱动重渲染——浏览器事件 → render——
+ * 与 $ 的「赋值自动」本质不同）：
+ * - useScrollPosition：全局 scroll + rAF 节流——y 响应式（视口/内部容器
+ *   通用）——scroll 事件 → 重渲染——unmount 清理
+ * - useInView：IntersectionObserver——isIn 响应式——IO 回调 → 重渲染——
+ *   unmount disconnect；环境无 IO（jsdom）→ 恒 false（测试注入 mock）
+ * - **目标元素未挂载**（首帧 ref 未就绪）→ 微任务重试注册（限次——防无限）
+ *
+ * 浏览器能力经 env.getBrowser()（零全局直接访问——设计规则 §5.5）。
+ */
+import type { HookEnv } from './env.ts';
+/** useScrollPosition 选项（ui-dom 兼容对象形状——组件消费：{ getScroller }） */
+export interface UseScrollPositionOptions {
+    /** 滚动容器 getter（HTMLElement | Window——组件自管容器场景） */
+    getScroller?: () => HTMLElement | Window | null;
+    /** 容器（string 选择器 / 元素） */
+    root?: string | HTMLElement;
+}
+/** useScrollPosition 结果（**对象 getter 形态**——y/x 读时求值——mount
+ *  闭包持有永远最新——位置规则不存在；refresh 手动重算驱动） */
+export interface ScrollPosition {
+    readonly y: number;
+    readonly x: number;
+    /** 手动重算（组件调用方驱动——读当前滚动位置——不触发渲染） */
+    refresh(): void;
+}
+/** 目标解析（ui-dom 兼容：对象 { getScroller } / 字符串 / 元素 / 函数 / 缺省=窗口） */
+export type ScrollTarget = HTMLElement | (() => HTMLElement | null) | string | UseScrollPositionOptions;
+/** 滚动位置跟踪（视口或内部容器——rAF 节流——事件驱动重渲染） */
+export declare function useScrollPosition(env: HookEnv, target?: ScrollTarget): ScrollPosition;
+/** useInView 选项（ui-dom 兼容对象形状——组件消费：{ root, threshold, target }） */
+export interface UseInViewOptions {
+    /** 可见性变化回调（ui-dom 兼容——InfiniteScroll 用——双参 (entry, isIn)） */
+    onChange?(entry: unknown, isIn: boolean): void;
+    /** 根容器（元素或渲染期 getter——ui-dom 兼容） */
+    root?: HTMLElement | null | (() => HTMLElement | Element | null);
+    /** 阈值（值或渲染期 getter） */
+    threshold?: number | number[] | (() => number | number[]);
+    /** 边距（字符串或渲染期 getter——ui-dom 渲染期函数形状） */
+    rootMargin?: string | (() => string);
+    target?: HTMLElement | (() => HTMLElement | null);
+}
+/** useInView 结果（**对象 getter 形态**——isIn/ready 读时求值——mount
+ *  闭包持有永远最新） */
+export interface InView {
+    readonly isIn: boolean;
+    /** 绑定 ref（el 挂载 → 观察；null → 断开） */
+    ref(el: HTMLElement | null): void;
+    /** 手动开始观察（组件自管 el 场景——BackTop/InView） */
+    observe(el: HTMLElement): void;
+    /** 停止观察 */
+    disconnect(): void;
+    /** 是否已注册（BackTop 用：ready && !isIn → 显示） */
+    readonly ready: boolean;
+}
+/** 可见性观察（IntersectionObserver——IO 回调 → 重渲染——环境无 IO → 恒 false） */
+export declare function useInView(env: HookEnv, options?: UseInViewOptions | HTMLElement | (() => HTMLElement | null)): InView;