weifuwu 0.94.0 → 0.95.0

package/dist/level4/client/vdom/create-component.d.ts

@@ -0,0 +1,42 @@
+/**
+ * vdom core — createComponent（组件声明抽象——状态类/aria/role 机械面生成）
+ *
+ * 设计（2027-09——分层抽象 W3）：组件层 80 状态类 · 240 aria 手写实证——
+ * 类名拼接与布尔 aria 是**派生面**（prop 状态 → 类/aria 的确定性映射）——
+ * 声明化（BEM 规则单源在 createComponent——组件内无 `--${variant}` 模板）。
+ *
+ * 抽象边界（防配置地狱护栏）：只生成**机械部分**（类 + aria 布尔 + role）——
+ * 结构/内容/事件/业务 = render 自由面（皮）。判据：声明比实现短且机械部分
+ * 全消失——否则抽象失败（判负登记）。
+ *
+ * 用法：
+ *   const PayBtn = createComponent<PayProps>({
+ *     class: 'wf-pay-btn',
+ *     enumStates: { variant: null },          // 直拼 wf-pay-btn--<v>
+ *     boolStates: { active: 'wf-pay-btn--active' },
+ *     ariaBools: { active: 'aria-pressed' },
+ *     render: (root, props) => h('button', { ...root, onClick: props.onClick }, props.label),
+ *   })
+ *   // 旧：cls 数组 7 行 + aria 2 行 → 新：声明行 + render
+ */
+import type { Component, VNode } from '../../../level0/vdom/vnode.ts';
+import type { UIContext } from '../../../level3/vdom/context/UIContext.ts';
+export interface CreateComponentDecl<P = Record<string, unknown>> {
+    /** BEM 词根（wf-btn——直拼 `wf-btn--<v>`；布尔状态用 boolStates 显式类） */
+    class: string;
+    /** 布尔状态 → 类变体（{ checked: 'wf-x--checked' }） */
+    boolStates?: Record<string, string>;
+    /** 枚举状态 → 类变体（值直拼 `wf-x--<v>`（null）或显式映射） */
+    enumStates?: Record<string, Record<string, string> | null>;
+    /** 布尔 → aria 属性（{ loading: 'aria-busy' }——真值写出属性） */
+    ariaBools?: Record<string, string>;
+    /** 根 role（静态） */
+    role?: string;
+    /** 皮（rootProps 组装毕——class/aria/role/class 透传已含——缺省
+     *  根元素直接透传——render 负责结构/内容/事件——ctx 透传（i18n 等）） */
+    render?: (rootProps: Record<string, unknown>, props: P, ctx: UIContext) => VNode | null;
+    /** 缺省渲染的根标签（render 未提供时——button） */
+    tag?: string;
+}
+/** 组件声明 → 组件工厂（同步——两阶段语义与手写一致） */
+export declare function createComponent<P = Record<string, unknown>>(decl: CreateComponentDecl<P>): Component<P>;

package/dist/level4/client/vdom/create-component.ts

