weifuwu 0.91.0 → 0.93.0

package/dist/server/response.d.ts

@@ -44,3 +44,20 @@ export declare function serverError(message?: string): Response;
  * ```
  */
 export declare function redirect(url: string, status?: number): Response;
+/**
+ * 错误 → Response（总错误面——HTTP 链（router.onError/默认链）与 route 内
+ * catch 同语义——DbError/HttpError 映射单源）。
+ *
+ * 双层语义（有意分层——文档契约）：
+ * - **链面（未捕获）**：普通 Error → 500（Internal Server Error——意外错误
+ *   诚实现形不泄漏——router.handleError 默认链消费）；DbError/ValidationError
+ *   → 400/409（orm 错误不该 500）
+ * - **route 内 catch（已知业务）**：普通 Error → 400（业务守卫/校验——
+ *   「我知道这是什么错」→ errorResponse 显式调用）
+ * - HttpError：双面一致（status 权威——403/404/409 同输出）
+ *
+ * code 面（`{ error, code }`——前端可 switch 而非解析 message 字符串）：
+ *   ValidationError → 'validation' · DbError 23505 → 'conflict' ·
+ *   DbError.kind → kind · HttpError/普通 Error → 无 code（status 已是语义）。
+ */
+export declare function errorResponse(e: unknown, status?: number): Response;

package/docs/client.md

@@ -56,21 +56,57 @@ app.router(Router())
 ## 3. 设计语言
 
 微流明（Whisper Luminance）：中性色主导、品牌色点睛、动效短促有目的（120–300ms）、
-1px 边界即结构。**Token 即规范**——`src/client/layout/style.css`（183 双层 token：
-色阶/排版/动效/圆角/阴影/z-index）——组件只引用 token、零硬编码（audit 强制）。
+1px 边界即结构。**Token 即规范**——`src/client/layout/_tokens.css`（178 token：
+色阶/排版/动效/圆角/阴影/z-index；`_dark.css` 暗色覆写 · `_presets.css` 紧凑预设覆写）
+——组件只引用 token、零硬编码（audit 强制）。
+
+**token 两面纪律**（layout-inventory L10/L11 哨兵）：
+
+- **断点单源**：`--wf-bp-sm/md/lg/xl` = 640/768/1024/1280——CSS 媒体查询语法不能
+  `var()`，故 token 作**审计白名单源**：合法字面量只有两形态 `V`（`min-width`）与
+  `V - 0.02`（`max-width`）——二者无缝对接（旧碎片：组件面 `639px`/`767px` vs
+  layout 面 `767.98px`——767.00–767.98 区间两侧规则同时失配）
+- **死面 = 0（登记制）**：token 声明必须有消费证据（`var()` / TS 字面）——零消费即删，
+  结构性不可消费的（bp-* 机制源 · gap-2xl 标尺完整性）逐条登记理由；反向哨兵：
+  登记项一旦有消费者即需移出（防登记表腐化）
+- **双标尺（定案）**：`--wf-gap-*` **派生**自 `--wf-space-*`（紧一档：gap-md = space 裸档
+  = 12px · gap-lg = space-md）。容器内元素间距 < 控件内边距是有意的密度设计，**不是**
+  同名不同值的命名事故——关系入代码（L13 登记 + 值冻结），预设只覆写 space 标尺
+  （gap 自动跟随）
+- **同值双名（L12）**：同主题文件内值全等且名为「限定词插入」形态（`shadow` ⊂
+  `surface-shadow`）= 历史双名 → 必须 `var()` 单源（语义名保留、值改引用）；
+  跨域巧合（motion-sm 4px ≡ overlay-blur 4px · 240px/200px 三胞胎）**判负不耦合**
+  （耦合即隐形爆炸半径）
+- **px 字面量（L14）**：layout 类文件只允许登记白名单内的结构魔数（44px 命中区 ·
+  999px 胶囊 · 1px 发丝走 `--wf-border-width` · 2px/4px bleed 对 · 32px 视口内缩 ·
+  2px hover 微抬升）——新增字面量必须 token 化或登记
 
 品牌换色 = 改 seed 一个值；预设主题 = `data-theme` 一个属性（minimal/dark）。
 
 ## 4. 布局系统
 
-`src/client/layout/`——49 原语（`_*.css`）+ 92 工具 + 2 内部，全部 `wf-` 前缀：
+`src/client/layout/`——50 原语（`_*.css`）+ 98 工具 + 2 内部，全部 `wf-` 前缀；
+**装配单源**：四处管线（build 产物 / showcase dev / 场景 dev / `ctx.ui.css`）共用
+`bundle.ts`——层序单源（D4 审计比对）；**发布产物 minify**（esbuild——见文末载荷面）：
 
 - **原语**：`wf-stack` / `wf-row` / `wf-grid` / `wf-center` / `wf-card-surface` / `wf-divider`
 - **工具**：`wf-padding` / `wf-margin` / `wf-text-*` / `wf-bg-*` / `wf-hidden`
-- **命名规则**：三类词根 + 三后缀（完整词根表见 `apps/showcase/src/demos/layout.tsx`
-  与 `src/test/contract/layout-inventory.test.ts` L1 计数断言——**测试即登记表**）
-
-零值形态唯一（`none` 归一）· 对齐域禁方向词 · 双名歼灭——layout-inventory 8 断言锁定。
+- **命名规则**：三类词根 + 三后缀（完整词根表 = **机器生成** `docs/layout.md`：类清单/断点表/
+  钩子表/标尺派生/零消费公共面示例——与 `layout-inventory` 哨兵同源，改布局源码后
+  `node scripts/layout-reference.mjs` 再生成；L15 校验漂移即红）
+
+零值形态唯一（`none` 归一）· 对齐域禁方向词 · 双名歼灭 · 零值档位矩阵（取消面缺口登记）·
+冲突矩阵（同属性不同值对的同元素共用逐对登记胜者+胜因）· 层叠机制锁定（层序/`:where()`/
+`!important` 白名单/`@property` 钩子注册）· 断点与 token 单源 · token 双名歼灭 ·
+间距标尺派生登记 · px 字面量白名单——layout-inventory **20 断言**锁定；
+层叠语义的浏览器计算值读数见场景层 `e2e-layout-semantics.test.ts`。
+
+**载荷面（W6 minify）**：dist 发布产物 `weifuwu-layout.css` **28.1K**（gzip 5.7K · brotli 5.1K）·
+`weifuwu/components/style.css` **220.9K**（gzip 29.4K · brotli 24.3K）——esbuild minify（
+`build.mjs` 实装：`@layer`/`@property`/`@supports`/转义类名全保留，注释全剥离）；
+**无组件应用只引 `weifuwu/layout`**（28.1K / br 5.1K——独立面，零组件 CSS 成本）。
+按需子集（per-component 子路径 / purge）**判负**：动态类名漏删风险 + 构建期改造成本
++ br 后 24.3K 非瓶颈——推翻条件：真实应用首屏 CSS 成为 LCP 阻塞的实测数据。
 
 ## 5. 组件编写规范（唯一入口）
 
@@ -89,6 +125,10 @@ app.router(Router())
   回调/类函数属性差异**不触发**（比较器自有豁免权——如 CodeEditor 忽略 onChange
   闭包引用）。默认不挂 = 行为完全不变。典型：CodeEditor（value/lang/rows/readOnly
   比较——高频输入页面零 diff 扰动）
+  **页面级范式（web W3 试点——AgentGrid 先例）**：列表区独立成组件 +
+  `shouldRender` 比较**数据引用**（`agents` 数组未变 = 输入键击不重渲列表段——
+  高频输入页的「静态邻居」零 diff）；回调经闭包（onDm/onRemove 豁免——
+  CodeEditor 同款）；单消费者页内组件（不违反「>1 消费者入库」——判负登记）
 
 ### 5.2 三件套
 
@@ -112,6 +152,32 @@ props camelCase · **`className=`（组件 props）`class=`（DOM 元素）** ·
 **状态变体类必须有规则或 `:where(.wf-x) {}` 显式声明**（L3 已扩围组件源码——未定义立即红）·
 动效 `--wf-dur-*`/`--wf-ease-*` · transition 含 visibility（隐藏不可 Tab 聚焦）
 
+**组件 px 四纪律（C1 哨兵强制——`contract/components-px.test.ts` 四桶登记制）**：
+
+1. **间距走标尺**：padding/margin/gap 的 4/8/12/16/24/32px →
+   `var(--wf-space-*)`/`var(--wf-gap-*)`（**任一档位值字面量 = 红**——含 var 混合声明
+   `padding: 8px var(--wf-x)` 同样适用——半 token 禁止；档位外值 = 结构桶登记制）
+2. **边框宽走发丝 token**：`border[N]: 1px solid/dashed …` → `var(--wf-border-width)`
+   （色可走 var/currentColor/transparent——hex 已锁 0；**非 1px 宽 = 强调边框**——无 token 面登记制）
+3. **结构值登记制**：非档位 px（结构尺寸/魔数——height/width/min-*/outline/box-shadow 偏移/
+   44px 命中区/z-index:1 等）→ `scripts/components-px-whitelist.json` structural/zIndex 桶
+   **登记 + 理由**（新增未登记 = 红 · 处理完未移出 = 幽灵红）
+4. **豁免面**：派生表达式（calc/env/min/max/clamp——L13 同款）与 0px 零值形态——非作者手写终值
+
+> 紧凑预设语义：**只有走 var() 的组件才跟随缩放**（_presets.css「间距缩一档」——手写=静止=活体缺口）。
+
+**C2 扩展纪律（`contract/components-token.test.ts` 三桶——token 消费哨兵）**：
+
+5. **文本行高走档**：`line-height` 值 ∈ {1.5, 1.25}（恒等档）→ `var(--wf-line-height)`/
+   `var(--wf-line-height-tight)`（近值=红）；代码排版 1.6（CodeBlock/DiffView——2 消费者
+   <3 升档门——第三消费者出现即升 --wf-line-height-code）；豁免面 {1 重置/0/px 图标}
+6. **弹层宽走钩子**：`.wf-popup` 系面板 **禁止手写 max-width**——基类
+   `min(var(--wf-popup-max, 480px), calc(100vw - 32px))` 是唯一入口；组件默认宽用
+   **回退值**表达（`min(var(--wf-popup-max, 320px), …)`——回退=默认宽）；非弹层面板宽
+   （命令面板/通知条/工作区）判负登记——`popup-max` 钩子调不动 = 钩子失效面
+7. **token 零消费双分类**：{保留类（色板档/暗色映射档/布局档/断点档——消费形态非
+   var() 引用）/真死候选}——新增零消费 token 需登记（消费矩阵哨兵——对齐 L11 组件版）
+
 ### 5.5 测试二层（覆盖哨兵 ≥2 层）
 
 1. **契约 harness**（`<Comp>.test.ts`——mount/render/createTable 命令流断言）
@@ -142,6 +208,27 @@ style-audit 文件数基线 +1 · 覆盖哨兵跑绿（`scripts/audit-component-
 R-03：类名/结构变更**反查测试选择器**（`[class*="..."]` 定位器）·
 行为变化**必带契约测试** · 机制化优先（能进审计不靠记忆）
 
