weifuwu 0.85.0 → 0.87.0

package/{docs → content/guides}/frontend.md

@@ -1,3 +1,8 @@
+# 前端总览与 API 速查
+
+> 从 docs/frontend.md 迁移（content/ 文档库——随 npm 包发布，与框架版本同步）。
+> 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
+
 # 前端 API 核心（weifuwu/ui-dom）
 
 > ⚠️ **引擎演进（2026-08）**：下一代引擎 **vdom3**（vnode + stream——渲染执行 = 事件流，
@@ -5,12 +10,10 @@
 > createRoot + 事件流）。vdom2（本文档）为当前生产引擎（冻结中——bug 修复在 vdom3）。
 > 迁移路线图见仓库 `design/vdom3-migration-plan.md`。
 
-> ⚠️ **`weifuwu/client` 已并入 `weifuwu/ui-dom`**（`src/client/` 已删除）——本页 import 均用 `weifuwu/ui-dom`。前端运行时唯一入口是 **`weifuwu/ui-dom`**（vdom3 精准事件流引擎：createRouter + createRoot——渲染全链路 `entity:action` 事件流），权威参考见 **[docs/frontend-ui-dom.md](frontend-ui-dom.md)**。
+> ⚠️ **`weifuwu/client` 已并入 `weifuwu/ui-dom`**（`src/client/` 已删除）——本页 import 均用 `weifuwu/ui-dom`。前端运行时唯一入口是 **`weifuwu/ui-dom`**（vdom3 精准事件流引擎：createRouter + createRoot——渲染全链路 `entity:action` 事件流），权威参考见 **[ui-dom 指南](ui-dom-guide.md)**。
 
 > 以下为完整 API 参考，按需查阅。新手建议先阅读 README 的「核心概念」和「快速开始」。
 
-> 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
-
 零外部 npm 运行时依赖。组件签名：`async (initProps, ctx) => (props) => Promise<VNode>`（两阶段模型，外层 mount 只一次可 await 数据，内层 renderFn 每次变化时执行——强制异步）。同步组件已不支持；无状态组件可简写为 `async (_init) => (props) => VNode`。
 
 构建配置（esbuild）：
@@ -35,6 +38,7 @@ let ctx: any = {}
 ctx = await api({ baseURL: '' })(ctx)
 ctx = await auth({ ... })(ctx)
 ctx = v3Toast()(ctx)