@@ -0,0 +1,77 @@
+/**
+ * vdom core — createComponent（组件声明抽象——状态类/aria/role 机械面生成）
+ *
+ * 设计（2027-09——分层抽象 W3）：组件层 80 状态类 · 240 aria 手写实证——
+ * 类名拼接与布尔 aria 是**派生面**（prop 状态 → 类/aria 的确定性映射）——
+ * 声明化（BEM 规则单源在 createComponent——组件内无 `--${variant}` 模板）。
+ *
+ * 抽象边界（防配置地狱护栏）：只生成**机械部分**（类 + aria 布尔 + role）——
+ * 结构/内容/事件/业务 = render 自由面（皮）。判据：声明比实现短且机械部分
+ * 全消失——否则抽象失败（判负登记）。
+ *
+ * 用法：
+ *   const PayBtn = createComponent<PayProps>({
+ *     class: 'wf-pay-btn',
+ *     enumStates: { variant: null },          // 直拼 wf-pay-btn--<v>
+ *     boolStates: { active: 'wf-pay-btn--active' },
+ *     ariaBools: { active: 'aria-pressed' },
+ *     render: (root, props) => h('button', { ...root, onClick: props.onClick }, props.label),
+ *   })
+ *   // 旧：cls 数组 7 行 + aria 2 行 → 新：声明行 + render
+ */
+import type { Component, VNode, RenderFn } from '../../../level0/vdom/vnode.ts'
+import { h } from '../../../level0/vdom/vnode.ts'
+import type { UIContext } from '../../../level3/vdom/context/UIContext.ts'
+
+export interface CreateComponentDecl<P = Record<string, unknown>> {
+  /** BEM 词根（wf-btn——直拼 `wf-btn--<v>`；布尔状态用 boolStates 显式类） */
+  class: string
+  /** 布尔状态 → 类变体（{ checked: 'wf-x--checked' }） */
+  boolStates?: Record<string, string>
+  /** 枚举状态 → 类变体（值直拼 `wf-x--<v>`（null）或显式映射） */
+  enumStates?: Record<string, Record<string, string> | null>
+  /** 布尔 → aria 属性（{ loading: 'aria-busy' }——真值写出属性） */
+  ariaBools?: Record<string, string>
+  /** 根 role（静态） */
+  role?: string
+  /** 皮（rootProps 组装毕——class/aria/role/class 透传已含——缺省
+   *  根元素直接透传——render 负责结构/内容/事件——ctx 透传（i18n 等）） */
+  render?: (rootProps: Record<string, unknown>, props: P, ctx: UIContext) => VNode | null
+  /** 缺省渲染的根标签（render 未提供时——button） */
+  tag?: string
+}
+
+/** 组件声明 → 组件工厂（同步——两阶段语义与手写一致） */
+export function createComponent<P = Record<string, unknown>>(
+  decl: CreateComponentDecl<P>,
+): Component<P> {
+  return (initProps: P, ctx: UIContext) => {
+    const renderFn = (props: P) => {
+      void initProps
+      // 根 props 组装（机械面——单源）
+      const rootProps: Record<string, unknown> = {}
+      const cls = [decl.class]
+      for (const [k, v] of Object.entries(decl.enumStates ?? {})) {
+        const val = props[k as keyof P]
+        if (val == null) continue
+        if (v === null) cls.push(`${decl.class}--${String(val)}`)
+        else cls.push(v[String(val)] ??
+          `${decl.class}--${String(val)}` /* 映射缺口 = 直拼（显式映射不吞） */)
+      }
+      for (const [k, v] of Object.entries(decl.boolStates ?? {})) {
+        if (props[k as keyof P]) cls.push(v)
+      }
+      // class 透传（Button 先例：调用方响应式类 wf-hidden@lg 等——追加尾部）
+      const pc = (props as { class?: unknown }).class
+      if (pc) cls.push(pc as string)
+      rootProps.class = cls.join(' ')
+      for (const [k, attr] of Object.entries(decl.ariaBools ?? {})) {
+        if (props[k as keyof P]) rootProps[attr] = true
+      }
+      if (decl.role) rootProps.role = decl.role
+      if (decl.render) return decl.render(rootProps, props, ctx)
+      return h((decl.tag ?? 'div') as string, rootProps, (props as { children?: unknown }).children as never)
+    }
+    return renderFn as RenderFn<P>
+  }
+}

package/dist/level4/client/vdom/create-item.d.ts

