weifuwu 0.63.0 → 0.64.0

package/docs/layout.md

@@ -0,0 +1,203 @@
+# 布局系统（weifuwu/layout）
+
+> 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
+
+纯 CSS 布局原语 + 工具类 + 141 个主题 Token。不绑定任何 JS 框架。
+
+> **学习路径与命名规范**：见 [`design/style-guide.md`](../design/style-guide.md)——统一语法 `wf-<域>-<名>`、三档学习（组件 → 10 核心原语 → 完整速查）、场景速查、变量定制。
+
+> **全栈 weifuwu 项目**：`weifuwu/components/style.css` 已包含布局系统，一条 import 就够了，无需单独引用本页。
+> 本页仅适用于**非 weifuwu 项目**或**只需 CSS 布局**的场景。
+
+```html
+<link rel="stylesheet" href="/node_modules/weifuwu/layout">
+```
+
+或在 weifuwu 服务端通过 `ctx.ui.css` 直接引用包名（`ctx.ui.css` 自动解析 exports map）：
+
+```ts
+// 方案 A：组件 + 布局全部搞定（推荐）
+app.get('/style.css', (req, ctx) => ctx.ui.css('weifuwu/components/style.css'))
+
+// 方案 B：只用布局
+app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
+```
+
+也支持相对路径：`ctx.ui.css('./src/style.css')`。
+
+## 70 个布局原语
+
+| 类别 | 原语 | 效果 |
+|------|------|------|
+| **排列** | `wf-stack` `wf-stack@sm/md/lg` | 纵向 flex + gap（断点变体→横向） |
+| | `wf-stack-reverse` `@sm/md/lg` | 纵向反向 |
+| | `wf-row` `wf-row@sm/md/lg` | 横向 flex + wrap + gap |
+| | `wf-row-reverse` `@sm/md/lg` | 横向反向 |
+| | `wf-nowrap` | flex-wrap: nowrap |
+| | `wf-cluster` | 换行居中簇 |
+| **分布** | `wf-split` | justify-content: space-between |
+| | `wf-center` | 双轴居中 |
+| | `wf-right` | justify-content: flex-end |
+| | `wf-around` | space-around |
+| | `wf-evenly` | space-evenly |
+| **对齐** | `wf-top` | align-items: flex-start |
+| | `wf-bottom` | align-items: flex-end |
+| | `wf-stretch` | align-items: stretch |
+| **弹性** | `wf-fill` | flex: 1 + min-width: 0 |
+| | `wf-fixed` | flex: none |
+| | `wf-auto` | flex: auto |
+| | `wf-shrink` | min-width/height: 0 |
+| **Z轴** | `wf-cover` | position: fixed + inset: 0 |
+| | `wf-pop` | position: absolute |
+| | `wf-anchor` | position: relative |
+| | `wf-layer` | position: relative + z-index |
+| | `wf-sticky` | position: sticky |
+| | `wf-popup` | 浮层基类：宽度视口 clamp（`min(var(--wf-popup-max, 480px), calc(100vw - 32px))`） |
+| **安全区** | `wf-safe-bottom` / `wf-safe-top` | iOS 刘海屏/Home 条：`padding: env(safe-area-inset-*)` |
+| **容器** | `wf-surface` | 基础面（border-radius + shadow + bg） |
+| | `wf-grid` | display: grid + --wf-cols |
+| | `wf-container` | max-width + margin: auto |
+| | `wf-scroll` | overflow: auto |
+| | `wf-clip` | overflow: hidden |
+| **显隐** | `wf-hidden` `wf-hidden@sm/md/lg` | display: none |
+| | `wf-block` `wf-block@sm/md/lg` | display: block |
+| | `wf-inline` | display: inline |
+| | `wf-inline-block` | display: inline-block |
+| | `wf-contents` | display: contents |
+| **间距** | `wf-p-*` / `wf-px-*` / `wf-py-*`（xs~2xl） | padding：全/水平/垂直，引用 `--wf-space-*` |
+| | `wf-mt-*` / `wf-mb-*` / `wf-my-*`（xs~2xl） | margin：top/bottom/垂直 |
+| | `wf-mx-auto` / `wf-my-auto` | margin: auto 居中 |
+| | `wf-gap-*`（xs~2xl） | 为 flex/grid 原语设置 `--wf-gap` |
+| **尺寸** | `wf-w-full` / `wf-h-full` / `wf-w-auto` | 宽/高 100%、auto |
+| **边框** | `wf-border` / `wf-border-t/b/l/r` | 1px 边框（`--wf-border-width` + `--wf-color-border`） |
+| **面工具** | `wf-bg-secondary/tertiary/brand/success/warning/error/info` | 语义背景色（`--wf-color-*-bg`） |
+| | `wf-pill` | 胶囊圆角（999px，状态徽章/标签/色块） |
+| | `wf-rounded-sm` `wf-rounded` `wf-rounded-md` `wf-rounded-lg` | 圆角工具（`--wf-radius-*`） |
+| **气泡** | `wf-bubble` / `wf-bubble--own` / `wf-bubble--ai` | 聊天气泡（pre-wrap + 折行内建） |
+| **打印** | `wf-print-hidden` / `wf-print-block` | 导出 PDF 时隐藏工具区 / 恢复块级 |
+| **行高** | `wf-leading-tight` `wf-leading-base` `wf-leading-relaxed` | line-height（`--wf-line-height-*`） |
+| **指针** | `wf-pointer` / `wf-not-allowed` | cursor: pointer / not-allowed |
+| **内容排版** | `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-text-*` 排版工具 | 见下文「排版工具」 |
+
+### 排版工具（`wf-text-*`）
+
+| 工具 | 效果 |
+|------|------|
+| `wf-text-left/center/right` | text-align |
+| `wf-text-xs…5xl` | 字号（`--wf-font-size-*`） |
+| `wf-text-secondary/tertiary/disabled/brand` | 中性色阶 |
+| `wf-text-success/warning/error/info` | 语义色文本（`--wf-color-*`） |
+| `wf-text-medium/semibold/bold` | 字重 |
+| `wf-tracking-normal/wide/wider` | letter-spacing |
+| `wf-uppercase/lowercase/capitalize` | text-transform |
+| `wf-pre-wrap` | white-space: pre-wrap + word-break（聊天气泡/代码） |
+| `wf-break-word` | overflow-wrap + word-break |
+| `wf-text-nowrap` | white-space: nowrap |
+| `wf-truncate` | 单行省略（ellipsis） |
+| `wf-line-clamp-2/3` | 多行截断 |
+
+## 141 个主题 Token
+
+**双层结构**：原始层（Primitive，色值只定义一次，品牌/暗色调校改这里）+ 语义层（Semantic，组件消费）。
+
+```css
+/* ── 原始层 — 品牌/中性色值 + 暗色值，主题定制改这一层 ── */
+--wf-brand-500 / --wf-brand-600 / --wf-brand-50   /* 品牌主色/悬停/浅底 */
+--wf-slate-900…50 / --wf-white                     /* 中性阶 */
+--wf-dark-*                                        /* 暗色值（暗色模式经间接层引用，零硬编码） */
+
+/* ── 语义层 — 组件消费，暗色/主题切换覆盖这里 ── */
+/* 品牌色 */
+--wf-color-primary / --wf-color-primary-hover / --wf-color-primary-bg
+
+/* 语义色 */
+--wf-color-success / --wf-color-success-bg
+--wf-color-warning / --wf-color-warning-bg
+--wf-color-error / --wf-color-error-bg
+--wf-color-info / --wf-color-info-bg
+
+/* 语义文字色（P2）：浅底可读 700 级，文字用 -text、填充用 500 级 */
+--wf-color-primary-text / --wf-color-success-text / --wf-color-warning-text / --wf-color-error-text / --wf-color-info-text
+--wf-color-on-brand   /* 实心品牌/语义底上的文字与图标 */
+--wf-overlay          /* 浮层遮罩（Modal/Drawer），暗色自动加深 */
+
+/* 文字色 */
+--wf-color-text / --wf-color-text-secondary / --wf-color-text-tertiary / --wf-color-text-disabled
+
+/* 背景色 */
+--wf-color-bg / --wf-color-bg-secondary / --wf-color-bg-tertiary
+
+/* 边框色 */
+--wf-color-border / --wf-color-border-light / --wf-color-border-dark
+
+/* 字体 */
+--wf-font-sans / --wf-font-mono
+
+/* 字号: xs sm base lg xl 2xl 3xl 4xl 5xl display */
+--wf-font-size-*
+
+/* 字重: normal medium semibold bold */
+--wf-font-weight-*
+
+/* 行高: tight normal relaxed */
+--wf-line-height-*
+
+/* 字距: normal wide wider */
+--wf-letter-spacing-*
+
+/* 间距: xs sm md lg xl 2xl */
+--wf-space-*
+
+/* 间隔: xs sm md lg xl 2xl */
+--wf-gap-*
+
+/* 圆角: sm md lg xl */
+--wf-radius-*
+
+/* 阴影: sm md lg */
+--wf-shadow-*
+
+/* 动效（P0）：时长阶梯/缓动曲线/位移量，全站动效统一引用 */
+--wf-dur-fast / --wf-dur-base / --wf-dur-slow
+--wf-ease-out / --wf-ease-in / --wf-ease-snap
+--wf-motion-sm / --wf-motion-md / --wf-motion-lg
+
+/* 表头/分组标题（P5）：CJK 感知，默认 none/0，英文可覆盖 */
+--wf-heading-case / --wf-heading-tracking
+
+/* 数字（P5）：tabular-nums 防宽度抖动（wf-nums 工具类） */
+--wf-nums
+
+/* 其他 */
+--wf-border-width / --wf-focus-ring
+--wf-transition-duration / --wf-transition-timing
+--wf-accent-color / --wf-caret-color
+--wf-opacity-disabled / --wf-opacity-overlay
+--wf-pop-z / --wf-cover-z
+
+/* 应用外壳 */
+--wf-sidebar-width
+```
+
+### 暗色模式
+
+两种激活方式（显式 `data-theme` 优先级更高）：
+
+```ts
+// 1. 手动切换
+// document.documentElement.setAttribute('data-theme', 'dark')
+// document.documentElement.setAttribute('data-theme', 'light') // 强制亮色
+
+// 2. 自动：系统暗色偏好（无需任何代码）
+// 系统为暗色时自动生效；加 data-theme="light" 可强制亮色
+```
+
+暗色值定义在原始层 `--wf-dark-*`（只写一次），`_dark.css` 两段仅做语义映射——改暗色调校只动原始层，无硬编码色值。
+
+---
+

