weifuwu 0.87.0 → 0.89.0

package/content/guides/custom-component.md

@@ -1,321 +0,0 @@
-# 自定义组件开发指南
-
-> 从 docs/custom-components.md 迁移（2026-08）——自定义组件全流程：骨架/状态/弹层/对话框/AI/异步/类型/测试/受控/动画/浏览器纪律/样式纪律。
-> 逐步指南配套：[选型](choose.md) · [组件模型](component-model.md) · [质量标准](quality.md)
->
-> ⚠️ **先读 [组件编写标准（强制）](component-standards.md)**——L1 类型/L2 运行时检测/L3 契约测试
-> 三层强制——本文是流程，标准是红线。
-
-# 自定义组件开发指南
-
-
-> ⚠️ **weifuwu/client 已并入 `weifuwu/ui-dom`**（`src/client/` 已删除）——前端运行时唯一入口为 `weifuwu/ui-dom`，见 [ui-dom 指南](ui-dom-guide.md)。
-> 用 weifuwu/ui-dom 写自己的组件——与内置组件同权：同渲染引擎、同弹层原语、同类型安全。
-> 前置：[前端概念](frontend.md)（两阶段模型/ctx.ui）+ [组件速查](components-guide.md)。
-
----
-
-## 0. 最小骨架
-
-```tsx
-import { h, type Component } from 'weifuwu/ui-dom'
-
-// Component<P, C>：P = props（JSX 自动推断），C = ctx 注入依赖（默认 {}）
-const Badge: Component<{ text: string; color?: string }> = async () =>
-  async (props) => h('span', { class: 'my-badge', style: { color: props.color } }, props.text)
-```
-
-- 两阶段：外层 `(initProps, ctx) => …` 只执行一次（mount），内层 `(props) => Promise<VNode>` 每次渲染执行（renderFn 强制异步——可 await 数据）
-- 有状态组件用闭包 `let` + 事件里 `ctx.ui.render()`（render-only）；不需要渲染的状态不调 `render()`
-
-### mount 与 render 的职责（事件函数写在哪层）
-
-| | mount（外层工厂，一次） | render（内层 renderFn，每次） |
-|---|---|---|
-| 职责 | 初始化状态 / 订阅 / 定时器 / **定义依赖稳定引用的回调** | 读最新 props / 派生数据 / **定义依赖它们的回调** / 输出视图 |
-| 可访问 | `initProps`（首次）、`ctx`、mount `let`、稳定 handle | 最新 `props`、mount 闭包、`ctx` |
-| 事件函数 | **只依赖稳定引用**（ctx / mount let / 稳定 handle 如 useChat 的 `chat`）→ mount 定义，天然引用恒等 | 依赖最新 props / 派生状态（如 Table 的 `rowSelection`、Menu 的 `openSet`）→ render 内定义（闭包捕获最新值） |
-
-```tsx
-const AiChat = async (initProps, ctx) => {
-  const chat = initProps.chat           // 稳定 handle（useChat 返回，引用不变）
-  const onSend = () => chat.send()      // ✅ mount 定义：只依赖稳定引用——引用恒等，零重绑
-  return async (props) => {
-    const onSelect = (k: string) => props.onSelect?.(k)   // ✅ render 定义：依赖最新 props——闭包捕获当前值
-    return h('button', { onClick: onSelect }, '选')
-  }
-}
-```
-
-**规则**：回调只依赖 ctx / mount `let` / 稳定 handle → **mount 定义**（天然稳定，不重绑）；依赖最新 props / 派生数据 → **render 内定义**（闭包捕获最新值；引用变化导致事件重绑是**正确性要求**——必须读最新状态，框架不做稳定引用魔法）。
-
-## 1. 有状态组件
-
-```tsx
-const Toggle: Component = async (_init, ctx) => {
-  let on = false        // 普通对象状态（render-only：无 $ Proxy）
-
-  return async (props) => h('button', {
-    class: 'my-toggle',
-    onClick: () => { on = !on; ctx.ui.render() },   // 改状态后显式 render()
-  }, on ? '开' : '关')
-}
-```
-
-| 状态类型 | 存放位置 | 触发渲染 |
-|---------|---------|---------|
-| 组件内部状态 | 闭包 `let` | 改后调 `ctx.ui.render()` |
-| 共享状态 | `createStore` + `ctx.ui.useExternal()` | store 变更自动 |
-| 内部缓存 | 闭包 `let` | 不触发 |
-
-## 2. 带弹层的组件（最高频的自定义场景）
-
-用 `ctx.ui.openPopup`——命令式弹窗（toast 心智——调用点构建内容——内核
-  自管理挂载/更新/卸载——返回 handle `{ close, update, open }`——定位/外部点击
-  /Escape/视口夹紧/presence/mask 全内置）——组件输出纯业务（无槽）
-
-```tsx
-const MyPopover: Component<{ content: string }> = async (_init, ctx) => {
-  let open = false
-  let wrapEl: HTMLElement | null = null
-  const wrapRef = (el: HTMLElement | null) => { wrapEl = el }
-  let handle: PopupHandle | null = null
-
-  // 句柄同步样板（受控 + 内容更新 + 关闭清理——每次渲染恒调用）
-  const syncPopup = (content: string) => {
-    if (open && !handle)
-      handle = ctx.ui.openPopup({
-        anchor: () => wrapEl,     // **anchor 必传**（触发区是锚点——否则被当外部点击关闭）
-        content: () => h('div', { class: 'wf-panel' }, 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-panel' }, content))
-  }
-
-  return async (props) => {
-    syncPopup(props.content)
-    return h('span', {
-      class: 'anchor', ref: wrapRef,
-      onMouseEnter: () => { open = true; ctx.ui.render() },   // hover 触发（组件自管）
-      onMouseLeave: () => { open = false; ctx.ui.render() },
-    }, props.children)
-  }
-}
-```
-
-> **受控弹层**：open 状态由父组件独占（props.open + onOpenChange）——组件内部
-> 只做句柄同步；非受控（无 open prop）时组件自管状态（`let open` + 触发事件）。
-> **关闭路径**：内核 onClose 回调（外部点击/Escape 触发）同步句柄 + 状态——
-> 组件无需显式清空（内核 dispose 全权）。
-
-## 3. 对话框类组件（Modal 系）
-
-全屏对话框（焦点 trap + 滚动锁 + 退场动画）是 openPopup 的**会话级模态模式**
-（`presence/trapFocus/lockScroll/positioning: 'none'`——Modal/Drawer 同款）：
-
-```tsx
-const MyDialog: Component<{ open: boolean; onClose: () => void }> = async (_init, ctx) => {
-  let handle: PopupHandle | null = null
-  return async (props) => {
-    // 命令式同步（受控 + 退场：关闭前先渲染 exit class → close 播动画）
-    if (props.open && !handle)
-      handle = ctx.ui.openPopup({
-        key: 'dialog',
-        presence: true,      // 退场状态机（open → exit → closed + animationend）
-        trapFocus: true,     // 焦点 trap（面板挂载锁定/卸载归还）
-        lockScroll: true,    // 滚动锁（打开锁 / 卸载释放）
-        positioning: 'none', // 组件自定义定位（.wf-modal inset:0 居中）
-        closeOnOutside: false, closeOnEscape: false, // 关闭语义组件自控
-        content: () => h('div', { class: 'wf-overlay', onClick: (e: any) => { if (e.target === e.currentTarget) props.onClose() } },
-          h('div', { class: `wf-modal ${props.open ? 'wf-modal--enter' : 'wf-modal--exit'}`,
-            onKeyDown: (e: any) => { if (e.key === 'Escape') props.onClose() } }, props.children)),
-        onClose: () => { handle = null },
-      })
-    else if (!props.open && handle) { handle.update(rootVn); handle.close(); handle = null }
-    else if (handle) handle.update(rootVn)
-    return null   // 主树零输出
-  }
-}
-```
-
-> **ref 接线**：`trapFocus`/`lockScroll`/presence 退场监听全部由 openPopup 内核接线
-> （面板根元素自动挂 ref——组件层无需手挂）——低层原语已收编为内核实现（不对外导出）。
-> `animateOut` 仍可用（非弹窗动画场景）。
-
-## 4. AI 组件
-
-会话语义由 `ctx.ui.useChat` 提供（消息/流式/工具/审批/stop/retry 全封装），返回的 handle 与 `$` 同一容器：
-
-```tsx
-const ChatPanel: Component = async (_init, ctx) => {
-  const chat = ctx.ui.useChat({
-    url: '/api/chat',
-    approveUrl: '/api/approve',   // HITL 审批上行（缺省 approve() 只清卡片）
-    body: (messages) => ({ messages, mode: 'agent' }),
-  })
-
-  return () => h('div', { class: 'chat' },
-    h(AiChat, { chat }),                    // 标准界面：输入/消息/流式/工具卡全内置
-    h('button', { onClick: () => chat.send() }, chat.streaming ? '…' : '发送'),
-  )
-}
-```
-
-**共享 handle 给子组件**（如 `<AiChat chat={chat} />`）：会话 handle 带 `subscribe(cb)`——子组件 mount 期 `ctx.ui.useExternal(initProps.chat)` 自订阅（AiChat 已内置），会话状态变化自动重渲染订阅组件。
-
-## 5. 异步组件（数据声明在工厂层）
-
-组件 = 函数，async 组件 = async 函数——**不需要包装**，签名与同步组件一致：
-
-```tsx
-const UserCard = async (initProps, ctx) => {
-  const user = await ctx.data.get(`/api/user/${initProps.userId}`)  // 三场景：SSR→__DATA__ / hydration 种子 / SPA fetch
-  let liked = false
-  return async (props) => h('div', {}, user.name, h('button', { onClick: () => { liked = !liked; ctx.ui.render() } }))
-}
-```
-
-- 渲染器按「返回值是 Promise」判别：主路径 `buildVNode` await 全部（无占位）；运行时首次挂载的 async 组件在 buildVNode 阶段 await（无占位/补全回调）；SSR 直接 await
-- 工厂按实例执行；**数据必须走 ctx.data**（缓存+并发合并，重复执行零成本）；禁止副作用裸写工厂
-- **个性化数据不进 ctx.data**（SSR 会序列化给所有客户端）——留在客户端 `let` + fetch + `render()`
-
-## 6. 类型纪律（编译期防线）
-
-```tsx
-const Badge: Component<{ variant: 'primary' | 'muted' }> = async () =>
-  async (props) => h('span', { class: `badge-${props.variant}` }, props.children)
-
-// 负例：variant 传错 → tsc 报错（@ts-expect-error 是类型流测试的写法）
-// @ts-expect-error variant 不允许 'bogus'
-const bad: { variant: 'primary' | 'muted' } = { variant: 'bogus' }
-
-// ctx 注入声明（C 泛型）：声明了才能用，未声明编译期报错
-const Page: Component<{}, { api: ApiInjected['api'] }> = async (_init, ctx) => {
-  ctx.api.get('/x')
-  return () => null
-}
-```
-
-| 规则 | 违反后果 |
-|------|---------|
-| `Component<P, C>` 类型化（禁 `_init: any`） | 编译期不可查 |
-| 受控 props 必须配回调 | 交互静默失效（组件 console.warn） |
-| ref 用 `ctx.ui.useStableRef`（禁内联 ref） | 清理逻辑每次渲染误触 |
-| 初始状态确定性（禁 `window.innerWidth` 直接初始化） | SSR/hydration mismatch |
-| 小尺寸按钮固定 min/max-height | 被全局 36px 撑成竖条 |
-
-## 7. 测试写法
-
-**官方测试原语 `weifuwu/ui-dom/testing`**（子路径，随包发布）——自研组件测试用官方工具，不手抄：
-
-```tsx
-import { renderVNode, mountComponent, findByClass, createTestCtx } from 'weifuwu/ui-dom/testing'
-// 仓库内开发用相对路径：from '../../ui-dom/testing.ts'
-
-const vnode = renderVNode(Toggle, {}, createTestCtx())
-// 断言 vnode 结构（子组件 VNode.type 是组件函数，不是标签名）
-
-// 交互流转（内部 let 状态）用 mountComponent（同实例 re-render）：
-const render = mountComponent(Toggle, {}, createTestCtx())
-render() // 初始
-// ... 触发点击/输入 ...
-render() // 重渲染，状态保留
-```
-
-- 弹层组件：`createPopupMock(isOpen)` 注入 `createTestCtx({ ui: { openPopup: (opts) => popup } })`
-- 类型流测试：`@ts-expect-error` 负例（见 [type-flow.test.ts](../../src/components/type-flow.test.ts)）
-- 组件测试跑在 node --test；DOM 事件级测试需 `document.body.appendChild(container)`
-
-## 8. 受控组件标准
-
-新受控组件**必须**用 `ctx.ui.useControlled`（受控判定 + 缺回调 warn 一次 + 非受控内部状态跨渲染保持）：
-
-```tsx
-const CollapseItem: Component<{ active?: boolean; onChange?: (v: boolean) => void }> = async (_init, ctx) => {
-  return async (props) => {
-    const ctrl = ctx.ui.useControlled<boolean>({ value: props.active, onChange: props.onChange, name: 'CollapseItem' })
-    return h('button', {
-      onClick: () => ctrl.setValue(!(ctrl.value ?? false)),   // 受控走 onChange；非受控内部状态
-    }, (ctrl.value ?? false) ? '开' : '关')
-  }
-}
-```
-
-> 多受控维度组件（Tree 的 expandedKeys+checkedKeys）不适用单值 useControlled——保留手工受控判定（参考 Tree.ts），warn 文案与 useControlled 保持一致。
-
-## 8.5 动画（4 层能力）
-
-| 层 | 原语 | 用法 |
-|----|------|------|
-| CSS 语言 | Token（`--wf-dur-*`/`--wf-ease-*`/`--wf-motion-*`）+ `--enter`/`--exit` 成对 | 组件动画统一引用 Token，禁硬编码 |
-| 生命周期 | `useAnimationEnd(cb, { once })`（完成回调）/ `usePresence({ name })`（显隐状态机）/ `animateOut(el, done)`（命令式退场） | 入场 settle / 退场延迟卸载 / 命令式播动画 |
-| 数值驱动 | `useTween(target, { duration, ease })`（补间）/ `useInView` / `useScrollPosition` | count-up / 进入视口播 / 滚动联动 |
-| 偏好感知 | `useReducedMotion()` | JS 动画（rAF/tween）侧跳过；CSS 动画 `_base.css` 已全局降级 |
-
-**纪律**：组件内动画事件监听**唯一入口是 `useAnimationEnd`**——禁直接 `addEventListener('animationend')`（DatePicker 已收敛）；退场优先 `usePresence`（声明式状态机）或 `animateOut`（命令式）。
-
-## 8.6 浏览器环境纪律（ctx.browser）
-
-> **自定义组件禁止直接引用 window/document**——统一经 `ctx.browser`：
-> SSR 安全（shim 安全默认）+ 测试 mock 单点 + 环境差异隔离。
-
-```tsx
-const MyComp: Component = async (_init, ctx) => {
-  // mount 层取 browser（ctx.browser 优先，测试/无注入环境 fallback jsdom）
-  const browser = ctx.browser ?? createClientBrowser()
-  return async (props) =>
-    h('button', {
-      onClick: () => {
-        // 复制/查询/存储/滚动——全部经 browser
-        void browser.copyText('hello')
-        const el = browser.byId('target')
-      }
-    })
-}
-```
-
-**规则**：
-- 拖拽统一 `ctx.ui.useDragDrop`（drop 侧 dropProps + drag 侧 dragProps：draggable/
-  onDragStart/onDragEnd）——**dragstart 期间禁止重渲染**（渲染替换源元素中断拖拽；
-  身份/位置在渲染期闭包绑定，拖拽视觉高亮用 CSS :hover）
-- 复制统一 `browser.copyText`（clipboard + 降级——勿自建 textarea+execCommand）
-- 键盘导航用 `browser.activeElement()`（勿 document.activeElement）
-- 存储用 `browser.storageGet/Set`（勿 localStorage 裸调）
-- SSR 场景（render/mount 期）绝对不碰环境 API（shim 返回 null——需防御）
-
-## 9. 样式纪律（style-audit 强制）
-
-- 动效用 Token：`--wf-dur-*` / `--wf-ease-*` / `--wf-motion-*`（禁硬编码）
-- 语义色用 `-text` 变体（700 级）；实心填充文字用 `--wf-color-on-brand`；遮罩 `--wf-overlay`
-- 图标用 `Icon` 组件（禁裸文本字形 ✕✓⚠▲）
-- 触屏（coarse pointer）自动 44px 命中区
-
----
-
-## 内置组件 = 最佳实践范本
-
-| 想要的能力 | 参考源码 |
-|-----------|---------|
-| 弹层组合（hover/click/longpress） | [Tooltip.ts](../../src/components/Tooltip/Tooltip.ts) / [ContextMenu.ts](../../src/components/ContextMenu/ContextMenu.ts) |
-| 对话框状态机 | [Modal.ts](../../src/components/Modal/Modal.ts) / [Drawer.ts](../../src/components/Drawer/Drawer.ts) |
-| AI 会话 | [AiChat.ts](../../src/components/AiChat/AiChat.ts) |
-| 受控 + 键盘导航 | [Collapse.ts](../../src/components/Collapse/Collapse.ts) / [Tabs.ts](../../src/components/Tabs/Tabs.ts) |
-| 异步数据 | [UserProfile](../../src/components/Img/Img.ts) 的 factory 模式 |
-| 命令式 API（toast/confirm） | [Toast.ts](../../src/components/Toast/Toast.ts) |
-
-## 已知边界（诚实裁剪）
-
-- **引擎自动写入的 DOM 属性（开发者不需要处理，但写自定义组件时会在 DOM 里看到）**：
-  - `data-wf-id`——组件实例 id，写到组件输出**每个顶层节点**（多根全部写）——渲染定位/audit/debug 用；存在性可预期，值不可预期（`_wf_N` 引擎分配）
-  - `data-wf-key`——数组项 key（显式或默认下标），写到元素项自身 / **组件项穿透到输出每个顶层节点**——列表项身份可见，动态增删重排建议显式 key（默认下标 = 位置复用 + 状态继承）
-  - `<!--wf-hole: xxx-->` 占位注释——条件渲染 false/null/true/非法输入的占位节点（`{cond && <X/>}`=false 时 DOM 里有注释而非消失）——不是 bug，是引擎的透明占位
-  - SSR 不输出 `data-wf-id`（id 客户端运行时分配）；`data-wf-key` SSR 同步输出
-  - 断言/快照测试注意：`outerHTML` 包含这些属性与占位注释；按类选择器/子项数量断言不受影响
-- **列表 key 纪律**：渲染的列表是**有内部状态的组件实例 + 动态增删/重排**（如可输入的卡片）→ 必须显式 key（项 id），否则默认下标位置复用会让后续项继承被删项的内部状态；纯元素列表（格子/行/节点 div）默认下标即可——通用列表组件对外提供 `keyBy`（如 `List`）
-
-- `openPopup` 是**统一弹窗能力层**（命令式——toast 心智）：锚定浮层（Tooltip/Popover/Dropdown/Select/AutoComplete/Mentions/Cascader/ContextMenu/NavMenu/Popconfirm/TreeSelect）+ 会话级模态（Modal/Drawer/Confirm——presence/trapFocus/lockScroll/positioning 'none'，Escape 语义留组件层）+ mask 模式（Command/Img preview/Tour）+ positioning 'none' 常驻容器（Toast/Notification）——**全部弹窗单一入口**（组件内部句柄同步样板 ~10 行——anchor 必传）
-- **事件监听纪律**：组件库内部浏览器事件监听**统一走 `ctx.ui.useXXX`**——滚动/观察/弹层/对话框/快捷键/拖拽/DnD 全覆盖：
-  `useInView`（InfiniteScroll）、`useScrollPosition`（AiChat/Affix/BackTop/VirtualList）、`usePopupPosition`（Affix 阈值重算）、`usePopup`（弹窗统一——ContextMenu 自由定位 + Modal/Drawer 模态模式 + mask 遮罩）、`useGlobalKey`（Command 快捷键/Img preview Escape）、`useDrag`（Resizable）、`useDragDrop`（FileUpload）、`useControlled`/`useStableRef`（状态/ref）
-- **唯一保留 usePopupPosition 独立使用**：Affix / Chart（坐标工具——非弹窗组合器，滚动跟随自动）
-- `createReactiveState` 已导出：组件外建全局 store（`createReactiveState(() => {})` + `$.__watch(cb)` 订阅）

