weifuwu 0.94.0 → 0.95.0

package/dist/level5/client/components/ActionSheet/ActionSheet.ts

@@ -0,0 +1,150 @@
+/** ActionSheet：动作面板——移动端底部滑出（命令列表 + 取消按钮，usePopup 会话级模态）（showcase /components/actionsheet） */
+/**
+ * weifuwu/client/components — ActionSheet 动作面板（移动端底部滑出）
+ *
+ * 命令列表 + 取消按钮（iOS 风格）——移动端 App 常用弹层（照片选择/分享/
+ * 更多操作）。与 Modal/Drawer 同款会话级模态（openPopup presence 退场状态机 +
+ * 焦点 trap + 滚动锁）。
+ *
+ * 纪律：
+ * - 受控纪律（§5.2）：open 由父控制 + onClose 必须提供
+ * - 键盘：role=menu + menuitem，方向键上下移动 + Enter 选择 + Escape 关闭
+ * - 选择后自动关闭（onSelect(key) + onClose()）
+ * - 危险操作项 danger（--wf-color-error-text 语义文字色）
+ * - 图标走 Icon 组件（IconName）或任意 VNode
+ */
+import type { Component } from '../../../../level6/client/vdom/index.ts'
+import type { UIContext } from '../../../../level6/client/vdom/index.ts'
+import { h } from '../../../../level6/client/vdom/index.ts'
+import type { IconName } from '../Icon/Icon.ts'
+import { Icon } from '../Icon/Icon.ts'
+
+export interface ActionSheetItem {
+  key: string
+  label: string
+  /** 图标：IconName（内置）或任意 VNode（业务自定义） */
+  icon?: IconName | any
+  /** 危险操作（红色语义文字） */
+  danger?: boolean
+  disabled?: boolean
+}
+
+export interface ActionSheetProps {
+  open: boolean
+  items: ActionSheetItem[]
+  /** 点击项回调（选择后组件自动关闭） */
+  onSelect?: (key: string)=> void
+  onClose: ()=> void
+  /** 取消按钮文案（默认「取消」） */
+  cancelText?: string
+  /** 可选标题（面板顶部） */
+  title?: string
+}
+
+export const ActionSheet: Component<ActionSheetProps> = (_init, ctx: UIContext)=> {
+  // ── mount（只一次）：行为契约（弹层四件套——presence/trap/lock/Esc/遮罩） ──
+  const ov = ctx.ui.useOverlay({ role: 'dialog' })
+  /** 键盘焦点项（方向键移动——menu 语义——业务面保留） */
+  let focusKey = ''
+
+  return (props: ActionSheetProps)=> {
+    const { open, items, onSelect, onClose, cancelText, title } = props
+
+    // 键盘：方向键上下 + Enter 选择（menu 语义——跳过 disabled）
+    const onKeyDown = (e: KeyboardEvent)=> {
+      const idx = items.findIndex((i)=> i.key === focusKey)
+      const dir = e.key === 'ArrowDown' ? 1 : e.key === 'ArrowUp' ? -1 : 0
+      if (dir !== 0) {
+        e.preventDefault()
+        let next = -1
+        for (let i = 1; i <= items.length; i++) {
+          const cand = (idx + dir * i + items.length) % items.length
+          if (!items[cand]?.disabled) { next = cand; break }
+        }
+        if (next === -1) return
+        focusKey = items[next].key
+        ctx.render()
+        // **roving focus（menu 语义——验证实测修复 2027-XX）**：方向键必须移动
+        // DOM 焦点（仅更新内部 focusKey 不可观察且被原生「Enter=点击焦点项」
+        // 旁路——焦点项与 focusKey 分裂）——渲染后显式聚焦目标项（跳过 disabled）
+        const target = document.querySelector<HTMLElement>(`[data-actionsheet-key="${focusKey}"]`)
+        target?.focus()
+        return
+      }
+      if (e.key === 'Enter' && focusKey) {
+        const item = items.find((i)=> i.key === focusKey)
+        if (item && !item.disabled) {
+          onSelect?.(item.key)
+          onClose()
+        }
+      }
+    }
+    // 渲染期维护焦点项（render-only——面板打开默认第一项；键盘移动后更新）
+    if (!items.some((i)=> i.key === focusKey)) focusKey = items[0]?.key ?? ''
+
+    const overlay = h('div', {
+      ...ov.maskProps,
+      class: 'wf-actionsheet-overlay',
+    })
+
+    const itemEls = items.map((item)=> {
+      const icon = typeof item.icon === 'string'
+        ? h(Icon, { name: item.icon as IconName, size: 18, className: 'wf-actionsheet-icon' })
+        : item.icon
+      return h('button', {
+        key: item.key,
+        type: 'button',
+        role: 'menuitem',
+        'data-actionsheet-key': item.key,
+        class: [
+          'wf-actionsheet-item',
+          item.danger ? 'wf-actionsheet-item--danger' : '',
+          item.disabled ? 'wf-actionsheet-item--disabled' : '',
+        ].filter(Boolean).join(' '),
+        disabled: item.disabled || undefined,
+        onClick: item.disabled ? undefined : ()=> {
+          onSelect?.(item.key)
+          onClose()
+        },
+      }, [
+        icon ?? null,
+        h('span', { class: 'wf-actionsheet-item-label' }, item.label),
+      ])
+    })
+
+    const cancelBtn = h('button', {
+      type: 'button',
+      class: 'wf-actionsheet-cancel',
+      onClick: onClose,
+    }, cancelText ?? '取消')
+
+    const panel = h('div', {
+      class: 'wf-actionsheet-panel',
+      role: 'menu',
+      'aria-label': title ?? '操作面板',
+      onKeyDown,
+      onClick: (e: Event)=> e.stopPropagation(),
+    }, [
+      title ? h('div', { class: 'wf-actionsheet-title' }, title) : null,
+      ...itemEls,
+      h('div', { class: 'wf-actionsheet-divider' }),
+      cancelBtn,
+    ])
+
+    const root = h('div', {
+      ...ov.panelProps,
+      class: `wf-actionsheet ${open ? 'wf-actionsheet--enter' : 'wf-actionsheet--exit'}`,
+      'aria-label': title ?? '操作面板',
+      tabIndex: -1,
+    }, [overlay, panel])
+
+    // 渲染期同步（openPopup 生命周期——受控 + 内容更新——每次渲染恒调用）
+    ov.sync(()=> root, {
+      open: !!open,
+      onOpenChange: (v)=> { if (!v) onClose() },
+      presence: true,
+    })
+
+    return null
+  }
+}