@@ -0,0 +1,114 @@
+/**
+ * createItem —— 交互元素状态捆绑原语（原语全面化回馈 #2）
+ *
+ * 为什么存在：createComponent（组件级声明）在 W3 判负调查中暴露结构性错位——
+ * 组件 = 容器 + 可交互子项（Tabs 的 tab / SegmentedControl 的 option /
+ * TabBar 的 item），**状态类和 aria 布尔几乎总在子项上**（43 组件含状态面，
+ * 12 组件是「同条件驱动类 + aria 双面」的真机械面）。抽象单位切错了——
+ * 从「组件」下沉到「交互元素」：
+ *
+ *   ```ts
+ *   const tab = createItem({ cls: 'wf-tab', role: 'tab', aria: 'aria-selected' })
+ *   // 循环内：
+ *   h('button', tab(act === key, { onClick }), label)
+ *   // → { class: 'wf-tab wf-tab--active', role: 'tab', 'aria-selected': true, onClick }
+ *   ```
+ *
+ * 单源回报：类后缀与 aria 布尔**捆绑声明**——不可能改一面漏一面
+ * （aria-selected 与 --active 不同步 = a11y bug——同类手写双面同步是历史重复源）。
+ * aria 布尔直传内核（ariaBoolValue 归一——回馈 #1 后全库无手写三元冗余）。
+ *
+ * ## 多状态槽（2027-09——回馈 #4：单槽边界打开）
+ *
+ * 单活动态边界在 Menu/NavMenu 判负（submenu title = isActive roving +
+ * popupOpen expanded 双布尔——同一元素两个独立状态面）。设计：
+ *
+ *   ```ts
+ *   const title = createItem({
+ *     cls: 'wf-menu-submenu-title',
+ *     role: 'menuitem',
+ *     states: {
+ *       active: { roving: true },            // 槽名 active → 默认后缀 '--active'
+ *       open: { aria: 'aria-expanded' },     // 布尔型（false 保留）
+ *     },
+ *   })
+ *   // 调用：
+ *   h('div', title({ active: isActive, open: popupOpen }, { onClick }), ...)
+ *   ```
+ *
+ * 槽语义（每槽独立）：
+ * - `suffix`（默认 `--${槽名}`；`false` = 无类面——roving-only 槽）
+ * - `aria` 布尔（槽真 → true · 假 → false **保留**——Menu popupOpen 原语义）
+ * - `ariaText` 文本（槽真 → value · 假 → undefined **移除**——NavMenu
+ *   hasChildren gated 原语义）
+ * - `roving`（槽真 → 0 · 假 → -1）
+ *
+ * 兼容：单槽便捷形态（states 未声明 = `{ active: {...} }`——boolean 调用
+ * 不变——既有 8 契约与 9 组件零改动）。
+ *
+ * 边界（诚实）：槽值是布尔——aria 多值枚举（Tree 'mixed' / Cascader
+ * String() 多态）仍在契约外（判负登记）；槽间互斥衍生态（TabBar
+ * disabled 与 active 互斥——disabled 槽有独立 suffix）按独立面处理。
+ */
+export interface ItemStateSlot {
+    /** 槽态类后缀（默认 `--${槽名}`；false = 无类面） */
+    suffix?: string | false;
+    /** 槽态 aria 布尔键（真 → true · 假 → false 保留——内核归一） */
+    aria?: string;
+    /** 槽态 aria 文本值（真 → value · 假 → undefined 移除） */
+    ariaText?: {
+        key: string;
+        value: string;
+    };
+    /** roving tabindex（真 → 0 · 假 → -1） */
+    roving?: boolean;
+}
+/** 值域槽变体态（互斥单键多值——三态 checkbox 原型） */
+export interface ItemEnumVariant {
+    /** 类后缀（缺省无类面——input 型无状态类） */
+    suffix?: string;
+    /** 写入 enum.key 的值（boolean | string——'mixed' 型） */
+    aria?: boolean | string;
+    /** 附加 props（indeterminate/checked property 面——vdom property 通道） */
+    props?: Record<string, unknown>;
+}
+/** 值域槽声明（互斥单值——'checked' | 'half' | null——替代多键布尔） */
+export interface ItemEnumDecl {
+    /** 共享 aria 键（如 'aria-checked'）——各态写入互斥值 */
+    key: string;
+    /** 零值态（null 时：类无 · key=off.aria ?? false） */
+    off?: ItemEnumVariant;
+    /** 值态（互斥——键名即调用值） */
+    values: Record<string, ItemEnumVariant>;
+}
+export interface ItemStateDecl {
+    /** 基类（如 'wf-tab'）——槽态时派生 `cls + 槽后缀` */
+    cls: string;
+    /** role（所有实例同值——如 'tab'/'option'） */
+    role?: string;
+    /** 单槽便捷（等效 states: { active: {...} }——兼容既有用法） */
+    suffix?: string;
+    aria?: string;
+    ariaText?: {
+        key: string;
+        value: string;
+    };
+    roving?: boolean;
+    /** 多状态槽（槽名 = 类后缀词干——'active' → '--active'） */
+    states?: Record<string, ItemStateSlot>;
+    /** 值域槽（互斥单键多值——enum.key 写入各态 aria 值 + props 捆绑——
+     * 与 states 正交：states = 多键独立（Menu active+open）· enum = 单键互斥
+     * （三态 checkbox checked/half）） */
+    enum?: ItemEnumDecl;
+}
+export type ItemStateArg = boolean | Record<string, boolean> | string | null | undefined;
+/**
+ * 生成「交互元素状态 props」工厂——返回 (state, extra) => props。
+ * - 单槽（boolean 调用）：active=true 类带后缀 · aria 布尔 true · ariaText value
+ * - 多槽（对象调用）：每槽独立判定（类后缀 · aria · ariaText · roving）
+ * - 槽假值：aria 布尔 false（保留——与属性移除语义不同）· ariaText undefined（移除）
+ * - extra 后置 spread（extra 胜——扩展不用改声明）
+ * - **class 例外：extra.class 追加而非覆盖**（disabled/focus/variant 等
+ *   第二类面与状态后缀共存——覆盖会丢状态类——契约锁定合并语义）
+ */
+export declare function createItem(decl: ItemStateDecl): (state: ItemStateArg, extra?: Record<string, unknown>) => Record<string, unknown>;