+---
+
+### 6.1 认证接线范式（fullstack W4——onRefresh 时序契约）
+
+```ts
+// uiServe options（v3-main.tsx）——auth 客户端接线（token 双源防线）
+auth: auth({ storage, onAuth: (c) => {...}, onRefresh: async () => {
+  // onRefresh 闭包直引（2027-09 教训：间接层 authRef 曾致 401 死循环——
+  // refresh 后 token 未更新——闭包直引 source 是唯一的）
+  const ok = await api.post('/api/auth/refresh', undefined, { skipAuth: true })
+  ...
+}})
+```
+
+- **时序契约**：onRefresh 返回 true 语义 = token 已重写（storage 就绪）——
+  false/异常 = 401 踢登录——**未配置 onRefresh → refresh() 恒 false + warn**
+  （机制化防线——401 时 console.warn 提示「未接线」——不再静默）
+- 401 → refresh 重试一次（ApiClient 层）→ 仍失败清 token 跳登录（兜底）
+
+---
+
 ## 6. 前端架构导论
 
 ```
@@ -172,5 +259,39 @@ R-03：类名/结构变更**反查测试选择器**（`[class*="..."]` 定位器
 
 ---
 
+### 7.1 页面数据世代（web W1——useAsyncData 首选手册）
+
+**为什么迁（v2 段复用实录）**：老世代 `load() + ctx.render()` 在工厂期异步启动
+——v2 段复用语义下**工厂不重跑 → 数据永不刷新**（导航返回/同会话停滞——
+Templates 迁移先例）。**getter 快照 bug（Agents W1 实录）**：`const agents =
+getAgents() ?? []` 在**工厂期**解构 = 渲染用旧快照（state$ 更新后不显示）——
+**必须在 renderFn 内读**（getter 纪律的页面级体现）。
+
+**怎么迁（5 行范本）**：
+
+```ts
+export const Agents: Component = (_p, ctx) => {
+  const [getAgents, reloadAgents] = ctx.ui.useAsyncData(async () => {
+    return (await ctx.api.get(`/api/agents`)).agents ?? []
+  }, 'agents-page')            // 同 key 并发合并 · key 稳定（页面级）
+  let qValue = ''              // 搜索闭包（getter 纪律）
+  return () => {
+    const agents = getAgents() ?? []        // 渲染期读最新（不是工厂期！）
+    const loading = getAgents() === null     // null = loading 态
+    return h('ul', {}, agents.map(...))
+  }
+}
+```
+
+**迁移后得到什么**：① 同 key 并发合并（多次挂载 1 次请求）② 竞态取消
+（switchMap——快速搜索乱序响应丢弃）③ 缓存保留（重挂载零请求——导航返回
+瞬时）④ reload 显式刷新（删除/变更后服务器权威）。搜索面：q 闭包 +
+debounce(reload)——触发读最新 q。
+
+**哨兵**：`apps/agent-platform/scripts/audit-page-generations.mjs`（async 工厂
+= 红 exit 1——工厂同步契约；老世代标记 = 黄报——迁移进度可见）。
+
+---
+
 > **运行**：`npm run test:client`（428 契约）· `npm run test:scenario`（123 场景）·
 > `npm run test:showcase`（324 组件测试）——全量防线见 AGENTS.md §1。

package/docs/layout.md

@@ -0,0 +1,243 @@
+# weifuwu/layout 参考
+
+> **机器生成**（`scripts/layout-reference.mjs`）——勿手改：改布局源码后跑 `node scripts/layout-reference.mjs`。
+> 单源校对：类清单 = `layout-inventory.mjs inventory()` · 层序 = `bundle.ts LAYER_ORDER` ·
+> 钩子 = `_props.css @property` · 标尺/断点 = `_tokens.css`。计数口径与 README/`docs/client.md` 全等（L6 哨兵）。
+
+## 1. 层叠与覆盖规则（L9 机制锁定）
+
+- **层序**：@layer `tokens, base, layout, components, utilities`——工具类在 components 之后 = 消费侧显式覆盖恒胜组件样式（旧序相反——W2 修正）
+- **display 族基类**（wf-block/wf-flex/wf-hidden）`:where()` 零优先级——断点变体（@sm/@lg）正常优先级 → 变体恒胜基类（跨文件亦然）
+- **`!important` 白名单**：仅 `prefers-reduced-motion`（无障碍强制）——其余位置禁（变体靠 specificity 胜出）
+- **变量钩子**：`@property inherits:false`（W2）——外层内联赋值不污染子孙原语；syntax `*` 且不写 initial-value（保各原语不同回退值）
+
+## 2. 断点（`--wf-bp-*` = 媒体查询白名单单源——L10）
+
+| 档 | 值 | 合法媒体查询字面量 |
+| --- | --- | --- |
+| `--wf-bp-sm` | `640px` | `min-width:640px` / `max-width:639.98px` |
+| `--wf-bp-md` | `768px` | `min-width:768px` / `max-width:767.98px` |
+| `--wf-bp-lg` | `1024px` | `min-width:1024px` / `max-width:1023.98px` |
+| `--wf-bp-xl` | `1280px` | `min-width:1280px` / `max-width:1279.98px` |
+
+## 3. 变量钩子（内联覆盖面——`@property` 注册 9 条）
+
+| 钩子 | 回退值（layout 内首个消费） | 说明 |
+| --- | --- | --- |
+| `--wf-gap` | `（无回退——必填钩子）` | 容器间距默认（stack/row/cluster/grid 原语共用） |
+| `--wf-align` | `（无回退——必填钩子）` | 对齐默认（cross-axis） |
+| `--wf-justify` | `（无回退——必填钩子）` | 主轴对齐默认 |
+| `--wf-cols` | `（无回退——必填钩子）` | grid 列模板（grid 原语） |
+| `--wf-max` | `（无回退——必填钩子）` | 容器最大宽（container 原语） |
+| `--wf-w-sm` | `（无回退——必填钩子）` | width-sm 工具类默认 |
+| `--wf-z` | `（无回退——必填钩子）` | z 档位默认 |
+| `--wf-offset` | `（无回退——必填钩子）` | sticky 偏移 |
+| `--wf-popup-max` | `（无回退——必填钩子）` | 弹层最大宽（popup 原语） |
+
+## 4. 类清单（inventory 全量——含状态修饰与断点变体）
+
+### 原语（50）
+
+| 类 | 文件 | 声明摘要 | 断点变体 | 状态修饰 |
+| --- | --- | --- | --- | --- |
+| `wf-absolute` | _position.css | position · position:absolute | — | — |
+| `wf-app-shell` | _app-shell.css | display · grid-template-columns · height · overflow · display:grid · overflow:visible | — | — |
+| `wf-block` | _block.css | display · display:block | — | — |
+| `wf-center` | _center.css | align-items · display · flex-direction · justify-content · display:flex · flex-direction:column · align-items:… | — | — |
+| `wf-cluster` | _cluster.css | align-items · display · flex-wrap · gap · justify-content · display:flex · flex-wrap:wrap · justify-content:va… | — | — |
+| `wf-container` | _container.css | margin · max-width · padding · width | — | — |
+| `wf-cover` | _cover.css | align-items · display · inset · justify-content · position · z-index · position:fixed · display:flex · align-i… | — | — |
+| `wf-dim` | _hidden.css | opacity | — | — |
+| `wf-fill` | _fill.css | flex · min-height · min-width · flex:1 | — | — |
+| `wf-fill-hover` | _fill.css | background · border-radius · margin · padding · transition | — | — |
+| `wf-flex` | _flex.css | display · display:flex | @@lg @@sm | — |
+| `wf-grid` | _grid.css | display · gap · grid-template-columns · display:grid | — | — |
+| `wf-hidden` | _hidden.css | display · display:none | @@lg | — |
+| `wf-items-center` | _row.css |  | — | — |
+| `wf-items-end` | _row.css |  | — | — |
+| `wf-items-start` | _row.css |  | — | — |
+| `wf-items-stretch` | _row.css |  | — | — |
+| `wf-justify-between` | _justify.css | align-items · display · gap · justify-content · display:flex · justify-content:space-between · align-items:var… | — | — |
+| `wf-justify-center` | _justify.css | align-items · display · gap · justify-content · display:flex · justify-content:center · align-items:var(--wf-a… | — | — |
+| `wf-justify-end` | _justify.css | align-items · display · gap · justify-content · display:flex · justify-content:flex-end · align-items:var(--wf… | — | — |
+| `wf-layer` | _layer.css | position · z-index · position:relative | — | — |
+| `wf-main` | _app-shell.css | background · margin-inline · max-width · min-height · min-width · overflow · overflow-y · padding · overflow:v… | — | — |
+| `wf-min-width-0` | _shrink.css | min-width | — | — |
+| `wf-nav` | _app-shell.css | display · flex-direction · gap · display:flex · flex-direction:column | — | `wf-nav--collapsed` |
+| `wf-nav--collapsed` | _app-shell.css | （基类 `wf-nav` 的状态修饰） | | |
+| `wf-nav-group` | _app-shell.css | color · font-size · font-weight · letter-spacing · padding · text-transform | — | — |
+| `wf-nav-item` | _app-shell.css | align-items · background · border · border-radius · box-shadow · color · cursor · display · font-family · font… | — | `wf-nav-item--active` |
+| `wf-nav-item--active` | _app-shell.css | （基类 `wf-nav-item` 的状态修饰） | | |
+| `wf-nowrap` | _nowrap.css | display · flex-wrap · gap · display:flex · flex-wrap:nowrap | — | — |
+| `wf-overflow-auto` | _overflow.css | overflow · overflow:auto | — | — |
+| `wf-overflow-hidden` | _overflow.css | overflow · overflow:hidden | — | — |
+| `wf-overflow-x` | _overflow.css | overflow-x | — | — |
+| `wf-pointer` | _hidden.css | cursor | — | — |
+| `wf-relative` | _position.css | position · position:relative | — | — |
+| `wf-row` | _row.css | align-items · display · flex-wrap · gap · display:flex · flex-wrap:wrap · align-items:var(--wf-align, center) | — | — |
+| `wf-row-reverse` | _row.css | align-items · display · flex-direction · flex-wrap · gap · display:flex · flex-direction:row-reverse · flex-wr… | — | — |
+| `wf-safe-bottom` | _safe-area.css | padding-bottom | — | — |
+| `wf-safe-top` | _safe-area.css | padding-top | — | — |
+| `wf-self-center` | _align-self.css | align-self | — | — |
+| `wf-self-end` | _align-self.css | align-self | — | — |
+| `wf-self-start` | _align-self.css | align-self | — | — |
+| `wf-self-stretch` | _align-self.css | align-self | — | — |
+| `wf-shrink` | _shrink.css | min-height · min-width | — | — |
+| `wf-sidebar` | _app-shell.css | background · border-bottom · border-right · display · flex-direction · height · overflow-y · position · top · … | — | — |
+| `wf-sidebar-body` | _app-shell.css | flex · overflow-y · padding · flex:1 | — | — |
+| `wf-sidebar-footer` | _app-shell.css | border-top · flex-shrink · padding | — | — |
+| `wf-sidebar-header` | _app-shell.css | align-items · border-bottom · display · flex-shrink · gap · padding · display:flex · align-items:center | — | — |
+| `wf-split` | _split.css | align-items · display · flex-shrink · gap · justify-content · display:flex · justify-content:space-between · a… | — | — |
+| `wf-stack` | _stack.css | align-items · display · flex-direction · gap · display:flex · flex-direction:column · align-items:var(--wf-ali… | — | — |
+| `wf-sticky` | _sticky.css | position · top · position:sticky | — | — |
+
+### 工具（98）
+
+| 类 | 文件 | 声明摘要 | 断点变体 | 状态修饰 |
+| --- | --- | --- | --- | --- |
+| `wf-bg-error` | _surface.css | background | — | — |
+| `wf-bg-none` | _surface.css | background | — | — |
+| `wf-bg-primary` | _surface.css | background | — | — |
+| `wf-bg-secondary` | _surface.css | background | — | — |
+| `wf-bg-tertiary` | _surface.css | background | — | — |
+| `wf-bg-warning` | _surface.css | background | — | — |
+| `wf-bold` | _text.css | font-weight | — | — |
+| `wf-border` | _border.css | border | — | — |
+| `wf-border-bottom` | _border.css | border-bottom | — | — |
+| `wf-border-left` | _border.css | border-left | — | — |
+| `wf-border-none` | _border.css | border | — | — |
+| `wf-border-right` | _border.css | border-right | — | — |
+| `wf-border-top` | _border.css | border-top | — | — |
+| `wf-break-word` | _text.css | overflow-wrap · word-break | — | — |
+| `wf-bubble` | _surface.css | background · border-radius · color · display · font-size · line-height · max-width · padding · white-space · w… | — | `wf-bubble--ai` `wf-bubble--own` |
+| `wf-bubble--ai` | _surface.css | （基类 `wf-bubble` 的状态修饰） | | |
+| `wf-bubble--own` | _surface.css | （基类 `wf-bubble` 的状态修饰） | | |
+| `wf-card-outline` | _surface.css | border | — | — |
+| `wf-elevate` | _surface.css | box-shadow · outline · transform · transition | — | — |
+| `wf-font-2xl` | _text.css | font-size | — | — |
+| `wf-font-3xl` | _text.css | font-size | — | — |
+| `wf-font-4xl` | _text.css | font-size | — | — |
+| `wf-font-base` | _text.css | font-size | — | — |
+| `wf-font-lg` | _text.css | font-size | — | — |
+| `wf-font-mono` | _text.css | font-family | — | — |
+| `wf-font-sm` | _text.css | font-size | — | — |
+| `wf-font-xs` | _text.css | font-size | — | — |
+| `wf-gap-lg` | _spacing.css | gap | — | — |
+| `wf-gap-md` | _spacing.css | gap | — | — |
+| `wf-gap-none` | _spacing.css | gap | — | — |
+| `wf-gap-sm` | _spacing.css | gap | — | — |
+| `wf-gap-xl` | _spacing.css | gap | — | — |
+| `wf-gap-xs` | _spacing.css | gap | — | — |
+| `wf-height-full` | _spacing.css | height | — | — |
+| `wf-margin-bottom-lg` | _spacing.css | margin-bottom | — | — |
+| `wf-margin-bottom-md` | _spacing.css | margin-bottom | — | — |
+| `wf-margin-bottom-sm` | _spacing.css | margin-bottom | — | — |
+| `wf-margin-bottom-xs` | _spacing.css | margin-bottom | — | — |
+| `wf-margin-left-sm` | _spacing.css | margin-left | — | — |
+| `wf-margin-left-xs` | _spacing.css | margin-left | — | — |
+| `wf-margin-none` | _spacing.css | margin | — | — |
+| `wf-margin-top-md` | _spacing.css | margin-top | — | — |
+| `wf-margin-top-none` | _spacing.css | margin-top | — | — |
+| `wf-margin-top-sm` | _spacing.css | margin-top | — | — |
+| `wf-margin-top-xs` | _spacing.css | margin-top | — | — |
+| `wf-margin-x-auto` | _spacing.css | margin-left · margin-right | — | — |
+| `wf-margin-y-xs` | _spacing.css | margin-bottom · margin-top | — | — |
+| `wf-medium` | _text.css | font-weight | — | — |
+| `wf-nums` | _text.css | font-variant-numeric | — | — |
+| `wf-padding-bottom-md` | _spacing.css | padding-bottom | — | — |
+| `wf-padding-bottom-sm` | _spacing.css | padding-bottom | — | — |
+| `wf-padding-bottom-xs` | _spacing.css | padding-bottom | — | — |
+| `wf-padding-left-sm` | _spacing.css | padding-left | — | — |
+| `wf-padding-lg` | _spacing.css | padding | — | — |
+| `wf-padding-md` | _spacing.css | padding | — | — |
+| `wf-padding-none` | _spacing.css | padding | — | — |
+| `wf-padding-sm` | _spacing.css | padding | — | — |
+| `wf-padding-top-sm` | _spacing.css | padding-top | — | — |
+| `wf-padding-x-md` | _spacing.css | padding-left · padding-right | — | — |
+| `wf-padding-x-sm` | _spacing.css | padding-left · padding-right | — | — |
+| `wf-padding-x-xs` | _spacing.css | padding-left · padding-right | — | — |
+| `wf-padding-xl` | _spacing.css | padding | — | — |
+| `wf-padding-xs` | _spacing.css | padding | — | — |
+| `wf-padding-y-lg` | _spacing.css | padding-bottom · padding-top | — | — |
+| `wf-padding-y-md` | _spacing.css | padding-bottom · padding-top | — | — |
+| `wf-padding-y-sm` | _spacing.css | padding-bottom · padding-top | — | — |
+| `wf-padding-y-xs` | _spacing.css | padding-bottom · padding-top | — | — |
+| `wf-panel-in` | _surface.css | animation · transform-origin | — | — |
+| `wf-pill` | _surface.css | border-radius | — | — |
+| `wf-pre-wrap` | _text.css | white-space · word-break | — | — |
+| `wf-radius` | _surface.css | border-radius | — | — |
+| `wf-radius-lg` | _surface.css | border-radius | — | — |
+| `wf-radius-md` | _surface.css | border-radius | — | — |
+| `wf-radius-sm` | _surface.css | border-radius | — | — |
+| `wf-rounded-md` | _surface.css | border-radius | — | — |
+| `wf-rounded-sm` | _surface.css | border-radius | — | — |
+| `wf-semibold` | _text.css | font-weight | — | — |
+| `wf-shadow` | _surface.css | box-shadow | — | — |
+| `wf-surface` | _surface.css | background · border-radius · box-shadow | — | `wf-surface--flat` |
+| `wf-surface--flat` | _surface.css | （基类 `wf-surface` 的状态修饰） | | |
+| `wf-text-center` | _text.css | text-align | — | — |
+| `wf-text-danger` | _text.css | color | — | — |
+| `wf-text-error` | _text.css | color | — | — |
+| `wf-text-left` | _text.css | text-align | — | — |
+| `wf-text-nowrap` | _text.css | white-space | — | — |
+| `wf-text-on-brand` | _text.css | color | — | — |
+| `wf-text-on-warning` | _text.css | color | — | — |
+| `wf-text-primary` | _text.css | color | — | — |
+| `wf-text-right` | _text.css | text-align | — | — |
+| `wf-text-secondary` | _text.css | color | — | — |
+| `wf-text-success` | _text.css | color | — | — |
+| `wf-text-tertiary` | _text.css | color | — | — |
+| `wf-text-warning` | _text.css | color | — | — |
+| `wf-tracking-wide` | _text.css | letter-spacing | — | — |
+| `wf-truncate` | _text.css | overflow · text-overflow · white-space · overflow:hidden | — | — |
+| `wf-uppercase` | _text.css | text-transform | — | — |
+| `wf-width-full` | _spacing.css | width | — | — |
+| `wf-width-sm` | _spacing.css | width | — | — |
+
+### 内部（2）
+
+| 类 | 文件 | 声明摘要 | 断点变体 | 状态修饰 |
+| --- | --- | --- | --- | --- |
+| `wf-popup` | _popup.css | box-sizing · max-width | — | — |
+| `wf-popup-mask` | _popup.css | background · inset · position · z-index · position:fixed | — | — |
+
+## 5. 间距标尺（双标尺定案——L13：gap 派生自 space 紧一档）
+
+| 档 | space（内/外边距） | gap（容器内间距——派生） | 关系 |
+| --- | --- | --- | --- |
+| — | `--wf-space` = `12px` | `--wf-gap-md = var(--wf-space)` | 裸档即 md 档源 |
+| xs | `4px` | `var(--wf-space-xs)` | gap 比 space 紧一档 |
+| sm | `8px` | `var(--wf-space-sm)` | gap 比 space 紧一档 |
+| md | `16px` | `var(--wf-space(裸))` | gap 比 space 紧一档 |
+| lg | `24px` | `var(--wf-space-md)` | gap 比 space 紧一档 |
+| xl | `32px` | `var(--wf-space-lg)` | gap 比 space 紧一档 |
+| 2xl | `40px` | `var(--wf-space-xl)` | gap 比 space 紧一档 |
+
+> 关系入代码：预设（compact）只覆写 space 标尺——gap 自动跟随；值冻结由 L13 守卫。
+
+## 6. 零消费公共面（文档化定案——「示例 = 可发现」，不做裁剪）
+
+以下类在代码语料（apps + src/client/components）零引用——属 weifuwu/layout npm 公共清单，
+退出消费或库侧裁剪时才移除（登记单源：`layout-inventory.mjs` QUARTET_KEEP / LIB_SURFACE_KEEP）；
+现文档化（示例 = 可发现）：
+
+- `wf-absolute`：定位：`<div class="wf-absolute wf-inset-0">`（绝对定位铺满——需 position 上下文）
+- `wf-cover`：媒体覆盖：`<div class="wf-cover"><img /></div>`（绝对定位全铺容器）
+- `wf-layer`：层叠原语：`<div class="wf-layer wf-z-pop">`（相对定位层，按 z 叠放）
+- `wf-nav`：导航条：`<nav class="wf-nav"><a class="wf-nav-item">…`（横向导航——内部项自带命中区）
+- `wf-nav-group`：导航分组：`<div class="wf-nav-group">`（导航项分组容器/标签）
+- `wf-radius-lg`：圆角档：`class="wf-radius-lg"`（大圆角——不在半径标尺逐档之外的独立值）
+- `wf-safe-bottom`：底部安全区：`class="wf-safe-bottom"`（env(safe-area-inset-bottom)——iOS 底部）
+- `wf-safe-top`：顶部安全区：`class="wf-safe-top"`（env(safe-area-inset-top)——刘海屏）
+- `wf-self-start`：cross-axis 单项定位：`class="wf-self-start"`（align-self: flex-start——与 wf-self-stretch 同族）
+
+> showcase 演示页私有类（`wf-variant-toggle/chevron/name/desc`——页面上下文定义，非库面）不计入。
+
+## 7. 计数速览（L1/L6 哨兵口径）
+
+| 面 | 数量 |
+| --- | --- |
+| 布局原语 | 50 |
+| 工具类 | 98 |
+| 内部类 | 2 |
+| 主题 token | 178 |