+ctx = v3Notification()(ctx)
 
 // 路由（RouteDef[]）+ 落地（事件流渲染）
 const handle = createRouter(
@@ -101,6 +105,7 @@ const Home: Component<{}, ApiInjected & RouteInjected> = async (_init, ctx) => {
 let ctx: any = {}
 ctx = api()(ctx)                 // 注入 ctx.api
 ctx = v3Toast()(ctx)             // 注入 ctx.toast
+ctx = v3Notification()(ctx)     // 注入 ctx.notification
 createRouter(routes, root, { ctx })
 ```
 
@@ -133,20 +138,80 @@ h('div', { class: 'x' }, child1, child2)
 |------|------|
 | `h(type, props, ...children)` | hyperscript |
 | `jsx` / `jsxs` / `jsxDEV` | JSX 编译目标 |
-| `Fragment` | 片段 |
-| `Portal` / `createPortal(children, portalKey?)` | 渲染到 `document.body#__wf_portal` 独立容器（弹层/对话框，脱离父级 overflow 裁剪） |
+| `ctx.ui.openPopup(opts)` | 命令式弹窗唯一入口（toast 心智——调用点构建内容——内核自管理挂载/更新/卸载/销毁——返回 `{ close, update, open }`） |
+
+> **Fragment 内化（2026-12）**：不需要 import Fragment——**数组 = 隐式 Fragment**
+> （任意嵌套递归展开——扁平化为同一 children 序列）；`<></>` 也可（JSX 编译器
+> 自动从运行时导入）。统一写法：多节点用数组，不需要任何结构符号。
+> Fragment 符号保留仅用于 keyed 文本/多根列表项（`h(Fragment, { key }, ...)`）。
+
+### 条件渲染统一标准（值域协议）
+
+**children 值域**（引擎契约——写组件只需要记这张表）：
+
+| 值 | 渲染 | 说明 |
+|----|------|------|
+| vnode / 数组（任意嵌套） | 元素 / 隐式 Fragment | 正常 |
+| string / number | 文本（含 `0`/`NaN`——显示为 "0"/"NaN"） | 合法——**但条件表达式避免产生** |
+| `false` / `null` / `undefined` / `true` | 空洞占位（不渲染——兄弟不错位） | 条件渲染的自然产物 |
+| 对象 / 函数 / Symbol | 诊断占位 + `console.warn` | 非法输入（开发期暴露） |
+
+**写法标准**（按优先级）：
 
 ```tsx
-import { createPortal } from 'weifuwu/ui-dom'
+// ① 首选：显式三元（双分支零歧义）
+cond ? <X/> : null
+cond ? <A/> : <B/>
 
-// 内容渲染到 body 下的独立容器（不在父组件的 DOM 树内）
-const Tooltip = (_init, ctx) =>
-  (props) => createPortal(
-    <div class="tooltip">{props.text}</div>
-  )
+// ② 条件渲染（cond 必须是 boolean/确定真值——禁止 0/''/NaN 语义）
+cond && <X/>
+cond && [<A/>, <B/>]          // 多节点条件（数组 = 隐式 Fragment）
+[<A/>, cond && <B/>]           // 嵌套在数组内——自然工作
+
+// ③ 多节点分支
+cond ? [<A/>, <B/>] : null
+```
+
+**红线**（会写出 bug 的写法）：
 
-// 配合 ctx.ui.selfId('name') 可从任何地方精准刷新 portal 内容
-ctx.ui.render(['name'])
+```tsx
+x || <Fallback/>               // ❌ x 为 0/''/NaN 时返回 x 本身——渲染 "0"/空文本
+                               //    用：x != null ? <Fallback/> : null
+0 && <X/>                      // ❌ 渲染 "0"（JS 真值陷阱——cond 应保证 boolean）
+{ a: 1 }                       // ❌ 对象直接作 children（warn + 占位）
+[cond && <A/>, <B/>].filter(Boolean)  // ❌ filter 消除空洞 → 数组长度变化 →
+                               //    无 key 有状态组件位置漂移（状态重置——
+                               //    A 级检测 dev error）。占位法已处理空洞：
+                               //    直接写 [cond && <A/>, <B/>]（false 占位——
+                               //    长度恒定——B 位置稳定）
+```
+
+**为什么不会错**：条件表达式产出的值域是受限的（vnode/数组/文本/空洞）——引擎对
+空洞做占位（同构——兄弟不错位——提交按钮事故免疫）；对非法输入 warn（不静默）。
+开发者只需遵守三条：三元优先、`&&` 的左侧保证 boolean、不写 `||` 条件渲染。
+
+> **命令式弹窗（2027-03 定稿）**：所有浮层一律 `ctx.ui.openPopup`（toast 心智——
+> 调用点构建内容——内核自管理生命周期）——定位/外部点击关闭/Escape/视口夹紧/
+> presence 退场/mask 全内置——组件输出纯业务（无槽无游离调用）。
+
+```tsx
+// 浮层正确姿势：openPopup（唯一入口——锚点定位 + 外部点击关闭 + Escape + 视口夹紧）
+const Tooltip = (_init, ctx) => {
+  let anchor: HTMLElement | null = null
+  let handle: import('weifuwu/client').PopupHandle | null = null
+  return (props) => {
+    // 句柄同步样板（受控 + 内容更新 + 关闭清理——每次渲染恒调用）
+    if (props.open && !handle)
+      handle = ctx.ui.openPopup({
+        anchor: () => anchor,             // 锚点必传（触发按钮也是锚点的一部分）
+        content: () => h('div', { class: 'tooltip' }, props.text),
+        onClose: () => { handle = null; props.onOpenChange?.(false) },
+      })
+    else if (!props.open && handle) { handle.close(); handle = null }
+    else if (handle) handle.update(h('div', { class: 'tooltip' }, props.text))
+    return h('span', { ref: (el) => { anchor = el } }, props.children)
+  }
+}
 ```
 
 ---
@@ -194,18 +259,18 @@ await browser.copyText(text)
 | `useAsync()` | `useAsync(fetcher)` | 异步取数：`data/loading/error` 响应式 + `reload()` |
 | `useControlled()` | `useControlled({ value, onChange, name })` | 受控/非受控统一：受控判定 + 缺回调 warn + 内部状态跨渲染保持 |
 | `useStableRef()` | `useStableRef(init, cleanup?)` | 稳定 ref 引用（根治内联 ref 陷阱） |
-| `usePopup()` 会话级模态 | `usePopup({ presence, trapFocus, lockScroll, positioning })` | **统一弹窗能力**：锚定浮层 + 会话级模态（Modal/Drawer 同款——退场状态机 + 滚动锁 + 焦点 trap + 居中定位）——一个入口按 options 组合 |
+| `openPopup(opts)` | `openPopup({ content, anchor?, placement?, mask?, presence?, trapFocus?, lockScroll?, closeOnOutside?, closeOnEscape?, position?, key? })` | **命令式弹窗唯一入口**（toast 心智）——返回 `{ close, update, open }`——锚定浮层 + 会话级模态（退场状态机 + 滚动锁 + 焦点 trap + 居中定位）——一个入口按 options 组合 |
 | `useGlobalKey()` | `useGlobalKey(handler)` | 全局键盘监听（window keydown：mount 注册 + 卸载清理） |
 | `useDrag()` | `useDrag({ onMove, onStart?, onEnd? })` | 指针拖拽（pointerdown 捕获 → window move delta / up 释放） |
 | `useDragDrop()` | `useDragDrop({ onDrop, onDragOver?, onDragLeave? })` | 原生 DnD（drop/dragover/dragleave + preventDefault，dropProps spread） |
 | `useReducedMotion()` | `useReducedMotion()` | 响应式系统偏好（JS 动画侧跳过；CSS 动画已有全局降级） |
 | `useAnimationEnd()` | `useAnimationEnd(cb, { once? })` | 元素动画完成回调（stableRef：挂载绑定/卸载清理/引用恒定） |
 | `useTween()` | `useTween(target, { duration?, ease? })` | 数值补间（rAF + easeOutCubic + reduced-motion 直落；幂等 reset） |
-| `usePresence()` | `usePresence({ name? })` | 通用显隐状态机（open→exit→closed，animationend 延迟卸载；usePopup presence 模式内部使用） |
+| `usePresence()` | `usePresence({ name? })` | 通用显隐状态机（open→exit→closed，animationend 延迟卸载；openPopup presence 模式内部使用） |
 | `useMedia()` | `useMedia(query, cb)` | 响应式媒体查询，断点变化时自动回调 |
 | `useBreakpoint()` | `useBreakpoint(cb \| bps, cb?)` | 命名断点 mobile/tablet/desktop |
 | `usePopupPosition()` | `usePopupPosition(opts)` | 弹层坐标跟随：scroll/resize 时自动重算 fixed 坐标 |
-| `usePopup()` | `usePopup(opts)` | **统一弹窗能力层**：触发（hover/tap 降级/longpress）+ Escape + 外部点击 + 定位/clamp + portal + 会话级模态（presence/trapFocus/lockScroll/positioning none——Modal/Drawer 同款） |
+| `openPopup()` | `openPopup(opts)` | **统一弹窗能力层**（命令式）：Escape + 外部点击 + 定位/clamp + mask + 会话级模态（presence/trapFocus/lockScroll/positioning none——Modal/Drawer 同款）——触发由组件自管（hover/click/longpress 事件绑定在调用侧） |
 | `useHoverCapable()` | `useHoverCapable()` | 设备是否支持 hover（`matchMedia '(hover: hover)'`），触屏降级判断 |
 | `useLongPress()` | `useLongPress({ onLongPress, duration })` | 长按手势（pointer 事件 + 位移取消 + 桌面右键兼容） |
 | `useVisualViewport()` | `useVisualViewport()` | 可视视口跟踪（键盘弹起/缩放），`{ height, offsetTop, keyboardOpen }` 响应式 |
@@ -224,7 +289,7 @@ await browser.copyText(text)
 | `ctx.ui.useMedia()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **响应式媒体查询** — 断点变化时自动重渲染 |
 | `ctx.ui.useBreakpoint()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **命名断点** — mobile/tablet/desktop 自动重渲染 |
 | `ctx.ui.usePopupPosition()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **弹层坐标跟随** — scroll/resize 时自动重算 fixed 坐标 |
-| `ctx.ui.usePopup()` | 注册监听 | 事件驱动 + document 监听 | 当前组件 | **弹层组合器** — 触发 + Escape + 外部点击 + 定位/clamp + portal（移动端友好由构造保证） |
+| `ctx.ui.openPopup(opts)` | 命令式（任意位置） | 内核自管理生命周期 | 调用点 | **命令式弹窗唯一入口**（toast 心智）— 定位/clamp + Escape + 外部点击 + mask + presence/trapFocus/lockScroll — 返回 `{ close, update, open }` |
 | `ctx.ui.useHoverCapable()` | mount 期判定 | 一次 matchMedia | 当前组件 | **hover 能力检测** — 触屏降级 tap 判断 |
 | `ctx.ui.useLongPress()` | 事件驱动 | pointer 事件 | 当前组件 | **长按手势** — ContextMenu 触屏触发、自定义长按操作 |
 | `ctx.ui.useVisualViewport()` | 注册监听 | visualViewport resize/scroll | 当前组件 | **键盘/缩放跟踪** — fixed 底部栏防键盘遮挡（AiChat `raiseOnKeyboard`） |
@@ -363,51 +428,55 @@ const CustomPopup = async (_init, ctx) => {
 
 已内置接入的组件：**Popover / Tooltip / Dropdown / DatePicker / Chart**（tooltip）——它们的弹出层在页面滚动、嵌套容器滚动、窗口缩放时都会自动跟随触发元素，无需额外配置。
 
-#### `ctx.ui.usePopup(options)` — 弹层组合器（推荐：移动端友好由构造保证）
+#### `ctx.ui.openPopup(options)` — 命令式弹窗（唯一入口——toast 心智）
 
-`usePopupPosition` 的**上层封装**：把弹层组件的完整生命周期（打开状态 + 触发 + Escape + 外部点击 + 定位/视口 clamp + portal）收敛成一个原语。弹层组件用它替代手写样板，**移动端行为自动正确**：
+**命令式内核**：调用点构建内容 → 内核自管理挂载/更新/卸载/销毁——**组件输出纯业务**
+（无槽无游离调用）。`usePopup`/`portal()`/`createPortal` 已删除（2027-03）。
 
-- **hover 触发在触屏自动降级为 tap**（内部 `matchMedia '(hover: hover)'` 判定）
-- **Escape 关闭是 document 级**——焦点在 portal 弹层内按 Escape 也能关
-- **外部点击关闭**（document mousedown，点弹层内部不关）
-- **宽度自动 clamp 视口**（≤ `100vw - 32px`，375px 屏不横向溢出）；`width` 支持 getter（DatePicker 跟随 trigger 宽）
-- **定位 + 视口夹紧**（复用 `usePopupPosition`，超高/超宽面板平移回视口）
-- **mask 遮罩**（`mask: true`——全屏遮罩 + 点击关闭；`maskCentered` 全屏居中——Modal 缩放预览/Command 面板；`mask: VNode` 自定义遮罩内容——Tour 挖洞高亮）
-- **trigger `'focus'`**（DatePicker）——focus 开 + blur 延迟关（`closeDelay` 窗口内面板交互生效）
-- 支持受控（`open`/`onOpenChange`）、动态 props（`placement`/`trigger`/`openDelay` 支持 getter）
+**能力**：
+- **定位 + 视口夹紧**（锚定浮层：anchor + placement/center/gap/margin——超高/超宽面板平移回视口；`position` 自定义坐标（光标处/跟随 trigger 宽））
+- **Escape 关闭是 document 级**（`closeOnEscape` 显式 false 禁用——危险操作组件自控）
+- **外部点击关闭**（document mousedown，点锚点/面板内不关——`closeOnOutside: false` 禁用）
+- **mask 遮罩**（`mask: true`——全屏遮罩 + 点击关闭（maskClosable）；`maskCentered` 全屏居中——Img 预览/Command 面板）
+- **会话级模态**：`presence`（退场状态机 open→exit→closed + animationend）+ `trapFocus`（焦点 trap）+ `lockScroll`（滚动锁 + 焦点归还）+ `positioning: 'none'`（自定义定位——.wf-modal inset:0 居中）
+- **handle**：`close()`（presence 播退场动画）/ `update(content)`（props 变化 diff 增量）/ `open`（getter）
 
 ```tsx
 const Tooltip = async (_init, ctx) => {
   let show = false
   let wrapEl: HTMLElement | null = null
   const wrapRef = (el) => { wrapEl = el }
+  let handle: PopupHandle | null = null
 
-  const popup = ctx.ui.usePopup({
-    trigger: 'hover',            // 触屏自动降级 tap
-    placement: () => latestPos,  // getter：动态读最新 props
-    el: () => wrapEl,
-    isOpen: () => show,
-    setOpen: (v) => { show = v; ctx.ui.render() },
-    width: 320,                  // 自动 clamp 视口
-    disabled: () => disabled,
-    openDelay: () => delay,      // hover 延迟（HoverCard 用）
-  })
-
-  return async (props) => h('div', { ref: wrapRef, ...popup.wrapProps }, [
-    props.children,
-    popup.portal(h('div', { class: 'wf-tooltip' }, props.content), 'tooltip'),
-  ].filter(Boolean))
+  return async (props) => {
+    // 句柄同步样板（受控 + 内容更新 + 关闭清理——每次渲染恒调用）
+    if (show && !handle)
+      handle = ctx.ui.openPopup({
+        anchor: () => wrapEl,          // **anchor 必传**（触发区也是锚点——否则被当外部点击关闭）
+        placement: () => latestPos,    // getter：动态读最新 props
+        content: () => h('div', { class: 'wf-tooltip' }, props.content),
+        onClose: () => { handle = null; show = false; ctx.ui.render() },
+      })
+    else if (!show && handle) { handle.close(); handle = null }
+    else if (handle) handle.update(h('div', { class: 'wf-tooltip' }, props.content))
+
+    return h('div', {
+      ref: wrapRef,
+      onMouseEnter: () => { show = true; ctx.ui.render() },
+      onMouseLeave: () => { show = false; ctx.ui.render() },
+    }, props.children)
+  }
 }
 ```
 
-- `popup.wrapProps` — 触发 + Escape + focus 处理，spread 到包装/触发元素
-- `popup.portal(content, portalKey)` — 定位 + clamp + portal（挂载 `#__wf_portal`），关闭时返回 null；自动附加 `wf-popup` 基类；`positioning: 'none'` 时不加坐标（只 `position: fixed`——组件自定义定位，Modal/Toast 用）
-- `popup.open` / `popup.setOpen()` — 状态读取与设置
-- `popup.sync(open)` / `popup.phase` — 会话级模态模式（`presence: true`）render 期同步打开状态 + 读退场 phase（`'closed' | 'open' | 'exit'`——exit 阶段保留退场动画）
+- **handle.close()** — 关闭（presence：先由组件 update exit class → 内核播退场动画 → animationend → dispose）
+- **handle.update(content)** — 内容更新（props 变化——diff 增量——不重建）
+- **handle.open** — 状态读取（渲染期最新）
+- **onClose 回调** — 外部点击/Escape/内核 dispose 后触发——组件同步句柄 + 状态（无需显式清空）
 
-**会话级模态模式**（Modal/Drawer/Confirm 同款）：`presence: true`（退场状态机）+ `trapFocus: true`（焦点 trap）+ `lockScroll: true`（滚动锁）+ `positioning: 'none'`（自定义定位）——全部能力 usePopup 内部实现（`trapFocus`/`lockScroll` 不对外导出）。
+**会话级模态模式**（Modal/Drawer/Confirm 同款）：`presence: true`（退场状态机）+ `trapFocus: true`（焦点 trap）+ `lockScroll: true`（滚动锁）+ `positioning: 'none'`（自定义定位）——全部能力 openPopup 内核实现（`trapFocus`/`lockScroll` 不对外导出）。
 
-**已迁移组件（全部弹窗统一 usePopup 单一入口）**：Tooltip / HoverCard / Popover / Dropdown / Menubar / Mentions / Cascader / ContextMenu / Select / AutoComplete / NavMenu / Popconfirm / DatePicker（focus 触发）/ Tour（mask 自定义遮罩）/ Toast / Notification（positioning 'none' 常驻容器）/ Modal / Drawer / Confirm / Command / Img（mask 全屏遮罩）/ TreeSelect。
+**已迁移组件（全部弹窗统一 openPopup 单一入口）**：Tooltip / HoverCard / Popover / Dropdown / Menubar / Mentions / Cascader / ContextMenu / Select / AutoComplete / NavMenu / Popconfirm / DatePicker（position 跟随 trigger 宽）/ Tour（mask + 自定位）/ Toast / Notification（positioning 'none' 常驻容器）/ Modal / Drawer / Confirm / Command / Img（mask 全屏遮罩）/ TreeSelect / Editor（link/image/ai/history）/ SheetGrid / SlideCanvas（AI 面板）/ Chart（tooltip）。
 
 **usePopupPosition 独立用户**：Affix / Chart（tooltip）——坐标工具（非弹窗组合器），滚动跟随自动。
 
@@ -458,7 +527,7 @@ ctx.ui.render(['stats'])
 
 #### `ctx.ui.useChat(options)` — AI 对话会话（AiChat 配套）
 
-会话语义的流式 AI 状态容器：消息累积 / 工具调用内嵌 / HITL 审批 / stop / retry，协议对页面完全透明（wf: 协议见 `docs/ai-contract.md`）。返回 handle 带 `subscribe(cb)`——子组件用 `ctx.ui.useExternal(chat)` 订阅会话变化（render-only 共享状态原语）：
+会话语义的流式 AI 状态容器：消息累积 / 工具调用内嵌 / HITL 审批 / stop / retry，协议对页面完全透明（wf: 协议见 [`ai-contract`](../../docs/ai-contract.md)）。返回 handle 带 `subscribe(cb)`——子组件用 `ctx.ui.useExternal(chat)` 订阅会话变化（render-only 共享状态原语）：
 
 ```tsx
 // mount 阶段（服务端 `ai()` 中间件 + `AiChat` 组件配套）
@@ -514,7 +583,7 @@ return () => list.loading ? h(Loading) : list.data?.map(u => h('div', {}, u.name
 | 原语 | 层 | 说明 |
 |------|----|------|
 | `useAnimationEnd(cb, { once? })` | 生命周期 | 元素动画完成回调（stableRef：挂载绑定/卸载清理/引用恒定）——**组件内动画事件唯一入口** |
-| `usePresence({ name? })` | 生命周期 | 显隐状态机：open → exit → closed（animationend 延迟卸载）；`usePopup` presence 模式内部使用 |
+| `usePresence({ name? })` | 生命周期 | 显隐状态机：open → exit → closed（animationend 延迟卸载）；openPopup presence 模式内部使用 |
 | `useTween(target, { duration?, ease? })` | 数值驱动 | 数值补间（rAF + easeOutCubic + reduced-motion 直落；幂等 reset + 每帧自动渲染） |
 | `useReducedMotion()` | 偏好感知 | 响应式系统偏好——**JS 动画**（rAF/tween）侧跳过（CSS 动画已有全局降级） |
 | `useInView` / `useScrollPosition` | 数值驱动 | 进入视口播 / 滚动位置联动（已有） |
@@ -538,7 +607,7 @@ return () => h('span', { class: 'wf-nums' }, String(n.value))
 if (!ctx.ui.useReducedMotion()) { /* 启动 rAF/动画 */ }
 ```
 
-> 完整动画纪律见 [custom-components.md](custom-components.md) 的「8.5 动画」章节。
+> 完整动画纪律见 [custom-component.md](custom-component.md) 的「8.5 动画」章节。
 
 #### CSS 层响应式（不碰 JS）
 
@@ -571,7 +640,7 @@ if (!ctx.ui.useReducedMotion()) { /* 启动 rAF/动画 */ }
 | `wf-safe-bottom` / `wf-safe-top` | iOS 安全区：`padding: env(safe-area-inset-bottom/top)`（刘海屏/Home 条） |
 | `@media (pointer: coarse)` 44px | 触屏命中区：button/input/select 全局覆盖；非 button 交互元素由 style-audit 规则强制登记 |
 
-> **移动端开发指南**：断点体系 / 44px 命中区纪律 / usePopup / 手势原语 / safe-area / 验收清单 → [`docs/mobile.md`](mobile.md)
+> **移动端开发指南**：断点体系 / 44px 命中区纪律 / openPopup / 手势原语 / safe-area / 验收清单 → [`移动端指南`](mobile-guide.md)
 
 ### `ctx.ui.render()` — 渲染唯一入口（render-only）
 
@@ -891,6 +960,7 @@ import type { RouterOptions } from 'weifuwu/ui-dom'
 | `ConfirmProps` | `{ open?, title?, message?, confirmText?, cancelText?, variant?, width?, onConfirm?, onCancel? }` |
 | `ConfirmOptions` | `{ title?, confirmText?, cancelText?, variant?, width? }` — 命令式 ctx.confirm 选项 |
 | `ToastOptions` | `{ position?, duration?, max? }` — 命令式 ctx.toast 配置 |
+| `NotificationOptions` | `{ position?, duration?, max? }` — 命令式 ctx.notification 配置 |
 | `PopupPositionOptions` | `{ el, isOpen, compute }` — 弹层位置跟踪配置（见 usePopupPosition） |
 | `PopupPosition` | `{ top, left, width?, refresh }` — 弹层位置跟踪器 |
 

package/content/guides/layout-choice.md

@@ -0,0 +1,64 @@
+# 布局选型指南（什么时候用哪个原语）
+
+> 解决"会用原语但不会选"——布局决策树：骨架/分区/间距/定位/响应式。
+> 与 [页面组装](page-building.md) 配合：本页决定"用什么"，组装决定"怎么搭"。
+
+## 1. 能力光谱（选型总原则）
+
+```
+从组合层往下找——Table 能解决不自己拼：
+  组合层    Table / Form / Descriptions / StatCard    （开箱即用——优先）
+  命名层    Grid / Space / Typography / Card          （有 API 有语义）
+  裸原语    wf-grid / wf-gap-* / wf-text-*            （自由但无约定——兜底）
+```
+
+## 2. 决策树
+
+```
+页面骨架？
+├─ 有侧栏+顶栏 → wf-app-shell（patterns/app-shell 蓝本）或 Layout 组件
+├─ 独立定宽页 → wf-container（--wf-max 控制宽度）
+└─ 全屏/无壳 → 直接 wf-stack / wf-fill
+
+内容分区？
+├─ 纵向堆叠 → wf-stack（页面默认）
+├─ 横向排列 → wf-row（按钮组/表单行）
+├─ 响应式网格 → wf-grid（--wf-cols: repeat(auto-fit, minmax(...))）
+├─ 两栏固定比例 → wf-split（--wf-split-ratio）
+└─ 居中专区 → wf-center（hero/空态/认证）
+
+间距？
+├─ 区域间 → wf-gap-lg / wf-gap-md（stack/row 的 --wf-gap）
+├─ 元素内 → wf-p-*（卡片内边距）
+└─ 标题留白 → wf-mb-*（仅 margin-bottom 用 m-，其余用 gap）
+
+定位/层级？
+├─ 吸顶 → wf-sticky（页面级）或 Affix 组件（滚动跟随）
+├─ 悬浮按钮 → FloatButton 组件
+├─ 角标覆盖 → wf-layer + wf-pop（容器内定位）
+└─ 弹层 → 组件（openPopup 命令式——禁手写定位）
+
+响应式？
+├─ 隐藏/显示 → wf-hidden / wf-hidden@lg / wf-flex@lg
+├─ 网格列数 → --wf-cols 的 auto-fit/auto-fill（窄屏自动收）
+└─ 表格 → Table minWidth + 横向滚动
+```
+
+## 3. 组件 vs 原语的边界（5 个重叠组件的分工）
+
+| 场景 | 用原语 | 用组件 |
+|------|--------|--------|
+| 简单响应式网格 | wf-grid | Grid（24 栅格/列偏移——antd 迁移心智） |
+| 简单间距 | wf-gap-* | Space（split 分隔符/方向控制） |
+| 纯分隔线 | wf-border-t | Divider（带文字/vertical） |
+| 简单字号 | wf-text-* | Typography（语义标签/mark/code） |
+| 普通滚动容器 | wf-scroll | Scrollbar（自定义滚动条外观） |
+
+## 4. 布局纪律（红线）
+
+```
+□ 布局结构只用 wf-* 原语（零手写 CSS）
+□ 先查框架再动手（layout 原语 + 组件 + patterns——三层都查过再自研）
+□ 间距走 token 阶梯（--wf-space-* 派生类——不用魔数）
+□ 新功能先查 wf-* 是否已覆盖（如吸顶：页面级 wf-sticky / 嵌套容器 Affix）
+```

package/{docs/layout.md → content/guides/layout-guide.md}

@@ -1,10 +1,13 @@
-# 布局系统（weifuwu/layout）
+# 布局原语使用指南
+
+> 从 docs/layout.md 迁移（content/ 文档库——随 npm 包发布，与框架版本同步）。
+> 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
 
-> 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
+# 布局系统（weifuwu/layout）
 
-纯 CSS 66 个布局原语 + 156 个工具类 + 177 个主题 Token。不绑定任何 JS 框架。
+纯 CSS 66 个布局原语 + 157 个工具类 + 182 个主题 Token。不绑定任何 JS 框架。
 
-> **学习路径与命名规范**：见 [`docs/style-guide.md`](style-guide.md)——统一语法 `wf-<域>-<名>`、三档学习（组件 → 10 核心原语 → 完整速查）、场景速查、变量定制。
+> **学习路径与命名规范**：见 [`样式体系指南`](../../docs/style-guide.md)——统一语法 `wf-<域>-<名>`、三档学习（组件 → 10 核心原语 → 完整速查）、场景速查、变量定制。
 
 > **全栈 weifuwu 项目**：`weifuwu/components/style.css` 已包含布局系统，一条 import 就够了，无需单独引用本页。
 > 本页仅适用于**非 weifuwu 项目**或**只需 CSS 布局**的场景。
@@ -90,8 +93,8 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 | **内容排版** | `wf-prose` | 富文本正文（文章/博客/文档，一个类包 h2/p/ul/blockquote/pre…） |
 | **外壳** | `wf-app-shell` | 应用外壳：侧边栏 + 主区 grid（`--wf-sidebar-width`） |
 | | `wf-sidebar` `wf-sidebar-header` `wf-sidebar-body` `wf-sidebar-footer` | 侧边栏：品牌区/导航区/底部用户区，sticky 全高 |
-| | `wf-nav` `wf-nav-group` `wf-nav-item` `wf-nav-icon` | 导航：分组标题 + 链接项（`--active` 激活态） |
-| | `wf-main` | 主内容区（padding + min-width: 0） |
+| | `wf-nav` `wf-nav-group` `wf-nav-item` `wf-nav-icon` | 导航：分组标题 + 链接项（`--active` 激活态）；折叠态 `wf-nav--collapsed`（图标-only——**导航项需加 `title` 属性**提供悬停提示，CSS 无法自动补） |
+| | `wf-main` | 主内容区（padding + min-width: 0；长文本设 `--wf-main-max: 900px` 限宽居中——文档站场景） |
 | | `wf-text-*` 排版工具 | 见下文「排版工具」 |
 
 ### 组合规则（冲突防线）
@@ -131,7 +134,7 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 | `wf-truncate` | 单行省略（ellipsis） |
 | `wf-line-clamp-2/3` | 多行截断 |
 
-## 177 个主题 Token
+## 182 个主题 Token
 
 **双层结构**：原始层（Primitive，色值只定义一次，品牌/暗色调校改这里）+ 语义层（Semantic，组件消费）。
 
@@ -169,7 +172,8 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 /* 边框色 */
 --wf-color-border / --wf-color-border-light / --wf-color-border-dark
 
-/* 字体 */
+/* 字体（--wf-font-sans 已含 CJK 回退：PingFang SC / Hiragino / 雅黑 / Noto Sans SC——
+   中文原生：西文最优字形 + 中文三平台一致；--wf-font-mono 同） */
 --wf-font-sans / --wf-font-mono
 
 /* 字号: xs sm base lg xl 2xl 3xl 4xl 5xl display */

package/{docs/frontend-middleware.md → content/guides/middleware.md}

@@ -1,8 +1,11 @@
-# 前端中间件与工具（weifuwu/ui-dom）
+# 中间件与 ctx 注入链
+
+> 从 docs/frontend-middleware.md 迁移（content/ 文档库——随 npm 包发布，与框架版本同步）。
+> 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
 
-> ⚠️ **`weifuwu/client` 已并入 `weifuwu/ui-dom`**——中间件（api/auth/ws/i18n）位于 `weifuwu/ui-dom`，前端运行时唯一入口为 `weifuwu/ui-dom`（vdom3 事件流引擎：createRouter + createRoot），见 [frontend-ui-dom.md](frontend-ui-dom.md)。
+# 前端中间件与工具（weifuwu/ui-dom）
 
-> 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
+> ⚠️ **`weifuwu/client` 已并入 `weifuwu/ui-dom`**——中间件（api/auth/ws/i18n）位于 `weifuwu/ui-dom`，前端运行时唯一入口为 `weifuwu/ui-dom`（vdom3 事件流引擎：createRouter + createRoot），见 [ui-dom 指南](ui-dom-guide.md)。
 
 ## createRouter — 前端路由（vdom3）
 
@@ -11,6 +14,7 @@ import { createRouter, h } from 'weifuwu/ui-dom'
 
 let ctx: any = {}
 ctx = v3Toast()(ctx)                  // 中间件面展开（ctx 注入——对齐后端 app.use）
+ctx = v3Notification()(ctx)          // 注入 ctx.notification
 
 const handle = createRouter(
   [
@@ -388,6 +392,33 @@ ctx.toast?.('普通消息')          // 默认 type = 'info'
 
 ---
 
+## notification — 命令式通知
+
+`ctx.notification()` 是 `<Notification>` 组件的全局命令式封装：队列式通知（title + description + icon + 操作），自动消失、手动关闭、四角定位。
+
+```tsx
+import { v3Notification } from 'weifuwu/ui-dom'
+
+let ctx: any = {}
+ctx = v3Notification({ position: 'top-right', duration: 4500, max: 5 })(ctx)
+
+// 任意代码中（组件事件、api 拦截器、WS 回调、定时器）
+ctx.notification?.success({ title: '部署成功', description: 'v0.63.0 已上线' })
+ctx.notification?.warning({ title: '磁盘空间不足', description: '已使用 92%' })
+ctx.notification?.('普通通知')
+ctx.notification?.open({ type: 'error', title: '请求失败', duration: 8000, action: { label: '重试', onClick: retry } })
+```
+
+| NotificationOptions | 类型 | 默认值 | 说明 |
+|-------------|------|--------|------|
+| `position` | `NotificationPosition` | `'top-right'` | 容器位置（top-right/top-left/bottom-right/bottom-left） |
+| `duration` | `number` | `4500` | 默认自动消失时间（ms），0 = 不消失 |
+| `max` | `number` | `5` | 最大显示条数，超出移除最早 |
+
+单条可覆盖自动消失时间：`ctx.notification({ title: 'x', duration: 8000 })`。
+
+---
+
 ## ScrollLock / FocusTrap
 
 ```tsx

package/{docs/mobile.md → content/guides/mobile-guide.md}

@@ -1,7 +1,12 @@
+# 移动端开发指南
+
+> 从 docs/mobile.md 迁移（content/ 文档库——随 npm 包发布，与框架版本同步）。
+> 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
+
 # 移动端开发指南（weifuwu）
 
 > 移动端友好由框架构造保证：**用对原语 + 守 audit 规则**，不靠每个组件"记得"。
-> 落地依据：移动端支持计划（P0-P3 全落地——usePopup 全系 + safe-area + 44px 命中区 + docs/mobile 指南）。
+> 落地依据：移动端支持计划（P0-P3 全落地——openPopup 全系 + safe-area + 44px 命中区 + docs/mobile 指南）。
 
 ## 一、断点体系（布局原语）
 
@@ -42,30 +47,21 @@
 
 - 小按钮（显式 `min-height` 覆盖了全局）需在组件 CSS 补 coarse 44px（参考 Pagination/Transfer/Calendar nav）
 
-## 三、弹层（usePopup 组合器）
-
-**弹层组件必须用 `ctx.ui.usePopup`**——移动端友好由构造保证：
-
-```ts
-const popup = ctx.ui.usePopup({
-  trigger: 'hover',              // 触屏自动降级 tap（内部 matchMedia '(hover: hover)'）
-  placement: () => latestPos,    // 支持 getter 动态读 props
-  el: () => wrapEl,              // 锚定元素 ref
-  isOpen: () => $.open,
-  setOpen: (v) => { $.open = v; ctx.ui.render() },
-  open: controlled ? () => latestOpen : undefined,  // 受控桥（mount 期决定模式）
-  onOpenChange: (v) => latestOnOpenChange?.(v),
-  width: 320,                    // 自动 clamp 视口（≤100vw-32px）
-  disabled: () => disabled,
-  openDelay: () => delay,        // hover 延迟（HoverCard）
-})
-// popup.wrapProps — 触发 + Escape + focus，spread 到包装元素
-// popup.portal(content, portalKey) — 定位 + clamp + portal（挂载 #__wf_portal）
-```
+## 三、弹层（openPopup 命令式弹窗）
 
-**内置行为**：hover 桌面 / tap 触屏 / Escape（document 级，portal 内也可关）/ 外部点击 / 视口 clamp / 宽度 clamp / focus 触发（DatePicker） / mask 遮罩（Command/Img/Tour）/ 会话级模态（Modal/Drawer/Confirm——presence 退场 + trapFocus + lockScroll + positioning 'none'）。
+**弹层组件必须用 `ctx.ui.openPopup`**——移动端友好由构造保证：
 
-**全部弹窗统一 usePopup 单一入口**（锚定浮层 + 居中模态 + 通知 + 引导 + 日历）；`usePopupPosition` 仅 Affix/Chart 坐标工具独立使用。
+```tsx
+let handle: PopupHandle | null = null
+if (open && !handle)
+  handle = ctx.ui.openPopup({
+    anchor: () => anchorEl,   // **anchor 必传**（触发区是锚点——否则被当外部点击关闭）
+    content: () => h('div', { class: 'wf-popover' }, props.content),
+    onClose: () => { handle = null; open = false; ctx.ui.render() },
+  })
+else if (!open && handle) { handle.close(); handle = null }
+else if (handle) handle.update(h('div', { class: 'wf-popover' }, props.content))
+```
 
 ## 四、手势原语
 
@@ -87,7 +83,7 @@ const popup = ctx.ui.usePopup({
 
 ## 六、防横向溢出（375px 验收基线）
 
-- 弹层宽度：usePopup 自动 `max-width: min(…, calc(100vw - 32px))`；手动浮层加 `.wf-popup` 基类
+- 弹层宽度：openPopup 自动视口夹紧（`calc(100vw - 32px)`）；手动浮层加 `.wf-popup` 基类
 - 宽内容（表格/双栏）：容器 `overflow-x: auto`（Table/Resizable 已内置）
 - 网格：`minmax(min(100%, 420px), 1fr)`（防 minmax 固定值撑破窄屏）
 - 验收：375×667 视口 `document.documentElement.scrollWidth <= innerWidth`

package/content/guides/page-building.md

@@ -0,0 +1,98 @@
+# 页面组装方法论（从零搭一个页面）
+
+> 解决"我会组件、会原语，但打开编辑器不知道第一行写什么"。
+> 与 [布局选型](layout-choice.md) 配合：选型决定"用什么"，本页决定"怎么搭"。
+> 前提：先查 patterns（`content/patterns/*.md`）——有现成蓝本直接复制，
+> 本方法论用于"没有蓝本时从零搭"。
+
+## 1. 页面解剖学（页面 = 五层）
+
+```
+骨架层     页面的大形状：wf-app-shell（壳）/ wf-container（定宽）/ wf-stack（纵列）
+分区层     区域划分：header / content / footer / sider（用 row/stack 组合）
+内容层     组件就位：Table/Form/Card…（组件文档查 API）
+间距层     呼吸感：wf-gap-* / wf-p-*（间距工具）
+响应式层   多设备：wf-hidden@lg / 断点变体（布局降级）
+```
+
+## 2. 组装 5 步套路（固定流程，不是自由发挥）
+
+```
+① 定骨架：这个页面是"壳内页面"（有侧栏/顶栏 → app-shell 已存在）还是
+   "独立页面"（→ wf-container + wf-stack）？
+② 划分区：从上到下/从左到右画出区域（header 标题区 / 主体区 / 底部操作区）
+③ 填内容：每个区域放什么组件（标题 → PageHeader；列表 → Table；表单 → Form）
+④ 调间距：区域间 wf-gap-lg、卡片内 wf-gap-sm、标题下 wf-mb-*
+⑤ 响应式：窄屏时哪些隐藏（wf-hidden@lg）、哪些堆叠（grid 列数自适应）
+```
+
+## 3. 完整示例：从零搭"订单详情页"（逐步）
+
+### 第 1 步：定骨架（独立页面——container + stack）
+
+```tsx
+return (
+  <div class="wf-container wf-stack" style="--wf-max:960px;--wf-gap:16px;padding:24px 16px">
+    {/* 分区占位 */}
+  </div>
+)
+```
+
+### 第 2 步：划分区 + 第 3 步：填内容
+
+```tsx
+// ① 标题区：PageHeader（标题 + 状态 Tag + 操作按钮）
+<PageHeader title={`订单 ${id}`} sub="客户：张伟">
+  <Button variant="primary">导出</Button>
+</PageHeader>
+
+// ② 主体区：Descriptions（详情字段栅格）
+<Descriptions items={[{ label: '订单号', value: id }, { label: '金额', value: '¥3,200' }]} bordered />
+
+// ③ 历史区：Timeline（执行流）
+<Timeline items={[{ key: '1', title: '已支付', time: '08-12 09:15' }]} />
+```
+
+### 第 4 步：调间距（gap 阶梯）
+
+```tsx
+// 区域间 gap-lg（16px）已有（骨架 --wf-gap:16px）
+// 卡片内紧凑 gap-sm、标题下留白 wf-mb-sm
+<Card>
+  <div class="wf-text-bold wf-mb-sm">补充信息</div>
+  <div class="wf-stack wf-gap-xs">…</div>
+</Card>
+```
+
+### 第 5 步：响应式降级
+
+```tsx
+// 双栏 → 窄屏单栏（grid auto-fit）
+<div class="wf-grid" style="--wf-cols:repeat(auto-fit,minmax(min(100%,300px),1fr))">
+  <Card>补充信息</Card><Card>执行历史</Card>
+</div>
+```
+
+**完整成品**：`examples/patterns/DetailPage.tsx`（本示例的落地版——5 步的每一步都可在源码中对应）。
+
+## 4. 常见页面的搭法速查
+
+| 页面类型 | 骨架 | 分区 | 核心组件 |
+|---------|------|------|---------|
+| 列表页 | container+stack | 标题区/表格区/分页区 | PageHeader + SearchInput + Table + Pagination |
+| 详情页 | container+stack | 标题区/详情区/历史区 | PageHeader + Descriptions + Timeline |
+| 设置页 | container+stack | 标题区/分区 Tabs | PageHeader + Tabs + Form + Switch |
+| 表单页 | container+stack | 标题区/表单区/操作区 | PageHeader + Form + Field + Button |
+| 仪表盘 | container+stack | KPI 行/图表区/表格区 | StatCard + Chart + Table |
+
+（每种都有对应 patterns 蓝本——`content/patterns/*.md`）
+
+## 5. 纪律（搭页面时的红线）
+
+```
+□ 布局结构只用 wf-* 原语（不手写 CSS/内联 style 自定义）
+□ 内容元素用组件（不裸 div/span 手搓结构）
+□ 间距走 wf-gap-*/wf-p-*（不用魔数 px）
+□ 图标用 Icon 组件（禁 emoji 装饰）
+□ 先查 patterns——重复造轮子是最常见的浪费
+```