package/dist/level4/client/vdom/create-item.ts

@@ -0,0 +1,180 @@
+/**
+ * createItem —— 交互元素状态捆绑原语（原语全面化回馈 #2）
+ *
+ * 为什么存在：createComponent（组件级声明）在 W3 判负调查中暴露结构性错位——
+ * 组件 = 容器 + 可交互子项（Tabs 的 tab / SegmentedControl 的 option /
+ * TabBar 的 item），**状态类和 aria 布尔几乎总在子项上**（43 组件含状态面，
+ * 12 组件是「同条件驱动类 + aria 双面」的真机械面）。抽象单位切错了——
+ * 从「组件」下沉到「交互元素」：
+ *
+ *   ```ts
+ *   const tab = createItem({ cls: 'wf-tab', role: 'tab', aria: 'aria-selected' })
+ *   // 循环内：
+ *   h('button', tab(act === key, { onClick }), label)
+ *   // → { class: 'wf-tab wf-tab--active', role: 'tab', 'aria-selected': true, onClick }
+ *   ```
+ *
+ * 单源回报：类后缀与 aria 布尔**捆绑声明**——不可能改一面漏一面
+ * （aria-selected 与 --active 不同步 = a11y bug——同类手写双面同步是历史重复源）。
+ * aria 布尔直传内核（ariaBoolValue 归一——回馈 #1 后全库无手写三元冗余）。
+ *
+ * ## 多状态槽（2027-09——回馈 #4：单槽边界打开）
+ *
+ * 单活动态边界在 Menu/NavMenu 判负（submenu title = isActive roving +
+ * popupOpen expanded 双布尔——同一元素两个独立状态面）。设计：
+ *
+ *   ```ts
+ *   const title = createItem({
+ *     cls: 'wf-menu-submenu-title',
+ *     role: 'menuitem',
+ *     states: {
+ *       active: { roving: true },            // 槽名 active → 默认后缀 '--active'
+ *       open: { aria: 'aria-expanded' },     // 布尔型（false 保留）
+ *     },
+ *   })
+ *   // 调用：
+ *   h('div', title({ active: isActive, open: popupOpen }, { onClick }), ...)
+ *   ```
+ *
+ * 槽语义（每槽独立）：
+ * - `suffix`（默认 `--${槽名}`；`false` = 无类面——roving-only 槽）
+ * - `aria` 布尔（槽真 → true · 假 → false **保留**——Menu popupOpen 原语义）
+ * - `ariaText` 文本（槽真 → value · 假 → undefined **移除**——NavMenu
+ *   hasChildren gated 原语义）
+ * - `roving`（槽真 → 0 · 假 → -1）
+ *
+ * 兼容：单槽便捷形态（states 未声明 = `{ active: {...} }`——boolean 调用
+ * 不变——既有 8 契约与 9 组件零改动）。
+ *
+ * 边界（诚实）：槽值是布尔——aria 多值枚举（Tree 'mixed' / Cascader
+ * String() 多态）仍在契约外（判负登记）；槽间互斥衍生态（TabBar
+ * disabled 与 active 互斥——disabled 槽有独立 suffix）按独立面处理。
+ */
+export interface ItemStateSlot {
+  /** 槽态类后缀（默认 `--${槽名}`；false = 无类面） */
+  suffix?: string | false
+  /** 槽态 aria 布尔键（真 → true · 假 → false 保留——内核归一） */
+  aria?: string
+  /** 槽态 aria 文本值（真 → value · 假 → undefined 移除） */
+  ariaText?: { key: string; value: string }
+  /** roving tabindex（真 → 0 · 假 → -1） */
+  roving?: boolean
+}
+
+/** 值域槽变体态（互斥单键多值——三态 checkbox 原型） */
+export interface ItemEnumVariant {
+  /** 类后缀（缺省无类面——input 型无状态类） */
+  suffix?: string
+  /** 写入 enum.key 的值（boolean | string——'mixed' 型） */
+  aria?: boolean | string
+  /** 附加 props（indeterminate/checked property 面——vdom property 通道） */
+  props?: Record<string, unknown>
+}
+
+/** 值域槽声明（互斥单值——'checked' | 'half' | null——替代多键布尔） */
+export interface ItemEnumDecl {
+  /** 共享 aria 键（如 'aria-checked'）——各态写入互斥值 */
+  key: string
+  /** 零值态（null 时：类无 · key=off.aria ?? false） */
+  off?: ItemEnumVariant
+  /** 值态（互斥——键名即调用值） */
+  values: Record<string, ItemEnumVariant>
+}
+
+export interface ItemStateDecl {
+  /** 基类（如 'wf-tab'）——槽态时派生 `cls + 槽后缀` */
+  cls: string
+  /** role（所有实例同值——如 'tab'/'option'） */
+  role?: string
+  /** 单槽便捷（等效 states: { active: {...} }——兼容既有用法） */
+  suffix?: string
+  aria?: string
+  ariaText?: { key: string; value: string }
+  roving?: boolean
+  /** 多状态槽（槽名 = 类后缀词干——'active' → '--active'） */
+  states?: Record<string, ItemStateSlot>
+  /** 值域槽（互斥单键多值——enum.key 写入各态 aria 值 + props 捆绑——
+   * 与 states 正交：states = 多键独立（Menu active+open）· enum = 单键互斥
+   * （三态 checkbox checked/half）） */
+  enum?: ItemEnumDecl
+}
+
+export type ItemStateArg = boolean | Record<string, boolean> | string | null | undefined
+
+/**
+ * 生成「交互元素状态 props」工厂——返回 (state, extra) => props。
+ * - 单槽（boolean 调用）：active=true 类带后缀 · aria 布尔 true · ariaText value
+ * - 多槽（对象调用）：每槽独立判定（类后缀 · aria · ariaText · roving）
+ * - 槽假值：aria 布尔 false（保留——与属性移除语义不同）· ariaText undefined（移除）
+ * - extra 后置 spread（extra 胜——扩展不用改声明）
+ * - **class 例外：extra.class 追加而非覆盖**（disabled/focus/variant 等
+ *   第二类面与状态后缀共存——覆盖会丢状态类——契约锁定合并语义）
+ */
+export function createItem(decl: ItemStateDecl) {
+  const { cls, role } = decl
+  const enumDecl = decl.enum
+  if (enumDecl !== undefined) {
+    const { key, off, values } = enumDecl
+    const offVariant: ItemEnumVariant = off ?? {}
+    return (state: ItemStateArg, extra: Record<string, unknown> = {}): Record<string, unknown> => {
+      const name = typeof state === 'string' ? state : null
+      const v = name !== null && values[name] ? values[name] : offVariant
+      const parts = [cls]
+      if (v.suffix) parts.push(cls + v.suffix)
+      const base = parts.join(' ')
+      const extraCls = extra.class
+      const classOut = extraCls
+        ? base + ' ' + (Array.isArray(extraCls) ? extraCls.filter(Boolean).join(' ') : extraCls)
+        : base
+      const { class: _omit, ...rest } = extra
+      const out: Record<string, unknown> = { class: classOut }
+      if (role) out.role = role
+      // aria 键：显式值（含 boolean/string/undefined）——undefined = 不写（Table 补
+      // aria 前的原语义）· off 兜底（含未知态名）默认 false（三态标准——
+      // 与属性移除语义不同——off.aria 可显式覆盖）
+      if (v.aria !== undefined) out[key] = v.aria
+      else if (v === offVariant) out[key] = offVariant.aria !== undefined ? offVariant.aria : false
+      if (v.props) Object.assign(out, v.props)
+      return { ...out, ...rest }
+    }
+  }
+  const multi = decl.states !== undefined
+  // 归一为槽表（单槽便捷 → 单一 active 槽）
+  type SlotNorm = { suffix: string | false; aria?: string; ariaText?: { key: string; value: string }; roving?: boolean }
+  const slots: Array<[string, SlotNorm]> = multi
+    ? Object.entries(decl.states!).map(([k, v]) => [k, {
+        suffix: v.suffix === undefined ? `--${k}` : v.suffix,
+        aria: v.aria, ariaText: v.ariaText, roving: v.roving,
+      }])
+    : [['active', {
+        suffix: decl.suffix ?? '--active',
+        aria: decl.aria, ariaText: decl.ariaText, roving: decl.roving,
+      } satisfies SlotNorm]]
+
+  return (state: ItemStateArg, extra: Record<string, unknown> = {}): Record<string, unknown> => {
+    // 单槽 boolean 直判；多槽对象取槽值（undefined → false）——enum 路径已在上方
+    // return（类型收窄：此处 state 仅 boolean | Record）
+    const st = state as boolean | Record<string, boolean>
+    const on = (name: string): boolean => typeof st === 'boolean' ? st : !!st[name]
+    const classParts = [cls]
+    for (const [name, slot] of slots) {
+      const act = on(name)
+      if (slot.suffix && act) classParts.push(cls + slot.suffix)
+    }
+    const base = classParts.join(' ')
+    const extraCls = extra.class
+    const classOut = extraCls
+      ? base + ' ' + (Array.isArray(extraCls) ? extraCls.filter(Boolean).join(' ') : extraCls)
+      : base
+    const { class: _omit, ...rest } = extra
+    const out: Record<string, unknown> = { class: classOut }
+    if (role) out.role = role
+    for (const [name, slot] of slots) {
+      const act = on(name)
+      if (slot.aria) out[slot.aria] = act
+      if (slot.ariaText) out[slot.ariaText.key] = act ? slot.ariaText.value : undefined
+      if (slot.roving) out.tabindex = act ? 0 : -1
+    }
+    return { ...out, ...rest }
+  }
+}