package/content/guides/data-guide.md

@@ -1,281 +0,0 @@
-# 数据层指南（sql/redis）
-
-> 从 docs/data.md 迁移（content/ 文档库——随 npm 包发布，与框架版本同步）。
-> 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
-
-# 数据层 — postgres / redis（weifuwu）
-
-自研 PG v3 / RESP2 协议客户端，真实库测试（CS-04），故障恢复见各节。
-
-## postgres — PostgreSQL 客户端（自研）
-
-> **自研 PG v3 协议**（零第三方依赖）——支持 SCRAM-SHA-256 认证、扩展查询（参数化）、类型映射（int8 超范围自动 string 防丢精度）、事务、连接池（acquire 超时防饿死）、schema 写前校验、statement_timeout 慢查询保护。
-
-```ts
-import { postgres } from 'weifuwu'
-
-// 注入 ctx.sql（懒连接池）
-app.use(postgres())
-
-// ① tagged template —— 插值自动参数化（防注入）
-app.get('/users', async (req, ctx) => {
-  const users = await ctx.sql`SELECT * FROM users WHERE id = ${ctx.params.id}`
-  return Response.json(users)
-})
-
-// ② jsonb 对象直传——自动序列化，不再有双重编码/parseRow 样板
-app.post('/decks', async (req, ctx) => {
-  const deck = await req.json()
-  await ctx.sql`INSERT INTO decks (title, deck_json) VALUES (${deck.title}, ${deck})`
-  // 读回来自动是对象：rows[0].deck_json === { slides: [...] }（不是字符串）
-})
-
-// ③ 事务（中间件实例 pg.transaction——不在 ctx.sql 接口）
-const pg = postgres()
-app.use(pg)
-app.post('/transfer', async (req, ctx) => {
-  await pg.transaction(async sql => {
-    await sql`UPDATE accounts SET balance = balance - 100 WHERE id = 1`
-    await sql`UPDATE accounts SET balance = balance + 100 WHERE id = 2`
-  })
-})
-```
-
-### Query Language（`sql.query` — AST 双后端）
-
-结构化查询对象（AST）→ **真库编译参数化 SQL / 内存直执行**——同一查询两种后端，业务代码零改动切换：
-
-```ts
-// 链式 builder：SQL 能力（WHERE 合并/聚合/JOIN/子查询）以类型安全对象表达
-const rows = await sql.query.from('orders')
-  .where({ user_id: userId, status: { in: ['paid', 'shipped'] } })
-  .orderBy('created_at', 'desc')
-  .limit(20)
-  .run()
-
-// 插入 + RETURNING（onConflict 无列 = 任意唯一冲突 DO NOTHING）
-const conv = (await sql.query.insert('conversations')
-  .values({ type: 'direct', created_by: userId })
-  .returning('id', 'created_at')
-  .run())[0]
-
-// 逃生舱：raw 片段（真库透传 / 内存裁剪）
-await sql.raw`now()`
-```
-
-- **双后端一致**：内存端（MemorySql）直执行同一 AST——关联子查询/聚合/JOIN/游标分页语义对齐真库
-- **诚实裁剪**：内存不支持的语义（raw 片段/窗口函数等）抛 `ProtocolError('unsupported')`
-- 事务性写入（INSERT/UPDATE/DELETE）建议走 Query Language；分析型列表（复杂 JOIN/COALESCE）用 tagged template 真库
-
-### Memory 实现（零数据库模式）
-
-`MemorySql` / `MemoryRedis` 是**生产契约的黑盒实现**（非 mock 桩）——开发/测试/单实例部署**零外部数据库**：
-
-```ts
-import { createMemorySql } from 'weifuwu/db/memory-sql'
-import { MemoryRedis } from 'weifuwu/db/memory-redis'
-
-const sql = createMemorySql()      // 契约 Sql：tagged template / query / unsafe / raw
-const redis = new MemoryRedis()    // 契约 Redis：command / publish / subscribe / close
-
-// 注入中间件（构造注入模式——消费方只见接口）
-const msg = messager({ sql, redis })
-const q = queue({ redis })
-```
-
-- **语义对齐真库**：惰性 TTL、XREADGROUP 游标、XACK/XAUTOCLAIM、23505→409、gen_random_uuid / now() 默认值、事务 BEGIN/COMMIT no-op（回滚快照由服务器层提供）
-- **替换成本为零**：与生产实现（PgConnection/RedisClient）同一契约——业务测试跑内存、协议测试跑内存服务器、生产跑真库
-
-### 测试（零外部依赖）
-
-`npm test` **不需要 docker**——协议层测试连进程内内存服务器（`MemoryRedisServer` / `MemoryPostgresServer`：真实 TCP 线协议 RESP/PG v3 交互），业务测试跑 Memory 实现：
-
-```
-协议测试（三部分）        connection（连接/命令/断开）→ 内存服务器
-                          AST parse/stringify        → resp/protocol 编解码 + query-language
-业务测试                  user/queue/messager/rate-limit → MemorySql/MemoryRedis
-```
-
-### 类型映射（自动）
-
-| 数据库类型 | 返回 JS 类型 |
-|-----------|-------------|
-| json / jsonb | `object`（自动 JSON.parse） |
-| int2 / int4 / int8（安全范围内） | `number` |
-| **int8（超出安全范围）** | **`string`**（防静默丢精度，金额/ID 关键） |
-| float / numeric | `number` |
-| boolean | `boolean` |
-| text / varchar / uuid | `string` |
-| **timestamptz** | **`Date`**（带时区，ISO 解析无本地时区魔法） |
-| timestamp / date / interval | `string`（无时区语义——转 Date 按本地时区解析即时区魔法，诚实裁剪不转） |
-| NULL | `null` |
-
-### 类型层（查询泛型）
-
-```ts
-// 查询结果泛型（编译期类型，无需手写 interface + 断言）
-interface Deck { id: number; title: string; deck_json: { slides: unknown[] } }
-const decks = await ctx.sql`SELECT id, title, deck_json FROM decks` as Deck[]
-```
-
-### 方法面
-
-| 方法 | 说明 |
-|------|------|
-| `ctx.sql\`...\`` | tagged template → 参数化查询（插值=参数，表名需硬编码） |
-| `ctx.sql.unsafe(sql, params?)` | 原生 SQL（DDL / 动态表名；`$1` 占位符） |
-| `ctx.sql.query` | **Query Language**：`sql.query.from('users').where({...}).run()`（AST 双后端） |
-| `ctx.sql.raw\`...\`` | 逃生舱片段（`NOW() - interval '7 days'`——真库透传/内存裁剪） |
-| `pg.transaction(fn)` | 事务（中间件实例；回调收到 callable sql，postgres.js 兼容 begin 语义） |
-| `pg.migrate()` / `markMigrated` / `isMigrated` | 幂等迁移（`_weifuwu_migrations` 表） |
-| `pg.poolStats()` | 连接池摘要（active/idle/waiting/max） |
-| `ctx.sql.close()` / `pg.close()` | 关闭连接池 |
-
-### 影响行数（affectedRows）
-
-`INSERT / UPDATE / DELETE / MERGE` 的返回行数组带**非枚举** `affectedRows` 属性（不干扰 `deepEqual`/`JSON.stringify`）：
-
-```ts
-const r = await ctx.sql`UPDATE messages SET read = true WHERE id = ${id}`
-if (r.affectedRows === 0) return new Response('not found', { status: 404 })
-```
-
-### 条件片段（嵌套过滤）
-
-```ts
-const status = req.query.status // 可能为空
-const rows = await ctx.sql`
-  SELECT * FROM orders WHERE amount > ${100}
-    ${status ? ctx.sql`AND status = ${status}` : ctx.sql``}
-`
-// 空片段内联为空，参数自动重编号——同一 SQL 无论条件多少都安全参数化
-```
-
-### 选项
-
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `connection` | `string` | `DATABASE_URL` | 连接字符串 |
-| `max`（或 `poolSize`） | `number` | `10` | 连接池大小 |
-| `acquireTimeoutMs` | `number` | `30000` | 池全忙时 acquire 超时（防饿死，0=无限） |
-| `statementTimeoutMs`（或 `statementTimeout`） | `number` | `0` | 语句超时（慢查询保护，0=禁用） |
-| `idleTimeoutMs` | `number` | `0` | 空闲连接回收（超时未用关闭，容量收缩后自动重建；0=禁用） |
-| `onQuery` | `(sql, durationMs, rowCount, traceId?) => void` | — | 查询观测钩子；第 4 参数为请求级 traceId（`x-trace-id` 头经 ALS 传播） |
-
-### 幂等迁移（内置）
-
-`postgres()` 返回的中间件自带迁移跟踪（`_weifuwu_migrations` 表），模块启动时检查-执行-记录三步幂等：
-
-```ts
-const db = postgres()
-await db.migrate()        // ① 建迁移跟踪表（幂等）
-
-if (!(await db.isMigrated('users'))) {       // ② 检查是否已迁移
-  await db.sql.unsafe(`CREATE TABLE users (...)`)
-  await db.markMigrated('users')             // ③ 记录（幂等，重复调用无害）
-}
-
-app.use(db)
-```
-
-> 多副本部署时天然安全：`markMigrated` 用 `ON CONFLICT DO NOTHING`，两个实例同时迁移也不会重复执行。
-
-### 错误映射（自动）
-
-`ctx.sql` 查询错误自动映射为 `HttpError`，业务无需手写 catch：
-
-| 错误码 | 含义 | HTTP |
-|--------|------|------|
-| `23505` | 唯一约束冲突 | **409** |
-| `23503` / `23502` / `23514` | 外键 / 非空 / 检查约束 | **400** |
-| `22P02` / `22003` | 类型 / 数值错误 | **400** |
-
-> 未映射的错误码原样抛出（带 `code` 属性，如 `42P01` 表不存在）。
-
-> **裁剪声明**：逻辑复制 / 大对象 / 显式游标 / 二进制 COPY 不支持（明确抛 `ProtocolError('unsupported')`，而非静默出错）。
-
----
-
-## redis — Redis 客户端（自研）
-
-> **自研 RESP2 协议**（零第三方依赖）——连接/重连（断线 pending 拒绝、指数退避）/离线队列/管道/Pub-Sub（订阅断线自动重放）+ 消除 ioredis 高频痛点（TTL 参数顺序、JSON 手动序列化、缓存样板）。**二进制安全**：`getBuffer(key)` 原样返回字节（缓存序列化 payload 不损坏）。
-
-```ts
-import { redis } from 'weifuwu'
-
-app.use(redis())
-
-// ① TTL 安全 —— 直接传秒，不会写错
-app.post('/cache/:key', async (req, ctx) => {
-  const { value } = await req.json()
-  await ctx.redis.set(ctx.params.key, value, 3600)  // ioredis 要 set(k, v, 'EX', 3600)
-})
-
-// ② JSON 零样板 —— 自动序列化（AI 缓存场景）
-app.get('/cache/:key', async (req, ctx) => {
-  const val = await ctx.redis.jsonGet(ctx.params.key)  // 自动 JSON.parse
-  return Response.json(val ?? { miss: true })
-})
-
-// ③ 缓存便捷 —— 读-算-写一体，null 不缓存（防穿透）
-app.get('/llm/:id', async (req, ctx) => {
-  const result = await ctx.redis.cache(`llm:${ctx.params.id}`, async () => {
-    return await generateLLM(ctx.params.id)  // miss 才执行
-  }, 3600)
-  return Response.json(result)
-})
-
-// ④ Pub/Sub —— 发布用 ctx.redis，订阅用独立连接（回调式，断线自动重连恢复订阅）
-app.post('/events', async (req, ctx) => {
-  await ctx.redis.publish('events', JSON.stringify({ type: 'deck.created' }))
-})
-
-const sub = ctx.redis.createSubscriber()
-await sub.connect()
-await sub.subscribe('events', (channel, message) => {
-  // 收到实时消息
-})
-await sub.psubscribe('jobs:*', (channel, message) => {
-  // 模式匹配订阅
-})
-
-// ⑤ 任意命令透传 + keyPrefix 隔离
-await ctx.redis.command('LRANGE', 'list', '0', '-1')
-
-app.use(redis({ keyPrefix: 'api:' }))  // 之后所有 key 自动加前缀
-await ctx.redis.set('user', 1)         // 实际写入 'api:user'
-```
-
-### 方法面
-
-| 方法 | 说明 |
-|------|------|
-| `get / set(key, val, ttl?) / del / incr / expire / ttl` | 基础命令（set 直接传秒） |
-| `jsonGet / jsonSet(key, val, ttl?)` | JSON 自动序列化 |
-| `cache(key, fn, ttl)` | 缓存读-算-写（null 不缓存防穿透） |
-| `publish(channel, msg)` | Pub-Sub 发布 |
-| `createSubscriber()` | 独立订阅连接（`subscribe`/`psubscribe` 回调式） |
-| `hset / hget / hgetall / hdel` | hash 字段读写（`hgetall` → `Record`，缺失 `{}`） |
-| `lpush / rpush / lpop / rpop / lrange` | list 队列操作（`lrange` 支持负数区间） |
-| `sadd / srem / smembers` | set 成员操作（`sadd` 重复不加） |
-| `zadd / zrange` | zset 有序集（score 升序） |
-| `mget / mset / exists / setnx / incrby` | 批量读写 / 存在性 / 原子设值（锁基础）/ 增量 |
-| `pipeline()` | 管道：批量命令一次往返（池级，key 自动加前缀） |
-| `command(name, ...args)` | 底层命令透传 |
-| `close()` | 关闭连接池 |
-
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `url` | `string` | `REDIS_URL` 环境变量（两者都缺 → 构造抛错，禁止静默回退 localhost） | 连接字符串 |
-| `poolSize` | `number` | `5` | 连接池大小 |
-| `keyPrefix` | `string` | `''` | 所有 key 自动加前缀（多应用隔离） |
-| `commandTimeoutMs` | `number` | `0` | 命令超时（阻塞命令 resolve(null)；防挂起。0=禁用） |
-| `onCommand` | `(command, args, durationMs, traceId?) => void` | — | 命令观测钩子；第 4 参数为请求级 traceId（`x-trace-id` 头经 ALS 传播） |
-| `socketTimeoutMs` | `number` | `0` | socket 响应超时（僵尸连接自愈：pending 有命令且超时无数据 → 主动断开重连。0=禁用） |
-
-> **连接健康**：断线自动剔除死连接并重建（池不萎缩）；`CLIENT KILL`/网络抖动后服务自愈，命令不命中死连接。
-
-> **裁剪声明**：集群（MOVED 路由）/ 哨兵 / 自动管道不支持（standalone 优先）。
-
----
-

package/content/guides/file-preview-family.md

@@ -1,18 +0,0 @@
-# FilePreview 家族 · components
-
-> Office 文档域组件——单入口发现全部能力（07 命名治理：家族归并）。
-> 顶层 `SheetGrid` / `SlideCanvas` 导出保留（向后兼容），新代码推荐命名空间访问。
-
-| 成员 | 命名空间访问 | 顶层别名 | 能力 |
-|------|------------|---------|------|
-| FilePreview | `FilePreview` | — | 多类型预览/编辑入口（md/html/pdf/office/text + 图片） |
-| SheetGrid | `FilePreview.Sheet` | `SheetGrid` | xlsx 网格编辑器（ODES 事件流——单元格编辑/公式/样式） |
-| SlideCanvas | `FilePreview.Slide` | `SlideCanvas` | pptx 画布编辑器（幻灯片/元素/转换） |
-
-## 选型
-
-```
-未知类型文件 → FilePreview（自动识别 + 降级）
-xlsx 数据编辑 → FilePreview.Sheet（或 SheetGrid）
-pptx 画布编辑 → FilePreview.Slide（或 SlideCanvas）
-```