weifuwu 0.87.0 → 0.89.0

package/content/components/wave.md

@@ -1,43 +0,0 @@
-# Wave · components
-
-## 概述
-
-点击水波纹动效——包装任意可点击元素（纯 CSS，reduced-motion 自动降级）
-
-## 典型场景
-
-- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
-
-## API
-
-| prop | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `children` | `any` | 否 |  |
-| `className` | `string` | 否 |  |
-| `color` | `string` | 否 | 波纹颜色（默认 currentColor 12% 透明） |
-
-## 用法示例
-
-> （P1 迁移 CODE 字符串）
-
-## 纪律/坑
-
-> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
-
-## 关系
-
-- ↑ 用于页面模式：（暂无）
-- ↑ 用于应用：（暂无）
-- → 后端能力：（暂无）
-
-## 文件位置
-
-| 文件 | 路径 |
-|------|------|
-| 源码 | `src/client/components/Wave/Wave.ts` |
-| 样式 | `src/client/components/Wave/Wave.css` |
-| 测试 | `src/client/components/Wave/Wave.test.ts` |
-
-## 验证
-
-> agent-browser 走查：打开 `/components/core/wave` ——（P1 填充具体步骤）

package/content/guides/ai-chat-family.md

@@ -1,24 +0,0 @@
-# AI 会话家族 · components
-
-> AI 会话场景组件族（07 命名治理：**不合并**——每个组件独立深度使用，统一归 ai 分类）。
-> 组合方式：`useChat()` handle 是粘合剂——会话状态 + 流式事件。
-
-| 组件 | 职责 | 组合 |
-|------|------|------|
-| AiChat | 标准对话界面（气泡+工具卡+审批卡+自动滚动） | 接收 useChat handle——最常用 |
-| ChatInput | 独立聊天输入条（IME/多行/流式停止） | AiChat 内部抽取；业务自拼对话页时用 |
-| MessageBubble | 单条消息气泡（role/status/actions） | 自拼对话页 |
-| SessionList | 会话管理列表（分组/重命名/删除/搜索） | 侧栏 |
-| ReasoningBlock | CoT 推理折叠展示 | AiChat renderMessage 内 |
-| ToolCallCard | 工具调用三态卡片 | AiChat 内嵌 |
-| CitationCard | RAG 引用来源展示 | AiChat renderMessage 内 |
-| ApprovalCard | HITL 人工审批（允许/拒绝/修改参数） | AiChat 内嵌；agent 审批流 |
-| PromptTemplate | 提示词模板编辑器（变量插入+预览） | 构建 agent 配置页 |
-
-## 组合示例
-
-```tsx
-// 最小对话页 = ChatInput + MessageBubble + SessionList（业务布局自控）
-// 标准对话 = AiChat（开箱即用）
-// Agent 配置 = PromptTemplate（系统提示词）+ JsonSchemaForm（工具参数）
-```

package/content/guides/choose.md