package/dist/level4/client/vdom/semantic.d.ts

@@ -0,0 +1,51 @@
+/**
+ * semantic —— 语义面原语（三面论·语义面——role 模板表）
+ *
+ * 为什么存在：组件的语义身份（role）携带**标准 aria 契约**（ARIA 1.2 角色
+ * 面）——dialog 必须 aria-modal · progressbar 必须 valuenow/min/max ·
+ * switch 必须 aria-checked。325 处手写 role/aria 面中，这些键面是**可模板化
+ * 的机械面**（键集固定——值组件特异）。
+ *
+ * 单源回报：role 模板表 ROLE_SEMANTICS 是角色契约的**唯一声明**——
+ * 契约测试扫描全库（组件用了 role 却缺键面 = 红——FileUpload/ToolCallCard
+ * progressbar 缺 valuemin 即被审计抓出）。键面归一（aria 布尔直传内核——
+ * 回馈 #1 后无手写三元）。
+ *
+ * 边界（诚实）：
+ * - aria-label 是成分面（值组件特异/i18n/插值）——labelable 只声明
+ *   "可被标注"的契约，值由组件传（不模板化值）
+ * - 非 ARIA 角色面（结构语义——navigation/main 的 landmark 面）走
+ *   结构面（h 直写——不模板化——landmark 值组件特异）
+ * - createItem 的 aria 槽是状态面（动态值）· semantic 的 keys 是契约面
+ *   （必备键集合）——正交：组件可同时用（progressbar 的 valuenow 若
+ *   动态也可走 createItem 的 enum/aria 面——两者收敛于同一键）
+ */
+/** 角色语义模板（ARIA 1.2 角色契约面摘要——28 角色） */
+export declare const ROLE_SEMANTICS: Record<string, {
+    /** 必备固定键（值常量——声明的角色即必须带） */
+    fixed?: Record<string, unknown>;
+    /** **必备键面**（ARIA 要求的最小契约——缺失 = 语义缺口——审计查这层） */
+    keys?: string[];
+    /** 条件键面（角色可能面——hasChildren/combobox 模式等——审计不查） */
+    optional?: string[];
+    /** labelable（aria-label/labelledby 连接面——值组件特异） */
+    labelable?: boolean;
+}>;
+export interface SemanticOpts {
+    /** aria-label 值（组件特异——labelable 面） */
+    label?: string;
+    /** aria-labelledby 引用（组件特异——labelable 面） */
+    labelledBy?: string;
+    /** aria-describedby 引用 */
+    describedBy?: string;
+    /** 键面值（role 的 keys——如 progressbar 的 valuenow） */
+    values?: Record<string, unknown>;
+}
+/**
+ * 语义面组装（纯函数）：role + 模板固定键 + 键面值 + labelable 连接。
+ * - 未知 role → 只 { role }（白名单外诚实——不静默造键）
+ * - label/labelledBy 互斥优先（显式 labelledBy > label > 无）
+ * - mode: 'strict'（模板 keys 缺值——缺失键不写（调用方决定——组件特异）
+ *   ——**契约审计扫描**保证键面（与语义缺口防线的分工）
+ */
+export declare function semantic(role: string, opts?: SemanticOpts): Record<string, unknown>;

