weifuwu 0.86.0 → 0.87.0

package/dist/{ui → server/ui}/index.d.ts

@@ -26,8 +26,8 @@
  * ```
  */
 import type { Middleware } from '../types.ts';
-import type { Component } from '../ui-dom/vnode.ts';
-declare module '../types.ts' {
+import type { Component } from '../../client/vdom/index.ts';
+declare module '../../server/types.ts' {
     interface Context {
         ui: {
             /** Tagged template → HTML Response */

package/dist/{user → server/user}/token.d.ts

@@ -2,7 +2,7 @@
  * 会话令牌（零依赖，node:crypto）
  *
  * access token：HMAC-SHA256 签名的 JWT 形态（base64url），
- *   与 weifuwu/ui-dom 的 auth() 兼容（客户端解码 payload 检查 exp）。
+ *   与 weifuwu/vdom 的 auth() 兼容（客户端解码 payload 检查 exp）。
  * refresh token：不透明随机串（256-bit），DB 只存 SHA-256 哈希（可撤销）。
  */
 /** 签发 JWT access token（HS256） */

package/dist/shared/router/trie.d.ts

@@ -0,0 +1,61 @@
+/**
+ * weifuwu shared — Trie 路径匹配核心（前后端共用——零 HTTP 依赖）
+ *
+ * 来源：后端 Router（src/server/core/router.ts）的 Trie 匹配逻辑抽离——
+ * 真实事故语义保留：
+ * - **静态段优先** → :param → * 通配（O(path_segments) 匹配——确定性——
+ *   注册序优先静态）
+ * - **param 冲突检查**：同一位置 :id 与 :name 并存抛错（不静默）
+ * - **通配独立槽**：精确 value 与通配 value 互不覆盖（showcase SSR 事故——
+ *   '/' + '/*' 并存时通配曾抢先精确 handler）
+ * - **根路径 '/'**：splitPath 过滤空段返回 []——value 绑 root 节点
+ *
+ * 泛型 value：后端 = method 表（{ handlers, middlewares }）；前端 = 页面
+ * handler。匹配返回 { value, params }——params 注入由调用方决定
+ * （后端 ctx/前端 req）。
+ */
+/** 泛型 Trie 节点 */
+export interface TrieNode<T> {
+    children: Map<string, TrieNode<T>>;
+    /** 参数段名（:id → 'id'——该子节点是参数槽） */
+    param?: string;
+    /** 通配段（*——匹配剩余任意段） */
+    wildcard?: boolean;
+    /** 精确路径 value（路径完全匹配） */
+    value?: T;
+    /** 通配路径 value（独立槽——不被精确覆盖；反之亦然） */
+    wildcardValue?: T;
+}
+export declare function createTrie<T>(): TrieNode<T>;
+/** 路径分段（'/a/b' → ['a','b']——空段过滤——根路径 '/' → []） */
+export declare function splitPath(path: string): string[];
+/**
+ * 查找路径终点节点（不含通配语义——用于冲突检查/多方法合并）——
+ * 遇 '*' 段返回当前节点（通配槽）；未注册路径返回 null。
+ *
+ * **精确匹配纪律（真实事故——agent-platform 沙盒路由）**：静态段只匹配
+ * 静态子节点——参数段（:xxx）只匹配参数槽。此前静态段用 `children.get(':')`
+ * 兜底——`:id/debug` 会命中 `:id/:action` 参数槽（children key ':'）——
+ * 冲突检查返回 POST action 节点——value.handlers.set('GET', debugHandler)
+ * **污染共享 value**（GET 写进 POST action 的 handlers）——后续
+ * `:id/<静态段>`（processes/stats）注册时再次命中 action 槽——误报
+ * `route conflict already registered`。
+ */
+export declare function trieFind<T>(root: TrieNode<T>, path: string): TrieNode<T> | null;
+/**
+ * 注册（path → value）——分段插入：
+ * '/'（空段）→ value 绑 root；'*' 结尾 → wildcardValue（独立槽）；
+ * 其余逐段 getOrCreateChild——终点绑 value。返回终点节点（冲突检查）。
+ */
+export declare function trieRegister<T>(root: TrieNode<T>, path: string, value: T, isWildcardValue?: boolean): TrieNode<T>;
+/**
+ * 匹配（segments → { value, params, wildcard } | null）：
+ * 精确优先（静态 → :param 逐段）——段失败或终端无 value → 通配兜底
+ * （从 root 沿路径检查任意前缀深度的通配注册——params['*'] = 剩余段）；
+ * 精确命中且节点有通配槽（'/' + '/*' 并存）→ params['*'] = ''（精确优先标记）。
+ */
+export declare function trieMatch<T>(root: TrieNode<T>, segments: string[]): {
+    value: T;
+    params: Record<string, string>;
+    wildcard: boolean;
+} | null;

package/docs/components-map.md

@@ -25,7 +25,7 @@
 | 标签页 | `<Tabs items active onChange>`（方向键 + 移动端横向滚动） | Tabs | Tabs | Tabs | 等价 |
 | 分页 | `<Pagination total page onChange>`（页码折叠 + 移动端 44px） | Pagination | Pagination | Pagination | 等价 |
 | 步骤条 | `<Steps items current>` | Steps | Steps | — | 等价 |
-| 下拉菜单 | `<Dropdown items>`（danger variant） | Dropdown | Dropdown | DropdownMenu | 等价（usePopup：外部点击/Escape 关闭） |
+| 下拉菜单 | `<Dropdown items>`（danger variant） | Dropdown | Dropdown | DropdownMenu | 等价（openPopup：外部点击/Escape 关闭） |
 | 水平菜单栏 | `<Menubar menus>`（←→↓ 键盘 + 触屏） | Menu 水平 | Menu | Menubar | 等价 |
 | 页面标题 | `<PageHeader title sub>` | PageHeader（v5 移除） | PageHeader | — | weifuwu 保留独立组件 |
 | 回到顶部 | `<BackTop threshold>` | FloatButton / BackTop | Backtop | — | 滚动超阈值显示 |
@@ -89,8 +89,8 @@
 | 模态框 | `<Modal open title onClose width>` | Modal | Dialog | Dialog | `open/onClose`（antd v5 同）；焦点 trap + 归还；移动端 bottom-sheet |
 | 确认框 | `<Confirm>` + `await confirm()` 命令式 | Popconfirm / Modal.confirm | Popconfirm / MessageBox | AlertDialog | 声明式 + 命令式双模式 |
 | 抽屉 | `<Drawer position="left\|right\|top\|bottom">` | Drawer | Drawer | Sheet / Drawer | **四方向覆盖 shadcn Sheet + Drawer**；移动端全宽 |
-| 气泡 | `<Popover position>`（视口夹紧） | Popover | Popover | Popover | 等价（usePopup：外部点击/Escape/tap 降级） |
-| 悬浮提示 | `<Tooltip content position>`（string） | Tooltip | Tooltip | Tooltip | usePopup：桌面 hover / 触屏 tap |
+| 气泡 | `<Popover position>`（视口夹紧） | Popover | Popover | Popover | 等价（openPopup：外部点击/Escape/tap 降级） |
+| 悬浮提示 | `<Tooltip content position>`（string） | Tooltip | Tooltip | Tooltip | openPopup：桌面 hover / 触屏 tap |
 | 悬停卡 | `<HoverCard content>`（富内容 + 延迟） | — | — | HoverCard | shadcn 对齐；触屏 tap |
 | 右键菜单 | `<ContextMenu items>` | Dropdown context | — | ContextMenu | 桌面右键 + **触屏长按**双通道 |
 | 消息 | `<Toast>` + `toast()` 命令式 | message | Message | Sonner | 命令式 `toast('已保存','success')` |
@@ -131,7 +131,7 @@
 ## 第十批：文件预览与 Office 编辑（2026-12——ODES 事件流）
 
 > 文档 = fold(事件流)：docx/xlsx/pptx ↔ ODES 模型（DocState/WorkbookState/DeckState）
-> 前端零依赖转换（自研 ZIP/XML + DecompressionStream）——详见 docs/components.md。
+> 前端零依赖转换（自研 ZIP/XML + DecompressionStream）——详见 content/guides/components-guide.md。
 
 | 组件 | 说明 |
 |------|------|
@@ -212,7 +212,7 @@
 | 组件 | 类型 | 三库等价 | 要点 |
 |------|------|---------|------|
 | **Layout**（+LayoutHeader/Sider/Content/Footer） | 新增 | antd Layout / EP Container / shadcn Sidebar | 复合子组件双模式；含 Sider → row 布局；Sider 折叠受控/非受控 + trigger |
-| **Popconfirm** | 新增 | antd / EP Popconfirm | 复用 usePopup 基座（弹层组合性）；danger 危险色；确认后自动关闭 |
+| **Popconfirm** | 新增 | antd / EP Popconfirm | openPopup 命令式弹窗；danger 危险色；确认后自动关闭 |
 | **AutoComplete** | 新增 | antd+EP Autocomplete / shadcn Combobox | 自由输入联想；包含过滤（纯函数）；键盘 ↓↑/Enter/Escape；选中回填；error 错误态 |
 | **Link** | 新增 | EP Link / antd Typography.Link | 语义色/下划线/disabled/new window/icon |
 | **FloatButton** | 新增 | antd FloatButton（特有） | fixed 定位 + badge + 组展开状态机 |

package/docs/style-guide.md

@@ -15,7 +15,7 @@ weifuwu 的设计语言与框架哲学同源（确定性、诚实裁剪、render
 | 4 | **专业** Instrumental | 面向 AI 应用/管理后台/数据工具：键盘可达、数据密度、三态完整 | 键盘焦点全局；compact 预设；加载/空/错误三态规范 |
 | 5 | **中文原生** CJK-Native | 字阶/行高/断行针对中文；表头不做 uppercase；数字防抖 | `--wf-heading-case: none`；`wf-nums`（tabular-nums） |
 
-主题配置三档（详见 [docs/styling.md](styling.md)）：**① 改 `--wf-brand-seed` 一个值换肤**（色阶 color-mix 自动派生，暗色自动跟随）→ **② `<html data-preset="minimal|compact|rounded">` 预设**（与 data-theme 正交）→ **③ 深度定制**（组件钩子 + @layer 覆盖）。
+主题配置三档（详见 [content/guides/styling.md](styling.md)）：**① 改 `--wf-brand-seed` 一个值换肤**（色阶 color-mix 自动派生，暗色自动跟随）→ **② `<html data-preset="minimal|compact|rounded">` 预设**（与 data-theme 正交）→ **③ 深度定制**（组件钩子 + @layer 覆盖）。
 
 ## 统一语法：`wf-<域>-<名字>`
 
@@ -157,6 +157,18 @@ wf-rounded-md     圆角
 
 完整钩子清单：`--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-*`。
 
+### 表面语言（微流明·边界即结构）
+
+静态卡片 = **1px 细边框**（`--wf-color-border`）——阴影仅用于抬升语义（hover/浮层/拖拽中）；卡片 hover 抬升用 `wf-elevate`。旧阴影观感可覆盖 `--wf-card-shadow` 恢复。浮层按层级用圆角矩阵：
+
+| 表面 | 圆角 | 底 | 说明 |
+|---|---|---|---|
+| Card / StatCard 默认 | --wf-radius-md (8) | bg | 细边框；阴影仅 hover（wf-elevate） |
+| Modal | **--wf-radius-lg (12)** | bg-elevated | 抬升语义 |
+| 面板族（dropdown/select/datepicker/popover） | --wf-field-radius | bg-elevated | 弹出面板 |
+| Tooltip / 小浮层 | --wf-radius-sm (4) | bg-elevated | 摘要层 |
+| Drawer | 0（贴边） | bg-elevated | 全幅侧拉 |
+
 ### 动效定制 — 时长/缓动/位移
 
 ```html
