weifuwu 0.86.0 → 0.87.0

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;

package/dist/client/vdom/hooks/popup-manager.d.ts

@@ -0,0 +1,92 @@
+/**
+ * vdom 命令式弹窗内核（2027-03——一个形态：ctx.popup.open——toast 心智）
+ *
+ * 设计（design/imperative-popup-plan.md）：
+ * - **唯一形态**：openPopup(opts) → PopupHandle——调用点构建内容——内核
+ *   自管理挂载/更新/卸载/销毁（挂载/卸载/销毁在实例内——无框架机制依赖）
+ * - **每次 openPopup = 独立实例**（普通闭包状态——非 hook 状态——无共享
+ *   冲突——NavMenu applierSame 类问题根治）
+ * - **渲染串行链 + 版本守卫**：链保证串行（防并发 diff）；版本号丢弃过时
+ *   渲染（update 比渲染快时旧渲染跳过——无 applier 引用比较误判）
+ * - **零 Portal vnode**：内容直接 renderToStream 到独立 applier——主树
+ *   完全不知道浮层存在（与 ctx.toast 同构）
+ *
+ * 能力（组件层消费）：
+ * - **定位**：anchor 锚定 + placement/center/gap/margin + 视口夹紧 +
+ *   0-rect 防护 + 面板未布局 rAF 重试（复用 computePos）
+ * - **交互**：外部点击关闭（el/panel 外）+ Escape 关闭（per-instance
+ *   监听——close 时移除——无常驻）
+ * - **会话级模态**：presence（退场动画 open→exit→closed→dispose）+
+ *   trapFocus（Tab 焦点陷阱）+ lockScroll（滚动锁 + 焦点归还）
+ * - **mask**：遮罩 + 居中（maskClosable——危险操作防误触）
+ */
+import type { VNodeChild } from '../core/vnode.ts';
+import type { HookEnv } from './env.ts';
+import { type PopupPlacement } from './popup.ts';
+export type PopupPhase = 'closed' | 'open' | 'exit';
+export interface PopupOpenOptions {
+    /** 内容（VNode 或工厂——打开/更新时构建——关闭态不构建） */
+    content: VNodeChild | (() => VNodeChild);
+    /** 锚点元素（锚定浮层——getter 渲染期读最新） */
+    anchor?: HTMLElement | (() => HTMLElement | null);
+    placement?: PopupPlacement | (() => PopupPlacement);
+    /** 左对齐（默认居中于锚点——水平+垂直） */
+    center?: boolean;
+    /** 锚点与面板间距 */
+    gap?: number;
+    /** 视口边距（夹紧） */
+    margin?: number;
+    /** 定位模式（none = 组件自定义定位——.wf-modal inset:0 居中） */
+    positioning?: 'anchor' | 'none';
+    /** 自定义坐标（光标处等——覆盖 computePos——width 面板宽度跟随 trigger——
+     *  同 usePopup position 语义） */
+    position?: () => {
+        x: number;
+        y: number;
+        width?: number;
+    };
+    /** 遮罩 + 居中（Img preview 等轻量居中弹层） */
+    mask?: boolean;
+    maskCentered?: boolean;
+    /** 遮罩点击关闭（默认 true——危险操作显式 false 防误触） */
+    maskClosable?: boolean;
+    /** 会话级模态：退场动画（open→exit→closed→dispose） */
+    presence?: boolean;
+    /** 焦点陷阱（Tab 面板内循环） */
+    trapFocus?: boolean;
+    /** 滚动锁（body overflow hidden + 关闭归还焦点） */
+    lockScroll?: boolean;
+    /** 外部点击关闭（默认 true——Confirm 等危险操作显式 false） */
+    closeOnOutside?: boolean;
+    /** Escape 关闭（默认 true） */
+    closeOnEscape?: boolean;
+    /** 容器 key（同组件多个弹层区分——默认 'popup'） */
+    key?: string;
+    /** 关闭回调（内核 dispose 后——组件同步句柄状态） */
+    onClose?: () => void;
+}
+export interface PopupHandle {
+    /** 关闭（presence：exit 动画 → animationend → dispose） */
+    close(): void;
+    /** 内容更新（props 变化——diff 增量——自定义坐标同步读 position getter） */
+    update(content: VNodeChild): void;
+    /** 坐标/内容重渲染（组件状态变化后——Slider tooltip 跟随等） */
+    refresh(): void;
+    /** open getter */
+    get open(): boolean;
+}
+/**
+ * openPopup——命令式弹窗内核（唯一形态——toast 心智）
+ *
+ * 组件内部样板（受控同步）：
+ * ```ts
+ * let handle: PopupHandle | null = null
+ * const syncPopup = (props) => {
+ *   if (props.open && !handle)
+ *     handle = ctx.ui.openPopup({ anchor: () => anchorEl, content: () => panelVn(props), onClose: () => { handle = null; ctx.ui.render() } })
+ *   else if (!props.open && handle) { handle.close(); handle = null }
+ *   else if (handle) handle.update(panelVn(props))
+ * }
+ * ```
+ */
+export declare function openPopup(env: HookEnv, opts: PopupOpenOptions): PopupHandle;

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