package/dist/level4/client/vdom/semantic.ts

@@ -0,0 +1,113 @@
+/**
+ * semantic —— 语义面原语（三面论·语义面——role 模板表）
+ *
+ * 为什么存在：组件的语义身份（role）携带**标准 aria 契约**（ARIA 1.2 角色
+ * 面）——dialog 必须 aria-modal · progressbar 必须 valuenow/min/max · 
+ * switch 必须 aria-checked。325 处手写 role/aria 面中，这些键面是**可模板化
+ * 的机械面**（键集固定——值组件特异）。
+ *
+ * 单源回报：role 模板表 ROLE_SEMANTICS 是角色契约的**唯一声明**——
+ * 契约测试扫描全库（组件用了 role 却缺键面 = 红——FileUpload/ToolCallCard
+ * progressbar 缺 valuemin 即被审计抓出）。键面归一（aria 布尔直传内核——
+ * 回馈 #1 后无手写三元）。
+ *
+ * 边界（诚实）：
+ * - aria-label 是成分面（值组件特异/i18n/插值）——labelable 只声明
+ *   "可被标注"的契约，值由组件传（不模板化值）
+ * - 非 ARIA 角色面（结构语义——navigation/main 的 landmark 面）走
+ *   结构面（h 直写——不模板化——landmark 值组件特异）
+ * - createItem 的 aria 槽是状态面（动态值）· semantic 的 keys 是契约面
+ *   （必备键集合）——正交：组件可同时用（progressbar 的 valuenow 若
+ *   动态也可走 createItem 的 enum/aria 面——两者收敛于同一键）
+ */
+
+/** 角色语义模板（ARIA 1.2 角色契约面摘要——28 角色） */
+export const ROLE_SEMANTICS: Record<string, {
+  /** 必备固定键（值常量——声明的角色即必须带） */
+  fixed?: Record<string, unknown>
+  /** **必备键面**（ARIA 要求的最小契约——缺失 = 语义缺口——审计查这层） */
+  keys?: string[]
+  /** 条件键面（角色可能面——hasChildren/combobox 模式等——审计不查） */
+  optional?: string[]
+  /** labelable（aria-label/labelledby 连接面——值组件特异） */
+  labelable?: boolean
+}> = {
+  // 窗口/弹层
+  dialog: { fixed: { 'aria-modal': true }, labelable: true },
+  alertdialog: { fixed: { 'aria-modal': true }, labelable: true },
+  // 进度/滑杆（数值面）
+  progressbar: { keys: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax'], labelable: true },
+  slider: { keys: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax'], labelable: true },
+  scrollbar: { keys: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax'], labelable: true },
+  // 选择类（布尔状态面）
+  switch: { keys: ['aria-checked'], labelable: true },
+  radio: { keys: ['aria-checked'], labelable: true },
+  checkbox: { keys: ['aria-checked'], labelable: true },
+  option: { keys: ['aria-selected'], labelable: true },
+  tab: { keys: ['aria-selected'], labelable: true },
+  menuitem: { keys: [], optional: ['aria-haspopup', 'aria-expanded', 'aria-current'], labelable: true },
+  treeitem: { keys: [], optional: ['aria-level', 'aria-selected', 'aria-expanded', 'aria-checked'], labelable: true },
+  // 容器（labelable——命名面）
+  group: { labelable: true },
+  listbox: { labelable: true },
+  combobox: { keys: ['aria-expanded'], optional: ['aria-controls', 'aria-activedescendant'], labelable: true },
+  menu: { labelable: true },
+  tablist: { labelable: true },
+  radiogroup: { labelable: true },
+  toolbar: { labelable: true },
+  navigation: { labelable: true },
+  menubar: { labelable: true },
+  tabpanel: { optional: ['aria-labelledby'], labelable: true },
+  // 图文（label 面）
+  img: { labelable: true },
+  // 嵌入（iframe 面）
+  article: { labelable: true },
+  // 活区
+  status: { labelable: true },
+  alert: { labelable: true },
+  // 原语（键面少或无）
+  button: { labelable: true },
+  link: { labelable: true },
+  separator: {},
+  tooltip: {},
+  tree: { labelable: true },
+  list: { labelable: true },
+}
+
+export interface SemanticOpts {
+  /** aria-label 值（组件特异——labelable 面） */
+  label?: string
+  /** aria-labelledby 引用（组件特异——labelable 面） */
+  labelledBy?: string
+  /** aria-describedby 引用 */
+  describedBy?: string
+  /** 键面值（role 的 keys——如 progressbar 的 valuenow） */
+  values?: Record<string, unknown>
+}
+
+/**
+ * 语义面组装（纯函数）：role + 模板固定键 + 键面值 + labelable 连接。
+ * - 未知 role → 只 { role }（白名单外诚实——不静默造键）
+ * - label/labelledBy 互斥优先（显式 labelledBy > label > 无）
+ * - mode: 'strict'（模板 keys 缺值——缺失键不写（调用方决定——组件特异）
+ *   ——**契约审计扫描**保证键面（与语义缺口防线的分工）
+ */
+export function semantic(role: string, opts: SemanticOpts = {}): Record<string, unknown> {
+  const tpl = ROLE_SEMANTICS[role]
+  const out: Record<string, unknown> = { role }
+  if (tpl?.fixed) Object.assign(out, tpl.fixed)
+  const allKeys = [...(tpl?.keys ?? []), ...(tpl?.optional ?? [])]
+  if (allKeys.length) {
+    for (const k of allKeys) {
+      const v = opts.values?.[k]
+      if (v !== undefined) out[k] = v
+    }
+  }
+  const label = opts.labelledBy ?? opts.label
+  if (tpl?.labelable && label !== undefined) {
+    if (opts.labelledBy !== undefined) out['aria-labelledby'] = opts.labelledBy
+    else out['aria-label'] = opts.label
+  }
+  if (opts.describedBy !== undefined) out['aria-describedby'] = opts.describedBy
+  return out
+}

package/dist/level4/server/db/body.d.ts

@@ -0,0 +1,31 @@
+/**
+ * weifuwu/db — bodyOf（shape → body 校验——handler 样板消失）
+ *
+ * 开发者动线（W0 体验提升）：shape 已知全部字段——handler 的 body 不再
+ * 手写类型/必填/枚举校验。parseBody 复用 insertSchema/updateSchema 变体
+ * （auto 列省略 · nullable/default 可缺省 · enum 校验）——与 orm 单源。
+ *
+ * 用法（手写 route——与 gql/rest 协议面同源）：
+ *   const body = await bodyOf(req, agents)            // BodyOf<typeof agents>
+ *   const patch = await bodyOf(req, agents, { variant: 'patch' })  // PatchOf
+ *
+ * 错误语义：ValidationError（400 面——错误消息含字段路径/期望——errorOf
+ * 映射；校验失败不抛原始 ZodError 噪音——可读优先）。
+ */
+import type { ZodRawShape } from '../../../level0/zod.ts';
+import type { Shape, BodyOf } from '../../../level0/db/shape.ts';
+export interface BodyOfOptions {
+    /** insert（缺省——裸行 body——省略 auto）· patch（全可选——部分更新） */
+    variant?: 'insert' | 'patch';
+    /** 系统列（租户/服务端注入面）——校验前剔除（不变式：注入列声明面权威——
+     *  body 传该键被忽略而非校验——W4 试点（agents app_id）实证） */
+    omit?: string[];
+}
+type ShapeLike<S extends ZodRawShape> = Shape<S> | {
+    __shape: import('../../../level0/db/shape.ts').Shape<S>;
+};
+/** 请求体 → 类型化输入行（shape 变体校验——enum/必填/nullable/auto 省略）。
+ *  命名纪律：parseBody（request.ts）是通用 JSON 解析——bodyOf 是 shape 校验面（一个词一个概念） */
+export declare function bodyOf<S extends ZodRawShape>(req: Request, shapeDef: ShapeLike<S>, opts?: BodyOfOptions): Promise<BodyOf<S>>;
+/** body 输入行类型快捷（parseBody 返回面——语义对等导出） */
+export type { BodyOf, PatchOf } from '../../../level0/db/shape.ts';