@@ -177,7 +189,7 @@ wf-rounded-md     圆角
 用户 @layer utilities 可精准盖过 weifuwu 的 utilities
 ```
 
-## 主题 Token（177 个，双层）
+## 主题 Token（182 个，双层）
 
 - **原始层**（`--wf-brand-*` `--wf-slate-*` `--wf-dark-*`）：色值只定义一次，品牌/暗色调校改这里
 - **语义层**（`--wf-color-*` `--wf-space-*` `--wf-radius-*` …）：组件消费，主题切换覆盖这里

package/examples/apps/admin/README.md

@@ -0,0 +1,23 @@
+# admin 应用模板（复制即用）
+
+```bash
+# 1. 安装依赖（weifuwu 包——含 content/ 离线文档 + examples/ 模板源码）
+npm i weifuwu
+
+# 2. 复制本目录到你的项目（或直接在 examples/apps/admin 内开发）
+# 3. 启动
+node server.ts    # → http://localhost:admin/3300 3301 3302 3303
+```
+
+## 改造指南
+
+见 `node_modules/weifuwu/content/apps/admin.md`（目录结构 + 逐步改造步骤）。
+
+## 结构
+
+| 文件 | 职责 |
+|------|------|
+| app.tsx | 前端：路由表 + 页面组件 + 状态 |
+| api.ts | 后端：API 注册函数（独立/嵌入共享） |
+| server.ts | 独立入口（MemorySql——生产换 postgres() 一行） |
+| main.tsx | 独立前端入口 |

package/examples/apps/admin/api.ts

@@ -0,0 +1,27 @@
+/**
+ * admin 后端 API——订单表（注册函数：独立 server 与 showcase 嵌入共享）
+ */
+import type { Router } from 'weifuwu'
+
+export function registerAdminApi(app: Router, sql: any): void {
+  app.get('/api/admin/orders', async () => {
+    const rows = await sql`SELECT * FROM admin_orders ORDER BY id DESC LIMIT 50`
+    return Response.json({ rows })
+  })
+}
+
+/** 建表 + 种子数据（独立/嵌入共用） */
+export async function ensureAdminTables(sql: any): Promise<void> {
+  await sql.unsafe('CREATE TABLE IF NOT EXISTS admin_orders (id serial PRIMARY KEY, customer text, amount numeric, status text, date text)')
+  const rows = await sql`SELECT COUNT(*) AS n FROM admin_orders`
+  if (Number(rows[0]?.n) > 0) return
+  const seed = [
+    ['张伟', 1280, 'paid', '2026-08-10'], ['李娜', 560, 'pending', '2026-08-11'],
+    ['王强', 3200, 'shipped', '2026-08-12'], ['赵敏', 890, 'paid', '2026-08-13'],
+    ['陈杰', 2100, 'pending', '2026-08-14'], ['刘洋', 450, 'paid', '2026-08-15'],
+    ['孙丽', 1750, 'shipped', '2026-08-16'], ['周涛', 980, 'paid', '2026-08-17'],
+  ]
+  for (const [customer, amount, status, date] of seed) {
+    await sql`INSERT INTO admin_orders (customer, amount, status, date) VALUES (${customer}, ${amount}, ${status}, ${date})`
+  }
+}

package/examples/apps/admin/app.tsx

@@ -0,0 +1,144 @@
+/**
+ * admin 应用模板——管理后台（AppShell + 多页 + 表格，完整全栈复制即用）
+ *
+ * 演示能力：
+ *   - Layout 组件骨架（Sider 折叠 + Header + Content）+ 路由 layout 包裹复用
+ *   - Table 排序 + StatCard KPI + 菜单导航（源于 agent-platform 架构提炼）
+ *   - 后端：MemorySql 订单表（api.ts 注册函数——独立/嵌入共享）
+ */
+import { UIRouter, uiServe, h, createStore, createClientBrowser } from 'weifuwu/vdom'
+import type { Component } from 'weifuwu/vdom'
+import { Layout, LayoutHeader, LayoutSider, LayoutContent, Menu, StatCard, Table, Badge, Tag, ThemeSwitch, PageHeader, EmptyState } from 'weifuwu/components'
+
+export interface Order { id: string; customer: string; amount: number; status: 'pending' | 'paid' | 'shipped'; date: string }
+
+export const adminStore = createStore<{ orders: Order[]; loading: boolean }>({ orders: [], loading: true })
+
+export async function loadOrders(): Promise<void> {
+  const res = await fetch('/api/admin/orders')
+  const data = await res.json()
+  adminStore.update((s) => { s.orders = data.rows; s.loading = false })
+}
+
+const statusTag = (s: Order['status']) =>
+  s === 'paid' ? <Tag variant="success">已支付</Tag> : s === 'shipped' ? <Tag variant="primary">已发货</Tag> : <Tag>待支付</Tag>
+
+/** 仪表盘页 */
+export const DashboardPage: Component = async (_init: any, ctx: any) => {
+  void loadOrders()
+  const state = ctx.ui.useExternal(adminStore)
+  const paid = state.orders.filter((o: Order) => o.status === 'paid' || o.status === 'shipped')
+  const total = state.orders.reduce((a: number, o: Order) => a + o.amount, 0)
+  return async (_p: any) => (
+    <div class="wf-stack wf-gap-md">
+      <PageHeader title="仪表盘" sub="KPI + 订单概览（数据来自 MemorySql）" />
+      <div class="wf-grid" style="--wf-cols:repeat(auto-fit,minmax(180px,1fr));--wf-gap:12px">
+        <StatCard label="订单总数" value={state.orders.length} />
+        <StatCard label="已支付/发货" value={paid.length} />
+        <StatCard label="销售总额" value={`¥${total.toLocaleString()}`} />
+        <StatCard label="待处理" value={state.orders.filter((o: Order) => o.status === 'pending').length} />
+      </div>
+      {state.loading ? <div class="wf-text-secondary">加载中…</div> : (
+        <Table
+          columns={[
+            { key: 'id', label: '订单号' },
+            { key: 'customer', label: '客户' },
+            { key: 'amount', label: '金额', sortable: true, render: (v: any) => `¥${Number(v).toLocaleString()}` },
+            { key: 'date', label: '日期' },
+            { key: 'status', label: '状态', render: (v: any) => statusTag(v) },
+          ]}
+          data={state.orders}
+         
+        />
+      )}
+    </div>
+  )
+}
+
+/** 订单页（全量表格 + 筛选） */
+export const OrdersPage: Component = async (_init: any, ctx: any) => {
+  void loadOrders()
+  const state = ctx.ui.useExternal(adminStore)
+  let q = ''
+  return async (_p: any) => {
+    const list = state.orders.filter((o: Order) => !q || o.customer.toLowerCase().includes(q.toLowerCase()) || o.id.includes(q))
+    return (
+      <div class="wf-stack wf-gap-md">
+        <PageHeader title="订单管理" sub={`共 ${list.length} 条`}>
+          <input class="wf-input" style="max-width:200px" placeholder="搜索客户/订单号…" value={q}
+            onInput={(e: any) => { q = (e.target as HTMLInputElement).value; ctx.render() }} />
+        </PageHeader>
+        {list.length === 0 && !state.loading ? <EmptyState text="无匹配订单" /> : (
+          <Table
+            columns={[
+              { key: 'id', label: '订单号' },
+              { key: 'customer', label: '客户', sortable: true },
+              { key: 'amount', label: '金额', sortable: true, render: (v: any) => `¥${Number(v).toLocaleString()}` },
+              { key: 'date', label: '日期' },
+              { key: 'status', label: '状态', render: (v: any) => statusTag(v) },
+            ]}
+            data={list}
+           
+          />
+        )}
+      </div>
+    )
+  }
+}
+
+// ── 路由（layout 包裹 = AppShell 复用——跨页保持侧栏/折叠状态） ──
+export const adminRoutes = [
+  { path: '/', render: () => h(DashboardPage, {}) },
+  { path: '/orders', render: () => h(OrdersPage, {}) },
+]
+
+const AppShell: Component = async (_init: any, ctx: any) => {
+  let collapsed = false
+  const current = () => location.hash.replace('#/', '') || '/'
+  return async (props: any) => (
+    <Layout style="min-height:420px;border:1px solid var(--wf-color-border);border-radius:8px;overflow:hidden">
+      <LayoutSider collapsed={collapsed} collapsible onCollapse={(c) => { collapsed = c; ctx.render() }} width={200}>
+        <div style={{ background: "var(--wf-color-bg-secondary)", height: "100%" }}>
+        <div class="wf-p-sm wf-text-bold" style="color:var(--wf-color-text)">⚙️ 管理后台</div>
+        <Menu
+          items={[
+            { key: '/', label: '仪表盘' },
+            { key: '/orders', label: '订单管理' },
+          ]}
+          activeKey={current()}
+          collapsible
+          collapsed={collapsed}
+          onCollapseChange={(c) => { collapsed = c; ctx.render() }}
+          onSelect={(k: string) => { location.hash = `#/${k === '/' ? '' : k}` }}
+        />
+        </div>
+      </LayoutSider>
+      <Layout>
+        <LayoutHeader style="display:flex;align-items:center;justify-content:flex-end;gap:8px">
+          <Badge variant="success">admin 模板</Badge>
+          <ThemeSwitch />
+        </LayoutHeader>
+        <LayoutContent style="padding:16px">{props.page}</LayoutContent>
+      </Layout>
+    </Layout>
+  )
+}
+
+export const adminAppShell = AppShell
+
+export function createAdminApp(root: HTMLElement, options?: { history?: boolean }): ReturnType<typeof uiServe> {
+  // vdom 规范面：UIRouter（Trie 匹配）+ uiServe（渲染落地）——布局共享
+  // （root 稳定——AppShell 包裹——精准路由切换）
+  const router = new UIRouter()
+  for (const r of adminRoutes) {
+    router.get(r.path, (req: Request, ctx: any) =>
+      (ctx as { stream: (v: unknown) => Response }).stream(h(AppShell, { page: r.render() })))
+  }
+  return uiServe(router, {
+    root,
+    browser: createClientBrowser()!,
+    ...(options?.history === false ? {} : {}),
+  })
+}
+
+export const pathFromHash = (): string => location.hash.replace(/^#/, '') || '/'

package/examples/apps/admin/main.tsx

@@ -0,0 +1,8 @@
+/**
+ * admin 独立入口——复制本目录即可运行：
+ *   cd examples/apps/admin && node server.ts → http://localhost:3302
+ */
+import { createAdminApp, pathFromHash } from './app.tsx'
+
+const sub = createAdminApp(document.querySelector('#root') as HTMLElement)
+window.addEventListener('hashchange', () => sub.navigate(pathFromHash()))

package/examples/apps/admin/server.ts

@@ -0,0 +1,37 @@
+/**
+ * admin 独立 server——MemorySql 订单表（生产换 postgres()）
+ *   cd examples/apps/admin && node server.ts → http://localhost:3302
+ */
+import { serve, Router, ui, createMemorySql } from 'weifuwu'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { registerAdminApi, ensureAdminTables } from './api.ts'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const sql = createMemorySql()
+await ensureAdminTables(sql)
+
+const app = new Router()
+app.use(ui())
+app.get('/app.js', (req, ctx) => ctx.ui.js(resolve(__dirname, 'main.tsx')))
+registerAdminApi(app, sql)
+
+app.get('/*', async (req, ctx) => ctx.ui.html`
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link rel="stylesheet" href="/components.css">
+  <title>admin 应用模板</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script src="/app.js"></script>
+</body>
+</html>
+`)
+app.get('/components.css', (req, ctx) => ctx.ui.css('weifuwu/components/style.css'))
+
+serve(app, { port: 3302 })
+console.log('admin 模板 → http://localhost:3302')

package/examples/apps/auth/README.md

@@ -0,0 +1,23 @@
+# auth 应用模板（复制即用）
+
+```bash
+# 1. 安装依赖（weifuwu 包——含 content/ 离线文档 + examples/ 模板源码）
+npm i weifuwu
+
+# 2. 复制本目录到你的项目（或直接在 examples/apps/auth 内开发）
+# 3. 启动
+node server.ts    # → http://localhost:auth/3300 3301 3302 3303
+```
+
+## 改造指南
+
+见 `node_modules/weifuwu/content/apps/auth.md`（目录结构 + 逐步改造步骤）。
+
+## 结构
+
+| 文件 | 职责 |
+|------|------|
+| app.tsx | 前端：路由表 + 页面组件 + 状态 |
+| api.ts | 后端：API 注册函数（独立/嵌入共享） |
+| server.ts | 独立入口（MemorySql——生产换 postgres() 一行） |
+| main.tsx | 独立前端入口 |

package/examples/apps/auth/api.ts

@@ -0,0 +1,49 @@
+/**
+ * auth 后端 API——内存用户表 + 会话（注册函数：独立 server 与 showcase 嵌入共享）
+ */
+import type { Router } from 'weifuwu'
+import { createMemorySql } from 'weifuwu'
+
+export interface AuthUser { id: string; email: string; name: string }
+
+export function registerAuthApi(app: Router, sql: any): void {
+  // 内存会话表（token → userId）——演示用；生产换 ctx.auth/userSystem
+  const sessions = new Map<string, string>()
+  let seq = 0
+
+  app.post('/api/auth/register', async (req: Request) => {
+    const { email, password, name } = await req.json()
+    if (!String(email ?? '').includes('@')) return Response.json({ ok: false, error: '邮箱格式无效' })
+    if (String(password ?? '').length < 6) return Response.json({ ok: false, error: '密码至少 6 位' })
+    const rows = await sql`INSERT INTO auth_users (email, password, name) VALUES (${String(email)}, ${String(password)}, ${String(name ?? email.split('@')[0])}) RETURNING id, email, name`
+    const user = rows[0]
+    const token = `tok_${++seq}_${user.id}`
+    sessions.set(token, String(user.id))
+    return Response.json({ ok: true, user, token }, { status: 201 })
+  })
+
+  app.post('/api/auth/login', async (req: Request) => {
+    const { email, password } = await req.json()
+    const rows = await sql`SELECT * FROM auth_users WHERE email = ${String(email)} AND password = ${String(password)}`
+    if (!rows.length) return Response.json({ ok: false, error: '邮箱或密码错误' }, { status: 401 })
+    const user = rows[0]
+    const token = `tok_${++seq}_${user.id}`
+    sessions.set(token, String(user.id))
+    return Response.json({ ok: true, user, token })
+  })
+
+  app.get('/api/auth/me', async (req: Request) => {
+    const auth = req.headers.get('authorization') ?? ''
+    const token = auth.replace('Bearer ', '')
+    const userId = sessions.get(token)
+    if (!userId) return Response.json({ ok: false }, { status: 401 })
+    const rows = await sql`SELECT id, email, name FROM auth_users WHERE id = ${userId}`
+    if (!rows.length) return Response.json({ ok: false }, { status: 401 })
+    return Response.json({ ok: true, user: rows[0] })
+  })
+}
+
+/** 建表（独立/嵌入共用） */
+export async function ensureAuthTables(sql: any): Promise<void> {
+  await sql.unsafe('CREATE TABLE IF NOT EXISTS auth_users (id serial PRIMARY KEY, email text UNIQUE, password text, name text)')
+}

package/examples/apps/auth/app.tsx

@@ -0,0 +1,137 @@
+/**
+ * auth 应用模板——登录/注册 → 受保护页 → 登出（完整全栈，复制即用）
+ *
+ * 演示能力：
+ *   - 应用级状态（createStore user）+ 路由守卫（未登录 → 登录页）
+ *   - 表单校验 + 提交 loading + 错误条（AuthPage 组件）
+ *   - 后端：内存用户表 + 会话（api.ts 注册函数——独立/嵌入共享）
+ *   - 会话持久化：ctx.browser.storage（浏览器纪律）
+ */
+import { UIRouter, uiServe, h, createStore, createClientBrowser } from 'weifuwu/vdom'
+import type { Component } from 'weifuwu/vdom'
+import { AuthPage, Input, Button, Alert, PageHeader, Avatar, Space } from 'weifuwu/components'
+
+export interface User { id: string; email: string; name: string }
+
+export const authStore = createStore<{ user: User | null; error: string | null }>({ user: null, error: null })
+
+async function api(browser: any, path: string, body: Record<string, string>): Promise<{ ok: boolean; user?: User; error?: string }> {
+  const token = browser.storageGet('auth:token')
+  const res = await fetch(path, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+    body: JSON.stringify(body),
+  })
+  return res.json()
+}
+
+/** 登录/注册页（AuthPage 组件——同一骨架两用） */
+const AuthFormPage = (mode: 'login' | 'register'): Component =>
+  async (_init: any, ctx: any) => {
+    const browser = ctx.browser
+    let email = ''
+    let password = ''
+    let name = ''
+    let error = ''
+    let loading = false
+    const submit = async () => {
+      error = ''
+      if (!email.includes('@')) { error = '请输入有效邮箱'; ctx.render(); return }
+      if (password.length < 6) { error = '密码至少 6 位'; ctx.render(); return }
+      loading = true; ctx.render()
+      const res = await api(browser, `/api/auth/${mode}`, { email, password, name })
+      loading = false
+      if (res.ok && res.user) {
+        authStore.update((s) => { s.user = res.user!; s.error = null })
+        browser.storageSet('auth:token', (res as any).token ?? '')
+        location.hash = '#/'
+      } else {
+        error = res.error ?? '请求失败'
+      }
+      ctx.render()
+    }
+    return async (_p: any) => (
+      <AuthPage
+        title={mode === 'login' ? '登录' : '注册'}
+        subtitle="auth 应用模板——内存用户 + 会话（演示）"
+        logo={<Avatar name="wf" />}
+        submitLabel={mode === 'login' ? '登录' : '注册'}
+        loading={loading}
+        error={error || null}
+        onSubmit={() => void submit()}
+        footer={<a href={mode === 'login' ? '#/register' : '#/login'} class="wf-link" style="cursor:pointer">{mode === 'login' ? '没有账号？注册' : '已有账号？登录'}</a>}
+      >
+        {mode === 'register' && (
+          <Input label="昵称" value={name} onInput={(e: any) => { name = (e.target as HTMLInputElement).value; ctx.render() }} placeholder="如何称呼你" />
+        )}
+        <Input label="邮箱" type="email" value={email} onInput={(e: any) => { email = (e.target as HTMLInputElement).value; ctx.render() }} placeholder="name@example.com" required />
+        <Input label="密码" type="password" value={password} onInput={(e: any) => { password = (e.target as HTMLInputElement).value; ctx.render() }} placeholder="至少 6 位" />
+      </AuthPage>
+    )
+  }
+
+export const LoginPage = AuthFormPage('login')
+export const RegisterPage = AuthFormPage('register')
+
+/** 受保护页（未登录 → 登录页——路由守卫） */
+export const DashboardPage: Component = async (_init: any, ctx: any) => {
+  const browser = ctx.browser
+  // 会话恢复（mount——ctx.browser.storage 安全适配）
+  void (async () => {
+    try {
+      const token = browser.storageGet('auth:token')
+      if (!token) return
+      const res = await fetch('/api/auth/me', { headers: { Authorization: `Bearer ${token}` } })
+      if (res.ok) {
+        const { user } = await res.json()
+        authStore.update((s) => { s.user = user })
+      }
+    } catch { /* 无会话 */ }
+  })()
+  const state = ctx.ui.useExternal(authStore)
+  const logout = () => {
+    browser.storageRemove('auth:token')
+    authStore.update((s) => { s.user = null })
+    location.hash = '#/login'
+  }
+  return async (_p: any) => {
+    if (!state.user) return h(LoginPage, {})
+    const u = state.user
+    return (
+      <div class="wf-stack wf-gap-md" style="max-width:560px">
+        <PageHeader
+          title={`欢迎，${u.name ?? u.email}`}
+          sub="登录态由 createStore 持有——路由守卫读它决定渲染"
+        >
+          <Button variant="ghost" onClick={logout}>登出</Button>
+        </PageHeader>
+        <div class="wf-surface wf-border wf-rounded-md wf-p-md wf-stack wf-gap-sm">
+          <Space align="center" size="md"><Avatar name={u.name ?? u.email} size="lg" /><b>{u.email}</b></Space>
+          <Alert variant="success">✓ 已登录——受保护内容可见。刷新页面会话自动恢复（ctx.browser.storage）</Alert>
+        </div>
+      </div>
+    )
+  }
+}
+
+/** 路由守卫：包装页面——未登录跳登录（守卫逻辑在页面组件内读 store） */
+export const guard = (page: Component): Component => page
+
+// ── 路由表 ──
+export const authRoutes = [
+  { path: '/', render: () => h(DashboardPage, {}) },
+  { path: '/login', render: () => h(LoginPage, {}) },
+  { path: '/register', render: () => h(RegisterPage, {}) },
+]
+
+export const pathFromHash = (): string => location.hash.replace(/^#/, '') || '/'
+
+export function createAuthApp(root: HTMLElement, _options?: { history?: boolean }): ReturnType<typeof uiServe> {
+  // vdom 规范面：UIRouter + uiServe——布局共享精准路由
+  const router = new UIRouter()
+  for (const r of authRoutes) {
+    router.get(r.path, (req: Request, ctx: any) =>
+      (ctx as { stream: (v: unknown) => Response }).stream(r.render()))
+  }
+  return uiServe(router, { root, browser: createClientBrowser()! })
+}

package/examples/apps/auth/main.tsx

@@ -0,0 +1,8 @@
+/**
+ * auth 独立入口——复制本目录即可运行：
+ *   cd examples/apps/auth && node server.ts → http://localhost:3301
+ */
+import { createAuthApp, pathFromHash } from './app.tsx'
+
+const sub = createAuthApp(document.querySelector('#root') as HTMLElement)
+window.addEventListener('hashchange', () => sub.navigate(pathFromHash()))