package/dist/level5/client/components/Affix/Affix.css

@@ -0,0 +1,16 @@
+/* weifuwu/client/components — Affix */
+
+.wf-affix {
+  font-family: var(--wf-font-sans);
+}
+
+.wf-affix-sentinel {
+  /* 占位：保持文档流位置，fixed 时内容脱离文档流不塌陷 */
+}
+
+.wf-affix-content {
+  transition: none;
+}
+/* ── 语义标记类（DOM 钩子——无样式：测试定位/用户扩展——:where 零优先级显式声明） ── */
+:where(.wf-affix-content--fixed) {}
+:where(.wf-affix-sentinel--active) {}

package/dist/level5/client/components/Affix/Affix.d.ts

@@ -0,0 +1,17 @@
+/** Affix：回到顶部（滚动超 400px 显示）+ 固定导航（距顶 80px 钉住）（showcase /components/affix） */
+import type { Component, VNodeChild } from '../../../../level6/client/vdom/index.ts';
+export interface AffixProps {
+    /** 距视口顶部偏移，滚动超过该值后固定（px），默认 0 */
+    offsetTop?: number;
+    /** 滚动容器（默认 window） */
+    target?: () => HTMLElement | Window;
+    children?: VNodeChild;
+    className?: string;
+    [key: string]: any;
+}
+/** 固定定位（对应 antd/EP Affix）：滚动超过阈值后固定元素，保持占位与宽度
+ * 实现：ctx.ui.useScrollPosition（全局 scroll 监听 + rAF 节流，内置方案）——
+ * mount 时算一次阈值（sentinel 文档位置 - offsetTop），滚动位置响应式驱动 fixed 判定。
+ * 不用 IO：IO 只在交叉状态变化时回调，瞬间滚动后 sentinel 从视口外下方到视口外上方
+ * isIntersecting 都是 false → 不回调（Affix 需要连续位置跟踪，IO 语义不匹配）。 */
+export declare const Affix: Component<AffixProps>;

