weifuwu 0.58.0 → 0.59.1

package/README.md

@@ -1,6 +1,6 @@
 # weifuwu
 
-**全栈框架 — 后端 HTTP 路由 + 前端 VDOM 框架 + 纯 CSS 布局系统**
+**一个包的全栈框架** — 后端 HTTP + 前端 VDOM + 组件库 + CSS 设计系统。全自研、零配置、消灭样板。
 
 ```bash
 npm install weifuwu
@@ -17,21 +17,46 @@ npm install weifuwu
 
 ## 设计理念
 
+### 一句话
+
+**weifuwu = 一个包的全栈框架：全自研、零配置、消灭样板。** 下面三条核心哲学与十条技术原则都是这句话的展开——我们不做缝合框架，每一层都自研且可预测。
+
+### 核心哲学
+
+**① 一个包，全栈一体。** 后端、前端、组件、样式装在一个 npm 包里，零配置、零构建、纯 link 可用：服务端 `--import weifuwu/dev` 直接跑 `.tsx`（Node loader + esbuild 同步编译）；浏览器 CDN import map 直接跑；CSS 一条 link 即得完整设计系统。
+
+**② 全自研，诚实裁剪。** VDOM、PG v3 / RESP2 协议、GraphQL schema、OpenAI 兼容流式协议——全部自研而非包装他人。动机不是炫技而是**确定性**：自研客户端输出确定、行为可预测、错误模型统一。配套纪律是诚实裁剪：**不支持的能力明确抛 `ProtocolError('unsupported')`，绝不静默降级或"尽量支持"**（已裁剪清单见 `docs/db-clients-plan.md`）。
+
+**③ 消灭样板。** 框架的每一层都在消灭一类样板代码：
+
+| 样板 | 消灭方式 |
+|---|---|
+| 构建样板 | 动态编译（`ctx.ui.js` / `weifuwu/dev`），改代码即刷即用，零构建步骤 |
+| 样式样板 | 语义原语 + 变量定制，零自定义 CSS 文件（`--wf-brand-500` 改一层值全站跟随） |
+| 数据样板 | `ctx.data.get` 一个 API 覆盖 SSR 预取 / hydration 命中 / SPA fetch，写数据像写同步代码 |
+| 协议样板 | 自研 PG/Redis 客户端消灭双重编码、parseRow 样板、`'EX'` 参数顺序陷阱 |
+
+### 技术原则（哲学的展开）
+
 **零运行时依赖** — 前端无 npm 运行时依赖（自研 VDOM，不引入 Virtual DOM 库、rxjs、immer 等）。后端仅依赖 `esbuild`（TSX→JS 编译）+ `graphql` + `ws`（语言/协议本身）——**数据库客户端（PostgreSQL/Redis 协议）、GraphQL schema 工具全部自研**。esbuild 作为运行时依赖随 `npm install weifuwu` 自动安装，`ctx.ui.js()` 开箱即用。
 
-**两阶段组件模型** — 组件 = `(initProps, ctx) => (props) => VNode`。外层函数只执行一次（mount），内层函数每次状态/props 变化时执行（render）。无 class、无 `this`、无 Hook。
+**两阶段组件模型** — 组件 = `(initProps, ctx) => (props) => VNode`。外层函数只执行一次（mount），内层函数每次状态/props 变化时执行（render）。无 class、无 `this`、无 Hook——**位置即语义**：外层天生只跑一次，没有 hooks 规则、没有依赖数组、没有闭包陷阱（详解见[核心概念](#核心概念)）。
 
-**Proxy 驱动渲染** — `ctx.ui.$()` 返回深度 Proxy，`$.x = val` 自动触发当前组件的 VDOM patch。也支持手动 `ctx.ui.render()` 精确控制渲染时机。无需手动调用 `useState`/`useEffect`。
+**Proxy 驱动渲染** — `ctx.ui.$()` 返回深度 Proxy，`$.x = val` 自动触发当前组件的 VDOM patch；也支持手动 `ctx.ui.render()` 精确控制渲染时机。**组件库手动优先、业务层自动优先**——同一框架内按角色选模式（详见[组件库](#组件库-weifuwucomponents)）。
 
-**中间件注入一切** — 后端和前端共用同一理念：中间件向 `ctx` 注入能力（`ctx.sql` / `ctx.redis` / `ctx.api` / `ctx.auth` / `ctx.i18n` 等），Handler/组件从 `ctx` 读取。
+**中间件注入一切** — 后端和前端共用同一理念：中间件向 `ctx` 注入能力（`ctx.sql` / `ctx.redis` / `ctx.api` / `ctx.auth` / `ctx.i18n` / `ctx.limit` / `ctx.email` / `ctx.queue` / `ctx.ai` 等），Handler/组件从 `ctx` 读取。
 
-**自研数据层** — `ctx.sql`（PG v3 协议）与 `ctx.redis`（RESP2 协议）为**自研客户端**：确定性输出、行为可预测、统一错误模型。jsonb 自动解码、TTL 安全 API、schema 写前校验——高频痛点（双重编码/parseRow 样板/`'EX'` 参数顺序）从根上消除。
+**async 工厂组件** — `async (ctx) => (initProps, ctx) => (props) => VNode`：工厂层声明数据（`await ctx.data.get`）、mount 初始化状态（`$`）、render 输出视图。异步只在工厂边界，mount/render 保持同步；数据经闭包注入，写数据像写同步代码。三条纪律见[核心概念 · async 组件](#核心概念)。
+
+**SPA/SSR/Hydration 统一透明** — 同一份路由定义（`routes`）一个组件三场景自动适配：后端 `uiSsr({ routes })` 匹配即自动 SSR（完整 HTML + `__DATA__`），客户端 `router({ routes })` + `RouteView` + `mount(..., { hydrate: true })` 按 URL 同源匹配并收养服务端 HTML（不重建、无闪跳）。`ctx.data.get` 一个 API：SSR 预取 / hydration 命中（不重复请求）/ SPA 触发 fetch。服务端直接用 `.tsx`（`weifuwu/dev` Node loader），前后端同一 JSX 运行时。
 
-**SSR + 动态编译** — 后端 `ctx.ui.js()` 用 esbuild 实时编译 TSX，开发时改代码即刷即用，零构建步骤。
+**AI 是一等公民** — 自研 OpenAI 兼容协议（`docs/ai-contract.md`）+ 零依赖流式客户端 + agent 工具循环 + HITL 人工审批。`ctx.ai` 一个入口：`chat()` / `stream()` / `agent()` / `approve()`，不用 ai-sdk。
 
-**async 工厂组件** — `async (ctx) => (initProps, ctx) => (props) => VNode`：工厂层声明数据（`await ctx.data.get`）、mount 初始化状态（`$`）、render 输出视图。异步只在工厂边界，mount/render 保持同步；数据经闭包注入，写数据像写同步代码。
+**SaaS 地基随包内置** — rateLimit（限流）/ email（邮件）/ userSystem（用户认证）/ queue（可靠队列）以中间件形态随包提供，`app.use(...)` 一行接入（详见文末[SaaS 地基模块](#saas-地基模块ratelimit--email--usersystem--queue)）。
 
-**SPA/SSR/Hydration 统一透明** — 同一份路由定义（`routes`）一个组件形态三场景自动适配：后端 `uiSsr({ routes })` 匹配即自动 SSR（完整 HTML + `__DATA__`），客户端 `router({ routes })` + `RouteView` + `mount(..., { hydrate: true })` 按 URL 同源匹配并收养服务端 HTML（不重建、无闪跳）。`ctx.data.get` 一个 API：SSR 预取 / hydration 命中（不重复请求）/ SPA 触发 fetch。服务端直接用 `.tsx`（`weifuwu/dev` Node loader），前后端同一 JSX 运行时。
+**零自定义 CSS 设计系统** — 一个 CSS 文件 = 双层 Token + 布局原语 + 工具类 + 组件样式。业务页面不写 style.css：组件 + `wf-*` 原语写业务，品牌/组件定制改变量（`--wf-brand-500` / `--wf-btn-radius`），暗色自动（详见[布局系统](#布局系统-weifuwulayout)）。
+
+**自研数据层** — `ctx.sql`（PG v3 协议）与 `ctx.redis`（RESP2 协议）为**自研客户端**：确定性输出、行为可预测、统一错误模型。jsonb 自动解码、TTL 安全 API、schema 写前校验——高频痛点（双重编码/parseRow 样板/`'EX'` 参数顺序）从根上消除。
 
 ---
 
@@ -211,8 +236,8 @@ createApp().use(router({ routes })).mount('#root', RouteView, { hydrate: true })
 | 资源 | CDN 地址 | 说明 |
 |------|---------|------|
 | `weifuwu/client` | `https://unpkg.com/weifuwu@latest/dist/client/index.js` | 客户端核心（createApp, h, 路由, 状态管理等） |
-| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 43 个 UI 组件（Button, Card, Table, Modal 等） |
-| 组件样式 | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 91 个主题 Token + 35 个布局原语 |
+| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 46 个 UI 组件（Button, Card, Table, Modal 等） |
+| 组件样式 | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 115 个主题 Token + 67 个布局原语 |
 | 独立布局系统 | `https://unpkg.com/weifuwu@latest/dist/layout/weifuwu-layout.css` | 仅 CSS 布局，不依赖 JS |
 
 
@@ -243,15 +268,15 @@ createApp().use(router({ routes })).mount('#root', RouteView, { hydrate: true })
 | Router 方法 | **app.graphql()** | GraphQL 端点（支持 GraphiQL），Router 实例方法（无需单独 import） | Router |
 | `weifuwu/client` | **createApp** | 应用引导 + VDOM 渲染引擎 | — |
 | `weifuwu/client` | **router / RouteView** | 前端路由（history/hash 模式） | createApp |
-| `weifuwu/client` | **asyncComponent** | async 工厂组件（形态 C）：工厂层声明数据，mount/render 同步 | — |
+| `weifuwu/client` | **asyncComponent** | async 工厂组件：工厂层声明数据，mount/render 同步（三条纪律见[核心概念](#核心概念)） | — |
 | `weifuwu/client` | **ctx.data** | 数据管道：SSR 预取 / hydration 命中 / SPA fetch（`ctx.data.get`） | createApp |
 | `weifuwu/client` | **api / auth / ws** | HTTP 客户端 / 认证 / WebSocket 中间件 | createApp |
 | `weifuwu/client` | **i18n** | 国际化中间件（运行时切换语言） | createApp |
 | `weifuwu/client` | **ErrorBoundary** | 错误边界组件 | createApp |
 | `weifuwu/client` | **lockScroll/trapFocus** | 滚动锁定 / 焦点陷阱工具 | — |
 | `weifuwu/client` | **popup** | 弹层 fixed 定位工具（`computeFixedPos` / `computeFixedPosRect`） | — |
-| `weifuwu/components` | **43 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/client |
-| `weifuwu/layout` | **CSS 布局** | 35 个布局原语 + 91 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
+| `weifuwu/components` | **46 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/client |
+| `weifuwu/layout` | **CSS 布局** | 67 个布局原语 + 115 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
 
 ---
 
@@ -298,6 +323,49 @@ const Counter = (_init, ctx) => {
 | 读取 | handler 读取 ctx | 组件读取 ctx |
 | 渲染 | 返回 Response | `ctx.ui.render()` / `ctx.ui.dirty()` / `$.x = val` 触发局部 VDOM patch |
 
+### async 组件（三条纪律）
+
+`asyncComponent` 让"拿数据渲染页面"像写同步代码——三层结构：**工厂**（async，只执行一次，声明数据）→ **mount**（初始化 `$`）→ **render**（输出视图）。异步只在工厂边界：
+
+```tsx
+const UserProfile = asyncComponent(async (ctx) => {
+  const user = await ctx.data.get(`/api/user/${ctx.params.id}`)   // ① 工厂层：声明数据
+  return (_init, ctx) => {
+    const $ = ctx.ui.$()
+    $.liked = false                                               // ② mount：客户端状态
+    return (props) =>
+      h('div', {},
+        h('p', {}, user.name),          // 服务端状态（闭包，SSR 进 HTML）
+        h('button', { onClick: () => $.liked = !$.liked }, $.liked ? '❤️' : '🤍'))
+  }
+})
+```
+
+**三条纪律**（不遵守就是隐性 bug）：
+
+| 纪律 | 反例 | 正确 |
+|---|---|---|
+| ① 数据 key 必须含维度 | `ctx.data.get('/api/user')`——`/users/1 → /users/2` 导航命中旧缓存 | `ctx.data.get(\`/api/user/${ctx.params.id}\`)` |
+| ② 会变的数据放 `$` | `const count = data.count`——点击永不更新 | `$.count = data.count`（初始值 seed 自服务端数据） |
+| ③ 初始状态必须确定性 | `$.w = window.innerWidth`——SSR/hydration mismatch | 用服务端数据 seed，交互后再测 |
+
+**常见坑**：
+- 工厂**拿不到 props**——数据维度从 `ctx.params` / `ctx.data` 取
+- 闭包数据是页面加载时的**快照**——路由参数变化靠工厂重跑刷新（key 变 → 缓存 miss → 重新取数）；工厂缓存绑定页面上下文，路由导航/登录登出时自动失效
+- **个性化数据不进 `ctx.data`**——SSR 会把工厂取数结果序列化给所有客户端，会话/用户相关数据留在 `$` + fetch
+
+### 渲染策略：SPA 还是 SSR？
+
+组件与路由的写法**完全一样**，差异只有入口两行：
+
+| | SPA | SSR + Hydration |
+|---|---|---|
+| 适用 | 应用页（后台、工具、Dashboard） | 内容页（博客、营销，需要 SEO/首屏） |
+| 后端 | HTML 外壳 | `uiSsr({ routes })` 一行（自动完整 HTML + `__DATA__`） |
+| 客户端 | `mount('#root', RouteView)` | `mount('#root', RouteView, { hydrate: true })` |
+
+**怎么选**：默认 SPA；需要 SEO 或首屏即内容时用 SSR。两种模式可混合——一个 app 内 `uiSsr` 匹配共享路由，未匹配 `next()` 走普通 handler。
+
 ### Closeable 接口
 
 所有有状态模块（postgres、redis）实现 `close(): Promise<void>`，serve 关闭时自动调用。
@@ -1651,7 +1719,7 @@ const UserProfile: Component = (initProps, ctx) => {
 }
 ```
 
-### asyncComponent 工厂（形态 C）— 同步式数据声明
+### asyncComponent 工厂（async 组件）— 同步式数据声明
 
 `async (ctx) => (initProps, ctx) => (props) => VNode` — 工厂层（async，只执行一次并缓存）声明数据/加载代码，mount/render 保持同步。数据经闭包注入组件，渲染无 loading 分支：
 
@@ -2148,11 +2216,11 @@ import type { RouterOptions } from 'weifuwu/client'
 
 # 组件库 (`weifuwu/components`)
 
-43 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
+46 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
 
 ```ts
 import { Button, Input, Table, Modal, Toast } from 'weifuwu/components'
-import 'weifuwu/components/style.css'   // 包含 Token + 35 布局原语 + 组件样式，一次性引入
+import 'weifuwu/components/style.css'   // 包含 Token + 67 布局原语 + 组件样式，一次性引入
 ```
 
 ### 使用示例
@@ -2381,7 +2449,9 @@ props 变化 ──────────────────────
 
 # 布局系统 (`weifuwu/layout`)
 
-纯 CSS 布局原语 + 91 个主题 Token。不绑定任何 JS 框架。
+纯 CSS 布局原语 + 工具类 + 115 个主题 Token。不绑定任何 JS 框架。
+
+> **学习路径与命名规范**：见 [`docs/style-guide.md`](./docs/style-guide.md)——统一语法 `wf-<域>-<名>`、三档学习（组件 → 10 核心原语 → 完整速查）、场景速查、变量定制。
 
 > **全栈 weifuwu 项目**：`weifuwu/components/style.css` 已包含布局系统，一条 import 就够了，无需单独引用本页。
 > 本页仅适用于**非 weifuwu 项目**或**只需 CSS 布局**的场景。
@@ -2401,9 +2471,8 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 ```
 
 也支持相对路径：`ctx.ui.css('./src/style.css')`。
-```
 
-## 35 个布局原语
+## 67 个布局原语
 
 | 类别 | 原语 | 效果 |
 |------|------|------|
@@ -2440,13 +2509,56 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 | | `wf-inline` | display: inline |
 | | `wf-inline-block` | display: inline-block |
 | | `wf-contents` | display: contents |
-
-## 91 个主题 Token
+| **间距** | `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` | 多行截断 |
+
+## 115 个主题 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-secondary / --wf-color-secondary-bg
 
 /* 语义色 */
 --wf-color-success / --wf-color-success-bg
@@ -2496,6 +2608,9 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 --wf-accent-color / --wf-caret-color
 --wf-opacity-disabled / --wf-opacity-overlay
 --wf-pop-z / --wf-cover-z
+
+/* 应用外壳 */
+--wf-sidebar-width
 ```
 
 ### 暗色模式
@@ -2511,10 +2626,64 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 // 系统为暗色时自动生效；加 data-theme="light" 可强制亮色
 ```
 
+暗色值定义在原始层 `--wf-dark-*`（只写一次），`_dark.css` 两段仅做语义映射——改暗色调校只动原始层，无硬编码色值。
+
 ---
 
 # 样式定制指南
 
+## 组件定制钩子（零覆盖 CSS）
+
+关键组件视觉全部变量化——定制只需设一个变量（默认值 = 现有 token）：
+
+```html
+<style>
+  :root {
+    --wf-brand-500: #7c3aed;      /* 品牌换色：改原始层一个值，全站跟随 */
+    --wf-dark-brand-500: #a78bfa; /* 暗色品牌（可选） */
+    --wf-modal-width: 640px;      /* 组件定制：设一个变量 */
+    --wf-btn-radius: 999px;
+    --wf-field-height: 44px;
+    --wf-card-shadow: 0 8px 24px rgba(0,0,0,.12);
+  }
+</style>
+```
+
+钩子清单：`--wf-btn-*` `--wf-card-*` `--wf-field-*` `--wf-modal-*` `--wf-drawer-width` `--wf-toast-*` `--wf-alert-radius` `--wf-badge-radius` `--wf-tag-radius` `--wf-switch-radius` `--wf-popover-*` `--wf-tooltip-radius` `--wf-dropdown-min-width` `--wf-datepicker-*`。
+
+**覆盖优先级（@layer）**：`@layer tokens, base, layout, utilities, components`——你写的未分层 CSS 天然最高优先级；也可用 `@layer utilities` 精准覆盖我们。
+
+## 零自定义 CSS 模式（推荐）
+
+一个项目只需要引用**一个 CSS 文件**（`weifuwu/components/style.css`，内含 Token + 布局原语 + 组件样式），
+业务代码全部由组件 + `wf-*` 原语承担，**不需要再写 `style.css`**：
+
+```tsx
+// 组件 → 页面功能块；wf-* 原语 → 块之间的空间关系；--wf-* → 业务色值
+<PageHeader title="仪表盘" sub="欢迎回来">
+  <Button variant="primary">+ 新建</Button>
+</PageHeader>
+<div class="wf-row wf-gap-lg">
+  <StatCard label="总用户" value="1,234" trend="up" trendLabel="12%" />
+</div>
+```
+
+主题定制（品牌色/圆角/字体）不需要独立文件——**内联在 HTML 的 `<style>` 里即可**：
+
+```html
+<style>
+  :root {
+    --wf-color-primary: #6366f1;
+    --wf-radius: 8px;
+  }
+</style>
+```
+
+完整的零样式示例：`apps/weifuwu-demo`（一个页面 = 组件 + 原语，无 style.css）。
+
+诚实例外（合理场景，仍可内联 `<style>` 解决）：打印/PDF 导出规则、第三方库宿主样式、
+业务特有的一次性视觉（如色板选择器交互）。
+
 ## 全局主题变量
 
 所有组件引用 `--wf-*` CSS 变量。在根元素覆盖即可定制主题：

package/dist/components/Avatar/Avatar.d.ts

@@ -3,5 +3,7 @@ export interface AvatarProps {
     name?: string;
     src?: string;
     size?: 'sm' | 'md' | 'lg';
+    /** 指定背景色（覆盖按名字哈希的颜色），如按类型着色：user=蓝 / ai=紫 */
+    color?: string;
 }
 export declare const Avatar: Component<AvatarProps>;

package/dist/components/Card/Card.d.ts

@@ -3,6 +3,10 @@ export interface CardProps {
     variant?: 'default' | 'outlined';
     padding?: 'sm' | 'md' | 'lg';
     clickable?: boolean;
+    /** hover 抬升（阴影 + 上移），适合可点击/可悬停的卡片 */
+    hover?: boolean;
+    /** 选中态（边框高亮 + 品牌浅底），适合选择卡片 */
+    active?: boolean;
     onClick?: () => void;
     children?: any;
 }

package/dist/components/Input/Input.d.ts

@@ -9,6 +9,8 @@ export interface InputProps {
     disabled?: boolean;
     error?: string;
     hint?: string;
+    /** 边框变体：borderless 用于可编辑标题/内联编辑（hover/focus 才显边框） */
+    variant?: 'default' | 'borderless';
     onInput?: (e: Event) => void;
     onChange?: (e: Event) => void;
 }

package/dist/components/SegmentedControl/SegmentedControl.d.ts

@@ -0,0 +1,22 @@
+import type { Component } from '../../client/vnode.ts';
+export interface SegmentedOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+export interface SegmentedControlProps {
+    /** 选项列表（label 可为字符串或任意 VNode） */
+    options: SegmentedOption[];
+    /** 当前选中值 */
+    value?: string;
+    onChange?: (value: string) => void;
+    size?: 'sm' | 'md';
+    /** 撑满父容器宽度（选项等分） */
+    block?: boolean;
+    ariaLabel?: string;
+}
+/**
+ * 分段控件 — 单选切换（模式切换 / 状态筛选 / 模板选择）
+ * 语义：toggle group（aria-pressed），键盘 focus-visible 可见
+ */
+export declare const SegmentedControl: Component<SegmentedControlProps>;

package/dist/components/StatCard/StatCard.d.ts

@@ -5,5 +5,7 @@ export interface StatCardProps {
     trend?: 'up' | 'down';
     trendLabel?: string;
     icon?: string;
+    /** 点击跳转/交互（悬停抬升 + role=button） */
+    onClick?: () => void;
 }
 export declare const StatCard: Component<StatCardProps>;

package/dist/components/Textarea/Textarea.d.ts

@@ -8,6 +8,10 @@ export interface TextareaProps {
     error?: string;
     hint?: string;
     rows?: number;
+    /** 最大字符数（同时限制输入） */
+    maxLength?: number;
+    /** 显示字数统计（右下角；配合受控 value 实时更新） */
+    showCount?: boolean;
     onInput?: (e: Event) => void;
 }
 export declare const Textarea: Component<TextareaProps>;

package/dist/components/index.d.ts

@@ -59,6 +59,8 @@ export { Slider } from './Slider/Slider.ts';
 export type { SliderProps } from './Slider/Slider.ts';
 export { SearchInput } from './SearchInput/SearchInput.ts';
 export type { SearchInputProps } from './SearchInput/SearchInput.ts';
+export { SegmentedControl } from './SegmentedControl/SegmentedControl.ts';
+export type { SegmentedControlProps, SegmentedOption } from './SegmentedControl/SegmentedControl.ts';
 export { ProgressBar } from './ProgressBar/ProgressBar.ts';
 export type { ProgressBarProps } from './ProgressBar/ProgressBar.ts';
 export { Accordion } from './Accordion/Accordion.ts';

package/dist/components/index.js

@@ -52,9 +52,9 @@ var Button = (_init, ctx) => (props) => {
 
 // src/components/Input/Input.ts
 var Input = (_init) => (props) => {
-  const { label, name, type = "text", value, placeholder, required, disabled, error, hint, onInput, onChange } = props;
+  const { label, name, type = "text", value, placeholder, required, disabled, error, hint, variant = "default", onInput, onChange } = props;
   const inputEl = h("input", {
-    class: "wf-input",
+    class: `wf-input${variant === "borderless" ? " wf-input--borderless" : ""}`,
     name: name || void 0,
     type,
     value: value ?? "",
@@ -79,7 +79,7 @@ var Input = (_init) => (props) => {
 
 // src/components/Textarea/Textarea.ts
 var Textarea = (_init, _ctx) => (props) => {
-  const { label, value, placeholder, required, disabled, error, hint, rows = 3, onInput } = props;
+  const { label, value, placeholder, required, disabled, error, hint, rows = 3, maxLength, showCount, onInput } = props;
   const textareaEl = h("textarea", {
     class: "wf-textarea",
     value: value ?? "",
@@ -87,6 +87,7 @@ var Textarea = (_init, _ctx) => (props) => {
     required: required || void 0,
     disabled: disabled || void 0,
     rows,
+    maxLength,
     onInput
   });
   const children = [];
@@ -96,6 +97,14 @@ var Textarea = (_init, _ctx) => (props) => {
     children.push(h("label", { class: "wf-textarea-label" }, labelContent));
   }
   children.push(textareaEl);
+  if (showCount) {
+    const len = (value ?? "").length;
+    const over = maxLength != null && len > maxLength;
+    children.push(h("div", {
+      class: `wf-textarea-count${over ? " wf-textarea-count--over" : ""}`,
+      "aria-live": "polite"
+    }, maxLength != null ? `${len}/${maxLength}` : String(len)));
+  }
   if (error) children.push(h("div", { class: "wf-textarea-err" }, error));
   if (hint && !error) children.push(h("div", { class: "wf-textarea-hint" }, hint));
   return h("div", { class: `wf-textarea-wrap${error ? " wf-textarea--err" : ""}` }, children);
@@ -1059,12 +1068,14 @@ function getPageRange(current, total) {
 
 // src/components/Card/Card.ts
 var Card = (_init, _ctx) => (props) => {
-  const { variant = "default", padding = "md", clickable, onClick, children } = props;
+  const { variant = "default", padding = "md", clickable, hover, active, onClick, children } = props;
   const cls = [
     "wf-card",
     `wf-card--${variant}`,
     `wf-card--pad-${padding}`,
-    clickable && "wf-card--clickable"
+    clickable && "wf-card--clickable",
+    hover && "wf-card--hover",
+    active && "wf-card--active"
   ].filter(Boolean).join(" ");
   return h("div", { class: cls, onClick, role: clickable ? "button" : void 0, tabindex: clickable ? 0 : void 0 }, children);
 };
@@ -1086,7 +1097,7 @@ function hashColor(name) {
   return COLORS[Math.abs(hash) % COLORS.length];
 }
 var Avatar = (_init, _ctx) => (props) => {
-  const { name = "", src, size = "md" } = props;
+  const { name = "", src, size = "md", color } = props;
   const initial = name.trim()[0]?.toUpperCase() ?? "?";
   if (src) {
     return h("img", {
@@ -1097,7 +1108,7 @@ var Avatar = (_init, _ctx) => (props) => {
   }
   return h("div", {
     class: `wf-avatar wf-avatar--${size}`,
-    style: { background: hashColor(name) }
+    style: { background: color ?? hashColor(name) }
   }, initial);
 };
 
@@ -1113,7 +1124,7 @@ var Tag = (_init, _ctx) => (props) => {
 
 // src/components/StatCard/StatCard.ts
 var StatCard = (_init, _ctx) => (props) => {
-  const { label, value, trend, trendLabel, icon } = props;
+  const { label, value, trend, trendLabel, icon, onClick } = props;
   const children = [];
   if (icon) children.push(h("div", { class: "wf-stat-icon" }, icon));
   children.push(h("div", { class: "wf-stat-value" }, String(value)));
@@ -1126,7 +1137,12 @@ var StatCard = (_init, _ctx) => (props) => {
       trendLabel ? h("span", { class: "wf-stat-trend-label" }, trendLabel) : null
     ].filter(Boolean)));
   }
-  return h("div", { class: "wf-stat" }, children);
+  return h("div", {
+    class: `wf-stat${onClick ? " wf-stat--clickable" : ""}`,
+    onClick,
+    role: onClick ? "button" : void 0,
+    tabindex: onClick ? 0 : void 0
+  }, children);
 };
 
 // src/components/Steps/Steps.ts
@@ -1279,6 +1295,27 @@ var SearchInput = (_init, _ctx) => (props) => {
   ].filter(Boolean));
 };
 
+// src/components/SegmentedControl/SegmentedControl.ts
+var SegmentedControl = (_init, _ctx) => (props) => {
+  const { options, value, onChange, size = "md", block, ariaLabel } = props;
+  const cls = [
+    "wf-segmented",
+    size === "sm" && "wf-segmented--sm",
+    block && "wf-segmented--block"
+  ].filter(Boolean).join(" ");
+  return h(
+    "div",
+    { class: cls, role: "group", "aria-label": ariaLabel },
+    options.map((opt) => h("button", {
+      type: "button",
+      class: `wf-segmented-option${opt.value === value ? " wf-segmented-option--active" : ""}`,
+      "aria-pressed": opt.value === value ? "true" : "false",
+      disabled: opt.disabled || void 0,
+      onClick: opt.disabled ? void 0 : () => onChange?.(opt.value)
+    }, opt.label))
+  );
+};
+
 // src/components/ProgressBar/ProgressBar.ts
 var ProgressBar = (_init, ctx) => (props) => {
   const { value = 0, max = 100, label, showValue } = props;
@@ -3200,6 +3237,7 @@ export {
   ProgressBar,
   RadioGroup,
   SearchInput,
+  SegmentedControl,
   Select,
   Skeleton,
   Slider,