@@ -0,0 +1,52 @@
+/**
+ * vdom hooks — usePopup（浮层弹窗——28 个浮层组件的核心依赖）
+ *
+ * 能力（设计规则 §5.4——弹窗纪律）：
+ * - **portal**：popup.portal(content, key)——createPortal 到 #__wf_portal +
+ *   fixed 定位 + 视口夹紧（禁止 absolute 相对父容器）
+ * - **定位**：placement（top/bottom/left/right）+ center:false 左对齐 +
+ *   gap/margin——打开时 refresh + 锚点变化自动重算
+ * - **el-null fallback**：锚点首帧未挂载——微任务重试
+ * - **外部点击关闭**：document mousedown——el/panel 外点击关闭
+ *   （禁止自建 overlay 遮罩——会挡按钮）
+ * - **Escape 关闭**：document keydown
+ * - **open getter**：渲染期读最新（非创建时快照）
+ * - **panelRef 稳定**：ref 回调稳定引用（mount 作用域定义）
+ *
+ * 会话级模态（presence/焦点 trap/滚动锁——Modal/Drawer）后续实现。
+ */
+import type { HookEnv } from './env.ts';
+export type PopupPlacement = 'top' | 'bottom' | 'left' | 'right';
+export type PopupPhase = 'closed' | 'open' | 'exit';
+/** Placement 别名（ui-dom 兼容——HoverCard/Popover/Tooltip 消费） */
+export type Placement = PopupPlacement;
+export declare function computePos(el: HTMLElement, win: Window, panelW: number, panelH: number, placement: PopupPlacement, gap: number, margin: number, center: boolean): {
+    top: number;
+    left: number;
+} | null;
+/** 动画检查（根 + 直接子元素——Modal/Drawer 动画在子元素——jsdom 无动画） */
+export declare function hasAnim(el: HTMLElement, win: Window): boolean;
+/** 锚点解析（**el 优先**——真实 bug：`trigger ?? el` 让 trigger 字符串
+ * （'click'——触发方式装饰——vdom 组件显式 setOpen 驱动）优先——el getter
+ * 被忽略——refresh 锚点恒 null——浮层定位 0,0（左上角——agent-browser
+ * 实测 Dropdown 面板 rect 0,0）——ui-dom 语义：el 是锚点，trigger 是方式） */
+export interface PopupPositionOptions {
+    /** 锚点元素（函数——ref 挂载后可用） */
+    el: () => HTMLElement | null;
+    /** 是否打开（关闭时跳过重算） */
+    isOpen?: () => boolean;
+    /** 重算回调（rect → 坐标）——Affix 阈值/宽度重算等 */
+    compute: (r: DOMRect) => {
+        top: number;
+        left: number;
+    };
+    /** 面板元素（视口夹紧用） */
+    panel?: () => HTMLElement | null;
+    margin?: number;
+}
+/** 弹层位置跟踪：scroll/resize 时自动重算 fixed 坐标（0 rect 防护） */
+export declare function usePopupPosition(env: HookEnv, options: PopupPositionOptions): {
+    readonly top: number;
+    readonly left: number;
+    refresh: () => void;
+};