@@ -1,67 +0,0 @@
-# 选型决策树
-
-> 核心原则：**先查框架再动手**——weifuwu 已提供的能力绝不重复造轮子。
-> 检查顺序：components → layout 原语 → patterns → apps → capabilities。
-
-## 决策树
-
-```
-要做一个界面元素？
-├─ 已有组件（Button/Input/Table/Modal/Tabs/Tree…135 个）
-│   └─ → content/components/<id>.md 查 API + 纪律，直接使用
-├─ 是布局结构（容器/间距/对齐/导航壳/响应式显隐）
-│   └─ → content/layout/*.md 用 wf-* 原语（零手写 CSS）
-│       ├─ 页面骨架 → wf-app-shell / wf-stack / wf-container
-│       ├─ 间距/排版 → wf-gap-* / wf-text-* / wf-p-* 工具
-│       └─ 响应式 → wf-hidden@lg / wf-flex@lg 断点变体
-└─ 是完整页面/应用
-    ├─ 单页结构（后台壳/仪表盘/落地页/移动端）→ content/patterns/*.md 复制
-    ├─ 多页应用（路由 + 状态 + 后端）→ content/apps/*.md 复制模板改
-    │   ├─ 任务管理 → todo
-    │   ├─ 登录/权限 → auth
-    │   ├─ 管理后台 → admin
-    │   └─ 应用编排 → multi
-    └─ 生产级参考 → apps/agent-platform/（真实产品架构）
-```
-
-## 取码（选定后怎么拿源码）
-
-| 选型结果 | 取码路径 |
-|---------|---------|
-| 组件片段 | 组件文档「用法示例」节复制（或 `examples/` 无独立文件——直接按 API 写） |
-| 页面模式 | `examples/patterns/<file>.tsx` 复制文件 |
-| 应用模板 | `examples/apps/<id>/` 整个目录复制（app.tsx + api.ts + server.ts + main.tsx） |
-
-`examples/` 随 npm 包发布——`node_modules/weifuwu/examples/` 可离线取码。
-
-## 组件 vs 原语（最常见混淆）
-
-| 场景 | 用组件 | 用原语 |
-|------|--------|--------|
-| 布局容器/间距/显隐 | ❌ | ✅ wf-stack/wf-grid/wf-gap-* |
-| 导航结构（侧栏/菜单项） | ❌ | ✅ wf-nav/wf-nav-item（或 Menu 组件） |
-| 可交互元素（按钮/输入/选择） | ✅ 组件 | ❌ |
-| 弹层（下拉/弹窗/tooltip） | ✅ 组件（openPopup 命令式） | ❌ |
-| 纯视觉容器（卡片面/分隔） | 两者皆可 | ✅ wf-surface/wf-border |
-
-## 近义组件选型（名字相近/功能重叠——一句话决策）
-
-```
-列表类：List（<500 条）→ VirtualList / VirtualTable（>500 条）
-选择类：固定选项 → Select；自由输入联想 → AutoComplete；纯搜索 → SearchInput
-编辑类：轻量 md → Editor；代码 → CodeEditor；分屏预览 → MarkdownEditor
-树形类：展示/勾选 → Tree；下拉选择 → TreeSelect；路径级联 → Cascader
-折叠类：多开 → Collapse；单开（互斥）→ Accordion
-通知类：轻反馈 → Toast；持久通知 → Notification
-主题类：pressed 语义 → ToggleGroup；选中态样式 → SegmentedControl
-图片类：展示 → Img；裁剪 → ImageCropper；头像 → Avatar
-Office 文档：预览/编辑 → FilePreview；xlsx → FilePreview.Sheet；pptx → FilePreview.Slide
-```
-
-## 关键纪律（选型时就要知道）
-
-1. **浮层必须组件 + openPopup**：dropdown/select/datepicker/menubar/cascader/mentions/contextmenu/tooltip/popover/hovercard/modal/drawer/toast/notification/confirm/tour/command——这些已有组件，直接复用；新弹层组件必须 `ctx.ui.openPopup`（anchor 必传）
-2. **受控组件配回调**：传 active/value/checkedKeys 等受控 props 必须同时传 onChange——缺回调 = 静默不可点
-3. **列表 key 纪律**：有内部状态的组件列表 + 动态增删重排 → 显式 key；纯元素列表 → 无 key（位置身份）
-4. **浏览器能力走 ctx.browser**：禁裸 window/document/localStorage/matchMedia
-

package/content/guides/component-model.md