package/docs/mobile.md

@@ -0,0 +1,109 @@
+# 移动端开发指南（weifuwu）
+
+> 移动端友好由框架构造保证：**用对原语 + 守 audit 规则**，不靠每个组件"记得"。
+> 落地依据：`design/mobile-support-plan.md`（P0/P1 已完成，P2 进行中）。
+
+## 一、断点体系（布局原语）
+
+移动优先，640/768/1024 三个断点（与 `useBreakpoint` 的 mobile/tablet/desktop 对齐）：
+
+| 断点 | 类前缀 | 语义 |
+|------|--------|------|
+| ≥640px | `@sm` | 小屏以上 |
+| ≥768px | `@md` | 平板以上 |
+| ≥1024px | `@lg` | 桌面 |
+
+```html
+<div class="wf-stack wf-stack@md">…</div>   <!-- 移动纵向堆叠，md 起横向 -->
+<div class="wf-hidden@sm">…</div>           <!-- 移动端隐藏 -->
+```
+
+- 组件级移动适配用 `@media (max-width: 639px)`（bottom-sheet/全宽抽屉）或 `(max-width: 767px)`（双栏堆叠）
+- 触屏判定用 `@media (pointer: coarse)`（44px 命中区），**不要**用 width 猜触屏
+
+## 二、命中区纪律（44px，Apple HIG / WCAG 2.5.8）
+
+- **button/input/select 由全局 coarse 规则自动覆盖**（`_base.css`）
+- **非 button 交互元素**（div/label/span 带 onClick）必须进 coarse 44px 清单——style-audit 规则强制，新组件漏了测试红
+- **小组件**（圆点/星/勾选框）视觉尺寸不变，用 `::after` 扩展命中区（参考 Carousel dot）：
+
+```css
+@media (pointer: coarse) {
+  .wf-carousel-dot {
+    position: relative;
+  }
+  .wf-carousel-dot::after {
+    content: '';
+    position: absolute;
+    inset: -14px;
+  }
+}
+```
+
+- 小按钮（显式 `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）
+```
+
+**内置行为**：hover 桌面 / tap 触屏 / Escape（document 级，portal 内也可关）/ 外部点击 / 视口 clamp / 宽度 clamp。
+
+**边界**：Modal/Drawer 全屏对话框不进 usePopup（focus-trap/scroll-lock 各自实现）。
+
+## 四、手势原语
+
+| 原语 | 用法 | 场景 |
+|------|------|------|
+| `ctx.ui.useLongPress({ onLongPress, duration })` | spread 到目标 | ContextMenu 触屏长按（已内置双通道） |
+| `ctx.ui.useVisualViewport()` | 返回 `{ height, offsetTop, keyboardOpen }` 响应式 | fixed 底部栏被键盘遮挡（AiChat `raiseOnKeyboard`） |
+| `ctx.ui.useBreakpoint()` / `useMedia()` | 断点回调 | JS 侧响应式 |
+| `ctx.ui.useHoverCapable()` | boolean | 自定义 hover/tap 双模式 |
+
+## 五、safe-area（刘海屏/Home 条）
+
+```html
+<div class="wf-safe-bottom">…</div>   <!-- padding-bottom: env(safe-area-inset-bottom) -->
+<div class="wf-safe-top">…</div>
+```
+
+底部抽屉/Modal bottom-sheet 已内置（P2）。
+
+## 六、防横向溢出（375px 验收基线）
+
+- 弹层宽度：usePopup 自动 `max-width: min(…, calc(100vw - 32px))`；手动浮层加 `.wf-popup` 基类
+- 宽内容（表格/双栏）：容器 `overflow-x: auto`（Table/Resizable 已内置）
+- 网格：`minmax(min(100%, 420px), 1fr)`（防 minmax 固定值撑破窄屏）
+- 验收：375×667 视口 `document.documentElement.scrollWidth <= innerWidth`
+
+## 七、验证清单
+
+1. 375px 视口无横向溢出
+2. 交互元素 tap 可达（44px 命中区）
+3. hover 组件 tap 可开、点外部可关、Escape 可关
+4. ContextMenu 长按触发
+5. 键盘弹起不遮挡输入（fixed 底部栏）
+6. 桌面视口行为不变（hover 仍 hover）
+7. style-audit 18 规则全绿 + `npm test` ≤15s
+
+## 八、已知裁剪/例外（诚实声明）
+
+- Rate 星 / Tree 勾选 / Slider 手柄：视觉小标记，命中区依赖行级容器（不做元素级 44px，避免破坏视觉）
+- ⌘K 类快捷键在移动端无键盘语义（Command 需显式触发按钮）
+- `raiseOnKeyboard` 默认 false：内联 chat 靠原生聚焦滚动；全屏 chat 布局才抬升