package/dist/level5/client/components/Affix/Affix.ts

@@ -0,0 +1,110 @@
+/** Affix：回到顶部（滚动超 400px 显示）+ 固定导航（距顶 80px 钉住）（showcase /components/affix） */
+import type {Component, VNodeChild} from '../../../../level6/client/vdom/index.ts'
+import type { UIContext } from '../../../../level6/client/vdom/index.ts'
+import { h } from '../../../../level6/client/vdom/index.ts'
+
+export interface AffixProps {
+  /** 距视口顶部偏移，滚动超过该值后固定（px），默认 0 */
+  offsetTop?: number
+  /** 滚动容器（默认 window） */
+  target?: ()=> HTMLElement | Window
+  children?: VNodeChild
+  className?: string
+  [key: string]: any
+}
+
+/** 固定定位（对应 antd/EP Affix）：滚动超过阈值后固定元素，保持占位与宽度
+ * 实现：ctx.ui.useScrollPosition（全局 scroll 监听 + rAF 节流，内置方案）——
+ * mount 时算一次阈值（sentinel 文档位置 - offsetTop），滚动位置响应式驱动 fixed 判定。
+ * 不用 IO：IO 只在交叉状态变化时回调，瞬间滚动后 sentinel 从视口外下方到视口外上方
+ * isIntersecting 都是 false → 不回调（Affix 需要连续位置跟踪，IO 语义不匹配）。 */
+export const Affix: Component<AffixProps> = (_init, ctx)=> {
+  // ── mount（只一次）──
+  let wrapEl: HTMLElement | null = null
+  let wrapWidth = 0
+  // 初始 Infinity：首次 render 时 fixed=false（不误固定）；ref 挂载后微任务里算出真实阈值
+  let threshold = Infinity
+  let lastOffsetTop: number | undefined
+
+  const propsRef: any = { ..._init }
+
+  const getScroller = ()=> propsRef.target ? propsRef.target() : window
+  const scroll = ctx.ui.useScrollPosition({ getScroller })
+
+  // 阈值/宽度重算经 usePopupPosition 的 compute（scroll/resize 全局监听 + rAF 节流驱动，
+  // 不再自建 window resize 监听）。rect 视口位置 + 当前滚动 = 文档位置；fixed = scrollY >= 文档位置 - offsetTop
+  const pos = ctx.ui.usePopupPosition({
+    el: ()=> wrapEl,
+    isOpen: ()=> true,
+    compute: (r)=> {
+      const scroller = getScroller()
+      // 滚动量经 ctx.browser 统一（scrollingElement 优先——window.scrollY 在
+      // 部分环境恒 0 会导致 threshold 漂移）；非 window 容器直接读 scrollTop
+      const sy = scroller instanceof Window
+        ? ctx.browser?.scrollTop() ?? 0
+        : (scroller as HTMLElement).scrollTop ?? 0
+      threshold = r.top + sy - (propsRef.offsetTop ?? 0)
+      wrapWidth = r.width
+      return { top: 0, left: 0 }
+    },
+  })
+
+  const stableRef = (node: HTMLElement | null)=> {
+    if (node) {
+      wrapEl = node
+      // ref 在 appendChild 之前触发（元素未连接文档，rect 无效）→ 微任务里等连接后重算
+      queueMicrotask(()=> {
+        pos.refresh()
+        scroll.refresh()
+      })
+    } else {
+      wrapEl = null
+    }
+  }
+
+  return (props)=> {
+    Object.assign(propsRef, props)
+    const { offsetTop = 0, children, className, ...rest } = props
+
+    // offsetTop 运行时变化：重算阈值（非滚动帧的布局读取，可接受）
+    if (offsetTop !== lastOffsetTop) {
+      lastOffsetTop = offsetTop
+      if (wrapEl) pos.refresh()
+    }
+
+    // **阈值/宽度渲染期直算（2027-XX——竞态根治）**：此前 threshold 由
+    // usePopupPosition.compute 副作用更新、fixed 判定由 scroll.y 流驱动渲染
+    // ——两线无顺序保证：容器级单次滚动时渲染先跑（threshold 仍初始
+    // Infinity → 永不固定）、compute 后更新 → 无后续渲染 → 卡死（实测）。
+    // 渲染期直算 = 单一数据流（滚动量响应式 → 渲染 → 读布局算阈值）——
+    // 布局读取与 offsetTop 分支同一纪律（非滚动帧可接受）
+    if (wrapEl) {
+      const rect = wrapEl.getBoundingClientRect()
+      const scroller = getScroller()
+      if (scroller instanceof Window) {
+        // window：rect.top + scrollY = 文档位置
+        threshold = rect.top + (ctx.browser?.scrollTop() ?? 0) - offsetTop
+      } else {
+        // **容器：rect.top − 容器视口 top + scrollTop = 容器内滚动位置**
+        //（rect.top 已含 window 滚动与容器视口偏移——直接 + scrollTop 会
+        // 混入容器视口偏移——容器级永不固定实证——两滚动作标系不同）
+        const sc = scroller as HTMLElement
+        threshold = rect.top - sc.getBoundingClientRect().top + sc.scrollTop - offsetTop
+      }
+      wrapWidth = rect.width
+    }
+
+    const fixed = scroll.y >= threshold
+
+    return h('div', { class: ['wf-affix', className].filter(Boolean).join(' '), ...rest }, [
+      h('div', {
+        ref: stableRef,
+        class: ['wf-affix-sentinel', fixed ? 'wf-affix-sentinel--active' : ''].join(' '),
+      }),
+      h('div', {
+        class: ['wf-affix-content', fixed ? 'wf-affix-content--fixed' : ''].filter(Boolean).join(' '),
+        style: fixed ? { position: 'fixed', top: `${offsetTop}px`, width: `${wrapWidth}px` } : undefined,
+      }, children),
+    ])
+  }
+}