@@ -1,32 +0,0 @@
-# 两阶段组件模型
-
-```tsx
-const MyComp: Component = async (initProps, ctx) => {   // ── mount（只一次）
-  let count = initProps.initial ?? 0                    // 状态初始化/订阅/定时器
-  return async (props) => {                             // ── render（每次渲染）
-    return h('button', { onClick: () => { count++; ctx.ui.render() } }, count)
-  }
-}
-```
-
-## 职责表
-
-| 阶段 | 职责 | 可访问 | 事件函数 |
-|------|------|--------|---------|
-| mount | 初始化状态/订阅/定时器/稳定引用回调 | initProps、ctx、mount let、稳定 handle | 只依赖稳定引用 → mount 定义（零重绑） |
-| render | 读最新 props/派生数据/输出视图 | 最新 props、mount 闭包、ctx | 依赖最新 props → render 内定义（重绑是正确性要求） |
-| ref | DOM 持有/第三方初始化/清理 | el 或 null | **必须 mount 作用域定义**（内联 ref 每渲染新函数 → ref(null) 反复触发） |
-
-## 铁律
-
-1. **renderFn 强制异步**（`async (props) => Promise<VNode>`）——两阶段都可 await
-2. **渲染只发生在 render() 调用处**——状态是普通对象（let/createStore），无 $ Proxy
-3. **工厂按实例执行**——数据必须走 ctx.data（自带缓存+并发合并）
-4. mount 捕获的 initProps 不得用于渲染（必须用渲染期 props）
-5. 初始状态必须确定性（禁 window.innerWidth 之类直接初始化 → SSR mismatch）
-
-## 相关
-
-- 状态存放：`let` + render()（内部）/ createStore + useExternal（共享）
-- 完整纪律：AGENTS.md §3/§4
-

package/content/guides/component-standards.md