package/docs/realtime.md

@@ -0,0 +1,291 @@
+# 实时与渲染 — scheduler / ui / graphql / WebSocket（weifuwu）
+
+> 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
+
+## scheduler — 计划任务（即时/延时/cron）
+
+> 依赖 `queue`（触发后入队执行）。三类任务：即时（queue.add 已有）、延时（`ctx.schedule`）、定时（`ctx.cron`）。
+
+```ts
+import { queue, scheduler } from 'weifuwu'
+
+const q = queue()
+app.use(q)
+app.use(scheduler({ queue: q }))       // 依赖 ctx.queue（触发后入队）
+
+// 延时任务（单次）：delayMs 或指定时间
+await ctx.schedule('email.send', { to, body }, { delayMs: 30_000 })
+await ctx.schedule('report.build', {}, { when: new Date('2026-09-01T00:00:00Z') })
+
+// cron 定时任务（重复）：每分钟触发 → 入队执行
+ctx.cron('* * * * *', 'heartbeat.check', { scope: 'health' })
+// 改需求 = 重新注册（同 name 覆盖更新，旧定义不残留）
+ctx.cron('*/5 * * * *', 'heartbeat.check', { scope: 'health' })
+// 停用 = cancel（删定义 + 清理 pending 触发点）
+await ctx.cancelCron('heartbeat.check')
+
+// 执行端：与 queue 完全一致
+const worker = ctx.queue.worker('email.send', async (job) => { ... })
+```
+
+- **延时**：ZSET（score=触发时间戳）+ 守护循环（独立连接）→ 到期 `ZREM` 原子抢占（多实例不重复）→ `queue.add`
+- **多应用隔离**：`scheduler({ prefix })`——ZSET/HASH 应用级共享，多应用共用 redis 时必须各自 prefix（同应用多实例共享 prefix = 协作消费）
+- **cron**：HASH 注册表（**field = name，同 name 重新注册 = 覆盖更新**，改表达式不残留旧定义）+ 滚动生成触发点（`ZADD NX` 幂等）→ 复用延时链路；`nextRunAt` 原子推进
+- **取消**：`ctx.cancelCron(name)` 删定义 + 清理 pending 触发点（停用 cron 必须 cancel——定义无 TTL 会累积）
+- **崩溃恢复**：未消费触发点留在 ZSET，重启后补扫立即触发（at-least-once，幂等由业务保证）
+- **cron 表达式**：5 字段（分 时 日 月 周），支持 `*`/步进/列表/范围；时区 = 服务器本地；非法表达式注册即抛错
+- **裁剪**：❌ cron 秒/年/别名（@daily）/特殊字符（L/W/#）、时区配置、单次任务取消（v2）、分布式锁（原子命令抢占替代）
+- **文档红线**：cron 定义持久化在 HASH——进程重启后守护循环恢复即继续触发（无需重新注册）；**停用必须 `cancelCron`**（定义无 TTL，不取消会永久触发）
+
+## ui — SSR 渲染 + JS/CSS 编译
+
+```ts
+import { ui } from 'weifuwu'
+
+app.use(ui())
+```
+
+| ctx 注入 | 签名 | 说明 |
+|----------|------|------|
+| `ctx.ui.html` | `` (strings, ...values) => Response `` | HTML 模板 (转义防 XSS) |
+| `ctx.ui.html.unsafe(str)` | `(string) => string` | 插入原始 HTML |
+| `ctx.ui.js(entryPath)` | `(string) => Promise<Response>` | esbuild 编译 TSX → JS bundle |
+| `ctx.ui.css(entryPath)` | `(string) => Promise<Response>` | 读取 CSS 文件 → CSS Response（如安装 postcss + @tailwindcss/postcss 则自动编译） |
+| `ctx.ui.ssr(Comp, props?, { data })` | `(Component, props, opts?) => Promise<string>` | 服务端渲染组件 → HTML 片段（async 工厂自动 await；HtmlSafe 内联不二次转义） |
+| `ctx.ui.ssrData(data)` | `(Map) => string` | 序列化 SSR 数据 → `<script>window.__DATA__=...</script>`（`<` 转义防 XSS） |
+
+### ctx.ui.html — HTML 模板
+
+模板插值自动转义（`& < > "` → 实体），防 XSS：
+
+```ts
+app.get('/page', (req, ctx) => ctx.ui.html`
+  <h1>${title}</h1>          <!-- 自动转义 -->
+  <div>${ctx.ui.html.unsafe(richHtml)}</div>  <!-- 不转义 -->
+`)
+```
+
+### ctx.ui.js — 编译 TSX → JS
+
+```ts
+app.get('/app.js', (req, ctx) => ctx.ui.js('./src/main.tsx'))   // 相对路径
+app.get('/app.js', (req, ctx) => ctx.ui.js('weifuwu/client'))   // 或包名
+```
+
+使用 esbuild 编译：
+- `bundle: true`, `format: 'esm'`, `platform: 'browser'`
+- `jsx: 'automatic'`, `jsxImportSource: 'weifuwu/client'`
+- 带 mtime 缓存验证（开发时编辑文件后自动失效）
+
+### ctx.ui.css — CSS 编译
+
+```ts
+app.get('/style.css', (req, ctx) => ctx.ui.css('./src/style.css'))               // 相对路径
+app.get('/style.css', (req, ctx) => ctx.ui.css('weifuwu/components/style.css'))   // 或包名
+```
+
+- 无编译工具时直接返回原始 CSS
+- 检测到已安装 `postcss` + `@tailwindcss/postcss` 时自动编译 Tailwind CSS
+- 支持包名（`weifuwu/layout/style.css`, `weifuwu/components/style.css`）或文件路径
+- 带 mtime 缓存验证（开发时编辑文件后自动失效）
+
+### ctx.ui.ssr — SSR 渲染组件 → HTML
+
+将组件（含 async 工厂组件）在服务端渲染为完整 HTML 片段，数据经 `ctx.data` 预取并序列化进 `window.__DATA__`（客户端 hydration 时同步命中，不重跑请求）：
+
+```ts
+const BlogPage = asyncComponent(async (ctx) => {
+  const post = await ctx.data.get(`/api/posts/${ctx.params.slug}`, fetchPost)
+  return (_init, ctx) => () =>
+    h('article', {},
+      h('h1', {}, post.title),
+      h('div', { innerHTML: post.body }),
+    )
+})
+
+app.get('/blog/:slug', async (req, ctx) => {
+  const data = new Map()
+  const html = await ctx.ui.ssr(BlogPage, {}, { data })   // HtmlSafe：模板内联不二次转义
+  return ctx.ui.html`
+    <!DOCTYPE html>
+    <html><body>
+      <div id="root">${html}</div>
+      ${ctx.ui.ssrData(data)}
+      <script src="/static/app.js"></script>
+    </body></html>
+  `
+})
+```
+
+- 事件处理器/ref 剥离，文本自动转义（XSS），`class`/`style` 对象序列化，`innerHTML` 原样输出
+- Fragment/Portal 子节点就地内联
+- `ctx.ui.ssrData(data)` 输出 `<script>window.__DATA__=...</script>`（JSON `<` 转义防 XSS）
+- 服务端 ctx shim：`$`（dirty no-op）、`ctx.data` 预取去重、`selfId` 请求级隔离
+
+### Hydration — 客户端收养服务端 HTML
+
+服务端 HTML + `window.__DATA__`（ctx.data 种子）到达客户端后，`mount(..., { hydrate: true })` **收养现有 DOM**（不重建、不闪跳），只接线事件/ref/$：
+
+```ts
+import { createApp } from 'weifuwu/client'
+
+createApp()
+  .mount('#root', BlogPage, { hydrate: true })   // 容器已有服务端 HTML
+```
+
+- **游标收养**：元素/文本按位置匹配现有 DOM；tag 不匹配 → 局部替换；文本不一致 → 就地修正；服务端多余节点 → 收尾清理
+- **async 工厂 hydration**：工厂 `ctx.data.get` 从 `__DATA__` 同步命中（不重跑请求）→ 渲染与服务端一致 → 收养
+- hydration 后 `$`/dirty/事件全量可用（与纯 SPA 无差别）
+- 诚实裁剪：Portal 内容就地收养（不移动到 `#__wf_portal`）；渲染期非确定性（Date/random）会导致 mismatch（dev 警告）
+
+### uiSsr — 路由级 SSR（声明即渲染）
+
+共享路由定义，前后端同一份声明——后端匹配即自动 SSR，无需手写 handler/模板/序列化：
+
+```tsx
+// routes.tsx —— 前后端共用
+import type { RouteDef } from 'weifuwu/client'
+import { BlogPage } from './pages/BlogPage.tsx'
+
+export const routes: RouteDef[] = [
+  { path: '/blog/:slug', component: BlogPage, title: '博客' },
+]
+
+// server.ts —— 一行中间件：GET 匹配 → 注入 ctx.route.params → await 组件工厂 → 完整 HTML + __DATA__ + bundle
+import { uiSsr } from 'weifuwu'
+app.use(uiSsr({ routes, bundle: '/static/blog.js' }))
+
+// blog-hydrate.ts —— 客户端：同一份 routes，router() 注入 ctx.route.params（两端同源）
+createApp()
+  .use(router({ routes }))
+  .mount('#root', routes[0].component, { hydrate: true })
+```
+
+- 组件工厂读 `ctx.route.params`（`/blog/:slug` → `ctx.route.params.slug`）——后端 uiSsr / 前端 router **同源注入**
+- 未匹配 → next()（交给 API/静态/404）；非 GET → next()
+- 可自定义 `title` / `template`
+
+### weifuwu/dev — 服务端直接跑 .tsx
+
+Node 原生 TS 只剥离类型（不支持 JSX）。`weifuwu/dev` 注册 esbuild loader，服务端直接跑 `.tsx`（零构建）：
+
+```json
+{
+  "scripts": {
+    "dev": "node --import weifuwu/dev server.ts",
+    "start": "node --import weifuwu/dev server.ts"
+  }
+}
+```
+
+- 前后端同一 JSX 运行时（`jsxImportSource: weifuwu/client`）→ 两端 VNode 一致 → hydration 可靠
+- 与 `ctx.ui.js` 前端动态编译同一理念：无构建、无产物、改代码即生效
+
+---
+
+## graphql — GraphQL 端点
+
+> **SDL + resolvers 绑定为自研实现**（`makeExecutableSchema`，56 行替代 @graphql-tools/schema）——支持根类型与嵌套类型字段 resolver、默认属性查找。
+
+```ts
+import type { GraphQLHandler } from 'weifuwu'
+
+const handler: GraphQLHandler = async (req, ctx) => ({
+  schema: `
+    type Query {
+      hello: String
+      users: [User]
+    }
+    type User { id: ID, name: String }
+  `,
+  resolvers: {
+    Query: {
+      hello: () => 'world',
+      users: () => [{ id: 1, name: 'Alice' }],
+    },
+  },
+  rootValue: {},
+  context: (req, ctx) => ({ user: ctx.user }),
+  graphiql: true,
+  maxDepth: 10,
+  timeout: 30000,
+})
+
+// 挂载到 /
+app.graphql(handler)
+
+// 或挂载到自定义路径
+app.graphql('/graphql', handler)
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `schema` | `string \| GraphQLSchema` | — | SDL 字符串或 Schema 对象 |
+| `resolvers` | `any` | — | 解析器（schema 为字符串时必填）|
+| `rootValue` | `any` | — | 根值 |
+| `context` | `(req, ctx) => object` | — | 上下文工厂 |
+| `graphiql` | `boolean` | — | 启用 GraphiQL IDE |
+| `maxDepth` | `number` | `10` | 查询深度限制（0=关闭）|
+| `timeout` | `number` | `30000` | 执行超时（ms，0=关闭）|
+
+GET 请求支持 query 参数查询；POST 支持 JSON body。启用 `graphiql: true` 时，GET 无 `?query=` 参数返回 GraphiQL IDE 页面。
+
+---
+
+## WebSocket
+
+```ts
+app.ws('/chat/:room', {
+  open(ws, ctx) {
+    ws.send(`欢迎加入 ${ctx.params.room} 房间`)
+    ctx.hub?.join(ctx.params.room, ws)
+  },
+  message(ws, ctx, data) {
+    // data: string | Buffer
+    ctx.hub?.send(ctx.params.room, `用户: ${data}`)
+  },
+  close(ws, ctx) {
+    ctx.hub?.leave(ws)
+  },
+  error(ws, ctx, error) {
+    console.error('WS error:', error)
+  },
+})
+```
+
+| 回调 | 参数 | 说明 |
+|------|------|------|
+| `open(ws, ctx)` | `WebSocket`, `Context` | 连接建立 |
+| `message(ws, ctx, data)` | `WebSocket`, `Context`, `string \| Buffer` | 收到消息 |
+| `close(ws, ctx)` | `WebSocket`, `Context` | 连接关闭 |
+| `error(ws, ctx, error)` | `WebSocket`, `Context`, `Error` | 错误 |
+
+### Hub — WebSocket 房间
+
+```ts
+// 注入 hub → ctx.hub
+app.ws('/chat/:room', {
+  open(ws, ctx)  { ctx.hub.join(ctx.params.room, ws) },
+  message(ws, ctx, data) { ctx.hub.send(ctx.params.room, String(data)) },
+  close(ws, ctx) { ctx.hub.leave(ws) },
+})
+
+// 自定义 Hub（Redis 后端）
+import type { Hub } from 'weifuwu'
+const redisHub: Hub = { ... }
+app.wsHub(redisHub)
+```
+
+| Hub 方法 | 说明 |
+|----------|------|
+| `join(key, ws)` | WebSocket 加入房间 |
+| `leave(ws)` | WebSocket 离开所有房间 |
+| `send(key, message)` | 向房间广播消息 |
+| `close()` | 关闭 Hub |
+
+WebSocket 原生 `ws.send()` 发送，`ws.on('message', cb)` WebSocket 接收。
+
+> **实时应用推荐用 `messager()`**（SaaS 地基模块）：协议内置（`connected/subscribe/ping`）+ 持久化 + 跨进程广播 + 点对点，不必自写 Hub/协议——见[消息系统章节](saas.md)。
+
+---
+