package/dist/level5/client/components/AiChat/AiChat.css

@@ -0,0 +1,88 @@
+/* weifuwu/client/components — AiChat（标准 AI 对话界面） */
+
+.wf-aichat {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wf-gap-sm);
+  font-family: var(--wf-font-sans);
+  font-size: var(--wf-font-size-sm);
+  line-height: var(--wf-line-height);
+  color: var(--wf-color-text);
+}
+
+.wf-aichat-list {
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: var(--wf-gap-sm);
+  padding: var(--wf-space-sm);
+  border: var(--wf-border-width) solid var(--wf-color-border);
+  border-radius: var(--wf-radius);
+  background: var(--wf-color-bg);
+}
+
+.wf-aichat-empty {
+  margin: var(--wf-space-lg) 0;
+  text-align: center;
+  color: var(--wf-color-text-secondary);
+  font-size: var(--wf-font-size-sm);
+}
+
+.wf-aichat-msg {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wf-gap-xs);
+}
+
+.wf-aichat-tools,
+.wf-aichat-approval {
+  max-width: 100%;
+}
+
+.wf-aichat-bubble {
+  display: inline-block;
+  max-width: 85%;
+  padding: var(--wf-space-sm) var(--wf-space-md);
+  border-radius: var(--wf-radius);
+  font-size: var(--wf-font-size-sm);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.wf-aichat-msg--user {
+  align-items: flex-end;
+}
+
+.wf-aichat-msg--assistant {
+  align-items: flex-start;
+}
+
+.wf-aichat-bubble--user {
+  background: var(--wf-color-primary);
+  color: var(--wf-color-on-brand);
+}
+
+.wf-aichat-bubble--assistant {
+  background: var(--wf-color-bg-tertiary);
+  color: var(--wf-color-text);
+}
+
+.wf-aichat-status {
+  font-size: var(--wf-font-size-xs);
+  color: var(--wf-color-info-text);
+}
+
+.wf-aichat-usage {
+  font-size: var(--wf-font-size-xs);
+  color: var(--wf-color-text-secondary);
+}
+
+.wf-aichat-error {
+  font-size: var(--wf-font-size-xs);
+  color: var(--wf-color-error-text);
+  background: var(--wf-color-error-bg);
+  border-radius: var(--wf-radius);
+  padding: var(--wf-space-sm);
+}
+/* ── 语义标记类（DOM 钩子——无样式：测试定位/用户扩展——:where 零优先级显式声明） ── */
+:where(.wf-aichat-inputbar--raised) {}

package/dist/level5/client/components/AiChat/AiChat.d.ts

@@ -0,0 +1,53 @@
+/** AiChat：useChat + 标准对话界面：流式 token / 工具卡 / 审批卡 / 自动滚动，协议对页面透明（showcase /components/aichat） */
+/**
+ * AiChat — 标准 AI 对话组件（useChat 的标准展示层）
+ *
+ * 组件库第一个领域复合组件：接收 ctx.ui.useChat() 返回的 handle  // audit-exempt: 用法示例文档（组件契约 = 接收 useChat handle）
+ * 渲染完整对话界面：消息气泡、工具调用卡（ToolCallCard）、HITL 审批卡
+ * （ApprovalCard）、思考/工具状态、usage、错误 + 重试、输入条 + 自动滚动。
+ *
+ * 分工：
+ *   - useChat（hook）= 会话语义 + 协议（数据层）
+ *   - AiChat（组件）= 标准界面（展示层，5 分钟出可交互对话页）
+ *   - 需要完全自定义 UI 的应用直接用 useChat + 自有渲染（hook 保持灵活路径）
+ *
+ * 约定（手动优先）：内部无 $，let + 事件；自动滚动经 ref + scroll 事件。
+ * 文案默认中文（与 ToolCallCard/ApprovalCard 一致），labels 可覆盖。
+ *
+ * ```tsx
+ * const $ = ctx.ui.useChat({ url: '/api/chat', approveUrl: '/api/approve' })  // audit-exempt: 用法示例文档（组件契约 = 接收 useChat handle）
+ * return ()=> h(AiChat, { chat: $ })
+ * ```
+ */
+import type { Component } from '../../../../level6/client/vdom/index.ts';
+import type { ChatHandle as UseChatHandle, ChatMessage as UiMessage } from '../../../../level3/vdom/hooks/chat.ts';
+import type { WfError, WfUsage, WfApprovalRequest } from '../../../server/ai/types.ts';
+import type { JsonSchema } from '../JsonSchemaForm/JsonSchemaForm.ts';
+export interface AiChatLabels {
+    send: string;
+    stop: string;
+    retry: string;
+    thinking: string;
+    runningTool: (name?: string) => string;
+    tokens: (u: WfUsage) => string;
+    error: (e: WfError) => string;
+    placeholder: string;
+    empty: string;
+}
+export interface AiChatProps {
+    /** ctx.ui.useChat() 返回的会话 handle（同一 $，状态变化自动重渲染） */ chat: UseChatHandle;
+    /** 消息列表最大高度（默认 '70vh'） */
+    maxHeight?: string;
+    /** 界面文案覆盖 */
+    labels?: Partial<AiChatLabels>;
+    /** 自定义气泡渲染逃生舱（默认纯文本） */
+    renderMessage?: (msg: UiMessage) => any;
+    /** 工具参数渲染（透传 ToolCallCard） */
+    renderToolArgs?: (args: Record<string, unknown>) => any;
+    /** 审批修改参数：按审批请求返回工具参数 schema（返回 undefined 则审批卡无修改入口；
+     *  提交修改后参数 → chat.approve('modified', …)——后端按 modifiedArgs 执行） */
+    approveSchema?: (request: WfApprovalRequest) => JsonSchema | undefined;
+    /** 键盘弹起时输入区 fixed 抬升（全屏 chat 布局用；内联卡片默认 false——原生聚焦滚动已够） */
+    raiseOnKeyboard?: boolean;
+}
+export declare const AiChat: Component<AiChatProps>;

package/dist/level5/client/components/AiChat/AiChat.ts

@@ -0,0 +1,235 @@
+/** AiChat：useChat + 标准对话界面：流式 token / 工具卡 / 审批卡 / 自动滚动，协议对页面透明（showcase /components/aichat） */
+/**
+ * AiChat — 标准 AI 对话组件（useChat 的标准展示层）
+ *
+ * 组件库第一个领域复合组件：接收 ctx.ui.useChat() 返回的 handle  // audit-exempt: 用法示例文档（组件契约 = 接收 useChat handle）
+ * 渲染完整对话界面：消息气泡、工具调用卡（ToolCallCard）、HITL 审批卡
+ * （ApprovalCard）、思考/工具状态、usage、错误 + 重试、输入条 + 自动滚动。
+ *
+ * 分工：
+ *   - useChat（hook）= 会话语义 + 协议（数据层）
+ *   - AiChat（组件）= 标准界面（展示层，5 分钟出可交互对话页）
+ *   - 需要完全自定义 UI 的应用直接用 useChat + 自有渲染（hook 保持灵活路径）
+ *
+ * 约定（手动优先）：内部无 $，let + 事件；自动滚动经 ref + scroll 事件。
+ * 文案默认中文（与 ToolCallCard/ApprovalCard 一致），labels 可覆盖。
+ *
+ * ```tsx
+ * const $ = ctx.ui.useChat({ url: '/api/chat', approveUrl: '/api/approve' })  // audit-exempt: 用法示例文档（组件契约 = 接收 useChat handle）
+ * return ()=> h(AiChat, { chat: $ })
+ * ```
+ */
+
+import type { Component } from '../../../../level6/client/vdom/index.ts'
+import { createClientBrowser } from '../../../../level6/client/vdom/index.ts'
+import { h } from '../../../../level6/client/vdom/index.ts'
+import type { ChatHandle as UseChatHandle, ChatMessage as UiMessage } from '../../../../level3/vdom/hooks/chat.ts'
+import type { WfError, WfUsage, WfApprovalRequest } from '../../../server/ai/types.ts'
+import type { JsonSchema } from '../JsonSchemaForm/JsonSchemaForm.ts'
+import { ToolCallCard } from '../ToolCallCard/ToolCallCard.ts'
+import { ApprovalCard } from '../ApprovalCard/ApprovalCard.ts'
+import { ReasoningBlock } from '../ReasoningBlock/ReasoningBlock.ts'
+import { ChatInput } from '../ChatInput/ChatInput.ts'
+
+// ── 类型 ─────────────────────────────────────────────────
+
+export interface AiChatLabels {
+  send: string
+  stop: string
+  retry: string
+  thinking: string
+  runningTool: (name?: string)=> string
+  tokens: (u: WfUsage)=> string
+  error: (e: WfError)=> string
+  placeholder: string
+  empty: string
+}
+
+export interface AiChatProps {
+  /** ctx.ui.useChat() 返回的会话 handle（同一 $，状态变化自动重渲染） */  // audit-exempt: 用法示例文档（组件契约 = 接收 useChat handle）
+  chat: UseChatHandle
+  /** 消息列表最大高度（默认 '70vh'） */
+  maxHeight?: string
+  /** 界面文案覆盖 */
+  labels?: Partial<AiChatLabels>
+  /** 自定义气泡渲染逃生舱（默认纯文本） */
+  renderMessage?: (msg: UiMessage)=> any
+  /** 工具参数渲染（透传 ToolCallCard） */
+  renderToolArgs?: (args: Record<string, unknown>)=> any
+  /** 审批修改参数：按审批请求返回工具参数 schema（返回 undefined 则审批卡无修改入口；
+   *  提交修改后参数 → chat.approve('modified', …)——后端按 modifiedArgs 执行） */
+  approveSchema?: (request: WfApprovalRequest)=> JsonSchema | undefined
+  /** 键盘弹起时输入区 fixed 抬升（全屏 chat 布局用；内联卡片默认 false——原生聚焦滚动已够） */
+  raiseOnKeyboard?: boolean
+}
+
+const defaultLabels: AiChatLabels = {
+  send: '发送',
+  stop: '停止',
+  retry: '重试',
+  thinking: '🤔 思考中…',
+  runningTool: (name)=> (name ? `执行工具 ${name}` : '执行工具…'),
+  tokens: (u)=> `tokens: ${u.prompt_tokens}→${u.completion_tokens}`,
+  error: (e)=> `${e.code}: ${e.message}`,
+  placeholder: '输入消息，回车发送…',
+  empty: '输入消息开始对话。',
+}
+
+// ── 组件 ─────────────────────────────────────────────────
+
+export const AiChat: Component<AiChatProps> = (initProps, ctx)=> {
+  const _browser = ctx.browser ?? createClientBrowser()
+  // ── 手动状态（组件库约定：let + 事件，不依赖 $）──
+  let listEl: HTMLElement | undefined
+  let stickToBottom = true
+
+  // 订阅 chat 变更（render-only 共享原语）：chat 是父组件持有的共享会话（活引用，
+  // props 浅比较恒等 → 三态 skip 命中），父 dirty 不会驱动本组件重渲染 →
+  // 订阅：任何会话状态变化 → 自身重渲染。**跟随最新 chat**（父换 handle → 重新订阅——
+  // 防“订阅旧 handle：新会话流式更新但界面无输出”——真实事故：父组件违反稳定契约传新 handle）
+  let currentChat: UseChatHandle = initProps.chat
+  let unsubChat: (()=> void) | undefined
+  const resubscribe = ()=> {
+    unsubChat?.()
+    const c = currentChat as UseChatHandle & { subscribe?: (cb: ()=> void) => ()=> void }
+    unsubChat = c?.subscribe ? c.subscribe(()=> ctx.render()) : undefined
+  }
+  resubscribe()
+  // 卸载退订（ref 纪律：稳定 ref + null 分支只在真卸载触发）
+  const rootRef = (el: any)=> { if (!el) { unsubChat?.(); unsubChat = undefined } }
+
+  // 可视视口跟踪：虚拟键盘弹起时输入区抬升到键盘上方（fixed 底部栏场景）
+  const vv = ctx.ui.useVisualViewport()
+
+  const scrollToBottom = ()=> {
+    if (listEl) listEl.scrollTop = listEl.scrollHeight
+  }
+
+  // 滚动位置跟踪（useScrollPosition：全局 scroll 监听 + rAF 节流，替代自建 listEl scroll 监听）。
+  // y 响应式变化自动 dirty → render 里重算 stickToBottom（贴底判定，距底 <48px 视为贴底）。
+  const scroll = ctx.ui.useScrollPosition({ getScroller: ()=> listEl ?? null })
+
+  // 稳定 ref 函数：跨渲染保持同一引用。
+  // weifuwu 的 ref-diff 在 ref 函数引用变化时调用旧 ref(null)——若 ref 内联在 render 里，
+  // 每次重渲染都会触发 null 分支（退订 watcher / 移除监听），必须把 ref 定义在 mount 作用域。
+  const listRef = (el: any)=> {
+    if (el && !listEl) {
+      listEl = el
+      scroll.refresh() // 初始 y
+      queueMicrotask(scrollToBottom)
+    } else if (!el && listEl) {
+      listEl = undefined
+    }
+  }
+
+  // ── render（每次 dirty/props 变化）──
+  return (props)=> {
+    const { chat, raiseOnKeyboard = false } = props
+    const labels: AiChatLabels = { ...defaultLabels, ...props.labels }
+
+    // §5.3 受控输入纪律：输入态走内部 keyword（IME 组合期间不回流传受控 value——
+    // 否则组合被打断，中文输入法无法输入 → 消息发不出 → “没有流式输出”的真实根因）
+    // 受控 value = chat.input（共享 handle 的输入态）；Enter 时写入 chat.input + send
+    if (chat !== currentChat) {
+      currentChat = chat
+      resubscribe() // 换 handle → 重新订阅（新会话的 notify 才能驱动本组件）
+    }
+
+
+    // 贴底判定（useScrollPosition 的 y 响应式驱动；scrollHeight/clientHeight 读当前 DOM）
+    if (listEl) {
+      stickToBottom = listEl.scrollHeight - scroll.y - listEl.clientHeight < 48
+    }
+
+    // 自动滚动：内容更新且用户未上翻 → 微任务内滚到底（render 返回后 patch 已完成）
+    if (stickToBottom) queueMicrotask(scrollToBottom)
+
+    const msgs = (chat.messages ?? []) as UiMessage[]
+    const nodes: any[] = []
+
+    if (msgs.length === 0) {
+      nodes.push(h('p', { class: 'wf-aichat-empty' }, labels.empty))
+    }
+    for (const m of msgs) {
+      nodes.push(renderMessage(m, props, labels))
+    }
+    if (chat.step) {
+      nodes.push(
+        h('div', { class: 'wf-aichat-status' },
+          chat.step.type === 'llm' ? labels.thinking : labels.runningTool(chat.step.name)),
+      )
+    }
+    if (chat.usage) nodes.push(h('div', { class: 'wf-aichat-usage' }, labels.tokens(chat.usage)))
+    if (chat.error) nodes.push(h('div', { class: 'wf-aichat-error' }, labels.error(chat.error)))
+
+    return h('div', { class: 'wf-aichat', ref: rootRef }, [
+      h('div', {
+        class: 'wf-aichat-list',
+        style: { maxHeight: props.maxHeight ?? '70vh' },
+        ref: listRef,
+      }, nodes),
+      // 输入条（ChatInput 独立组件——§5.3 受控输入纪律内置：IME 组合/Enter 发送/streaming 切换）
+      h('div', {
+        class: `wf-aichat-inputbar${vv.keyboardOpen && raiseOnKeyboard ? ' wf-aichat-inputbar--raised' : ''}`,
+        // 键盘弹起（opt-in，全屏 chat 布局）：fixed 抬升到键盘上方（bottom = 键盘高度）
+        style: vv.keyboardOpen && raiseOnKeyboard
+          ? { position: 'fixed', left: '0', right: '0', bottom: `${Math.max(0, _browser?.viewportHeight() - (vv.height + vv.offsetTop)) + 8}px`, zIndex: 'var(--wf-z-popover)' }
+          : undefined,
+      }, [
+        h(ChatInput, {
+          value: chat.input ?? '',
+          onChange: (v: string)=> { chat.setInput(v) }, // 输入期每键同步共享 handle（发送读 state.input）
+          onSend: (text: string)=> {
+            chat.setInput(text) // 写入共享 handle（send 读 state.input）
+            chat.send()
+          },
+          streaming: chat.streaming,
+          onStop: ()=> chat.stop(),
+          error: chat.error ? chat.error.message : null,
+          onRetry: ()=> chat.retry(),
+          labels: { send: labels.send, stop: labels.stop, retry: labels.retry, placeholder: labels.placeholder },
+        }),
+      ]),
+    ])
+  }
+}
+
+// ── 单条消息：工具卡 + 审批卡 + 气泡 ──────────────────────
+
+function renderMessage(m: UiMessage, props: AiChatProps, _labels: AiChatLabels): any {
+  const nodes: any[] = []
+
+  if (m.toolCalls?.length) {
+    const cards = m.toolCalls.map((tc, i)=>
+      h(ToolCallCard, {
+        key: `${m.id}-tool-${i}`,
+        call: tc.call,
+        progress: tc.progress,
+        result: tc.result,
+        renderArgs: props.renderToolArgs,
+      }))
+    nodes.push(h('div', { class: 'wf-aichat-tools' }, cards))
+  }
+
+  if (m.approval) {
+    const card = h(ApprovalCard, {
+      request: m.approval,
+      argsSchema: props.approveSchema?.(m.approval),
+      onApprove: (modifiedArgs?: Record<string, unknown>)=> props.chat.approve(modifiedArgs ? 'modified' : 'approved', undefined, modifiedArgs),
+      onReject: (note?: string)=> props.chat.approve('rejected', note ?? '用户拒绝'),
+    })
+    nodes.push(h('div', { class: 'wf-aichat-approval' }, card))
+  }
+
+  if (m.reasoning) {
+    nodes.push(h(ReasoningBlock, {
+      content: m.reasoning,
+      streaming: m.status === 'streaming',
+    }))
+  }
+
+  nodes.push(h('div', { class: `wf-aichat-bubble wf-aichat-bubble--${m.role}` },
+    props.renderMessage ? props.renderMessage(m) : (m.content || '…')))
+
+  return h('div', { key: m.id, class: `wf-aichat-msg wf-aichat-msg--${m.role}` }, nodes)
+}