@@ -1,123 +0,0 @@
-# 组件编写标准（强制）
-
-> 本文是 weifuwu 组件的**强制标准**——不是建议。每条标准标注强制执行机制：
-> **L1 类型强制**（编译期失败）/ **L2 运行时检测**（dev error/warn——写错即报）/
-> **L3 契约测试**（引擎行为——vdom-x.test.ts 验收）/ **文档红线**（引擎无法检测——靠审查）。
-> 配套：[自定义组件指南](custom-component.md)（流程）· [质量标准](quality.md)（质量）
-
----
-
-## S1 组件形态
-
-| # | 标准 | 强制 | 违反时 |
-|---|------|------|--------|
-| S1.1 | 两阶段签名 `Component<P, C>`——外层 mount 一次，内层 renderFn 每次渲染 | **L1** | 编译失败（类型） |
-| S1.2 | **render-only**：改状态后显式 `ctx.render()`——无自动渲染 | 文档红线 | 交互不更新（审查/测试抓） |
-| S1.3 | renderFn 的 await 只允许 `ctx.data`（管道保证 resolve） | 文档红线 | 挂起（永不 resolve） |
-| S1.4 | 工厂（mount）内禁止副作用/昂贵操作——数据走 `ctx.data` | 文档红线 | 重复执行（N 实例 = N 次） |
-
-## S2 children 结构（值域协议）
-
-**children 只接受四类值**：vnode / 数组（隐式 Fragment——任意嵌套递归展开）/
-string·number（文本）/ 空洞（`false`·`null`·`undefined`·`true`——占位不渲染）。
-
-| # | 标准 | 强制 | 违反时 |
-|---|------|------|--------|
-| S2.1 | children 值域协议（对象/函数/Symbol = 非法输入） | **L2** | `console.warn` + 诊断占位 |
-| S2.2 | 数组 = 隐式 Fragment（嵌套递归展开——路径稳定） | **L3** | 契约测试 X-B5 |
-| S2.3 | 条件渲染：三元优先（`cond ? <X/> : null`）；`cond && <X/>` 的 cond 保证 boolean | 文档红线 | `0 && <X/>` 渲染 "0" |
-| S2.4 | **禁 `x || <Fallback/>`**（0/''/NaN 脏值泄漏）——用 `x != null ? ... : null` | 文档红线 | 渲染 "0"/空文本 |
-| S2.5 | **children 数组禁 `filter(Boolean)`**——占位法已处理空洞（长度恒定保位置） | **L2** | A 级检测 dev error |
-| S2.6 | 条件渲染的 false 是占位（同构——不塌缩兄弟） | **L3** | 契约测试 X-B4 |
-
-## S3 列表
-
-| # | 标准 | 强制 | 违反时 |
-|---|------|------|--------|
-| S3.1 | **有状态组件实例列表必须显式 key**（业务身份——增删/重排状态跟随） | **L2** | A 级检测 dev error（长度变化 + 无 key 组件项——portal 槽豁免） |
-| S3.2 | 无内部状态元素列表无 key（位置身份——patch 正确） | 文档红线 | 状态错位（误加 key 噪音） |
-| S3.3 | keyed 项路径 `.k{key}` 稳定（单 keyed 项不翻转） | **L3** | 契约测试 X-B3 |
-
-## S4 状态与受控
-
-| # | 标准 | 强制 | 违反时 |
-|---|------|------|--------|
-| S4.1 | **受控 props 必须配回调**（active/value/checkedKeys 等——父独占状态，回调是唯一出口） | **L2** | `console.warn`（按 name 幂等） |
-| S4.2 | 受控输入用 `ctx.ui.useControlledInput`（输入态不依赖受控 value 回流——防焦点丢失） | 文档红线 | 输入失焦 |
-| S4.3 | 共享状态 `createStore` + `ctx.ui.useExternal` | 文档红线 | — |
-| S4.4 | 内部状态闭包 `let` + 显式 render（不触发渲染的缓存用 let 不 render） | 文档红线 | — |
-| S4.5 | **props 里的对象变更必须换引用**（不可变更新——`[...items, x]` 而非 `items.push(x)`）——剪枝是引用比较——同引用内容变化永远不触发重渲染（deepFreeze 豁免对象——含函数属性——不被冻结） | 文档红线 | 内容变了 UI 不更新 |
-
-## S5 浮层
-
-| # | 标准 | 强制 | 违反时 |
-|---|------|------|--------|
-| S5.1 | **浮层唯一入口 `ctx.ui.openPopup`**（命令式——toast 心智）——portal 机制已删除 | **L3** + 文档红线 | 契约 + 场景 |
-| S5.2 | 浮层根 `position: fixed` + JS 坐标 + `#__wf_portal`（禁 absolute 相对父容器） | 文档红线 | overflow/transform 裁剪 |
-| S5.3 | 新弹层组件先查 openPopup 能力（定位/Escape/外部点击/presence/mask——anchor 必传） | 文档红线 | 重复造轮子 |
-
-## S6 生命周期
-
-| # | 标准 | 强制 | 违反时 |
-|---|------|------|--------|
-| S6.1 | **ref 定义在 mount 作用域**（内联 ref 每渲染新函数 → 旧 ref(null) 反复触发清理） | 文档红线 | 清理逻辑反复执行 |
-| S6.2 | 卸载清理：`onUnmount`（退订/清定时器/removeEventListener） | **L3** | 契约 X-G1 |
-| S6.3 | 浏览器能力走 `ctx.browser`（禁裸 `window.`/`document.`/`localStorage` 等） | 审计基线 | grep 审计（CI 噪音） |
-
-## S7 环境
-
-| # | 标准 | 强制 | 违反时 |
-|---|------|------|--------|
-| S7.1 | 工厂层取数走 `ctx.data`（三场景：SSR 收集/hydration 种子/SPA fetch + 并发合并） | **L3** | 契约 X-A5/X-G3 |
-| S7.2 | 个性化/会话数据不进 ctx.data（SSR 序列化泄漏）——留客户端 let + fetch | 文档红线 | 数据泄露 |
-
----
-
-## S8 路由与 SSR（引擎标准——每个 vdom 必须实现——vdom-x 验收）
-
-| # | 标准 | 强制 | 违反时 |
-|---|------|------|--------|
-| S8.1 | **UIRouter**：`get(path, handler)` / `notFound`——Trie 匹配（静态段优先参数段优先通配段——`:id` 参数 + `*` 通配）——类比后端 Router | **L3** | 契约 X-R1 |
-| S8.2 | **uiServe**（客户端）：SSR 首帧收养（hydrate——路径 id 精确吸收零重建）+ 导航（navigate/链接拦截/popstate） | **L3** | 契约 X-R2/X-R3 |
-| S8.3 | **uiSsr**（服务端）：match → 页面 → SSR HTML + 数据种子——同一 UIRouter 实例两端共享（匹配/参数同源） | **L3** | 契约 X-R3 |
-| S8.4 | 导航渲染：根级异类型 = 整树原子替换；同类型（params 变化）= 实例复用 | **L3** | 契约 X-R2 |
-| S8.5 | 页面组件 ctx.route（path/params——共享可变对象——导航更新内容引用恒定） | 文档红线 | 复用组件读旧 params |
-
-> **引擎兼容契约**：UIRouter/uiServe/uiSsr 是每个 vdom 的**必选项**（公共面
-> `weifuwu/ui-dom` 导出——vdom5 替换实现即切换——X-R1~R3 验收）。
-> **vdom3 退役条件**：vdom4 通过全部 vdom-x 契约（含 X-R）→ vdom3 删除
-> （组件库测试引擎切换 + 公共面去 v3 导出——见 design/vdom4-risk.md）。
-
-## S9 公共面稳定契约（weifuwu/ui-dom index.ts——对外接口）
-
-| # | 标准 | 强制 | 违反时 |
-|---|------|------|--------|
-| S9.1 | **`weifuwu/ui-dom` 公共面 = 对外契约**——内部引擎实现（vdom4/vdom5）切换**不影响功能**——应用/组件只依赖公共面 | **L3** | 契约 X-S1/X-S2 |
-| S9.2 | 契约 API 清单（vdom 无关面）：`h/jsx/jsxs/jsxDEV` + `createStore` + `createClientBrowser` + 中间件（`api/auth/ws/i18n`）——**结构符号内化：`Fragment` 不在公共面**（数组 = 隐式 Fragment；浮层 = openPopup 命令式；`<></>` 经 jsx-runtime 子路径自动导入） | **L3** | X-S1 |
-| S9.3 | 引擎契约面：`createRoot`（handle: ready/engine/unmount）+ `UIRouter/uiServe/uiSsr`（S8） | **L3** | X-S2/X-R |
-| S9.4 | **禁止公共面泄漏引擎专属实现**（v3 专属导出过渡期标注——vdom3 退役时移除——不得成为契约） | 文档红线 | 切换时功能变化 |
-
-> **公共面 = 兼容性承诺**：vdom-x 全部测试（X-A~R + X-S）经公共面取引擎入口——
-> vdom5 只改 index.ts 的 v4 面实现——测试零改动——全绿 = 公共面功能不变。
-
-## 强制执行机制总览
-
-| 机制 | 覆盖 | 位置 |
-|------|------|------|
-| **L1 类型** | S1.1 | `Component`/`RenderFn` 类型（contracts/vnode.ts） |
-| **L2 运行时检测** | S2.1/S2.5/S3.1/S4.1 | vdom4 diff.ts（A 级检测/非法输入/受控 warn——幂等） |
-| **L3 契约测试** | S2.2/S2.6/S3.3/S5.1/S6.2/S7.1 | `src/test/vdom-x.test.ts`（41 测试——vdom5 验收） |
-| **审计测试** | L2 检测自身工作 | `src/test/component-standards.test.ts` |
-| **审计基线** | S6.3 | `grep -rnE '\bwindow\.|document\.' src/components/`（0 允许） |
-
-## 开发流程（强制）
-
-1. 写组件 → 类型检查（L1 编译期）
-2. dev 运行 → L2 检测报错即修（受控缺回调/key 缺失/非法 children/filter）
-3. 提测 → 契约测试（L3——引擎行为）
-4. 发布 → 全量（1538+）
-
-## 与引擎的契约（vdom5 必须满足）
-
-vdom-x.test.ts 的 41 测试 = 上述 L3 条目的可执行化。新引擎一行替换入口——
-全绿 = 组件库零改动迁移 + 标准自动满足。