weifuwu 0.94.0 → 0.95.0

package/dist/level5/client/components/AutoComplete/AutoComplete.d.ts

@@ -0,0 +1,40 @@
+/** AutoComplete：输入联想：自由输入 + 过滤下拉 + 键盘流 + 选中回填（showcase /components/autocomplete） */
+/**
+ * weifuwu/client/components — AutoComplete 输入联想
+ *
+ * 三库等价：antd AutoComplete / EP Autocomplete / shadcn Combobox（输入侧）。
+ * 自由输入 + 实时联想下拉：包含匹配（不区分大小写）、键盘 ↓↑/Enter/Escape、
+ * 选中回填。与 Select 区别：Select 选固定选项，AutoComplete 输入是自由值。
+ *
+ *   <AutoComplete
+ *     options={[{ value: 'pay', label: '支付平台' }]}
+ *     value={query} onChange={setQuery}
+ *   />
+ *
+ * 裁剪（CS-05，见 docs/client.md）：不做分组/虚拟化候选（Select searchable 覆盖分组场景）；
+ * 自定义渲染用 `renderOption` 透传。
+ */
+import type { Component, VNodeChild } from '../../../../level6/client/vdom/index.ts';
+export interface AutoCompleteOption {
+    value: string;
+    label?: VNodeChild;
+    disabled?: boolean;
+}
+export interface AutoCompleteProps {
+    options: AutoCompleteOption[];
+    value?: string;
+    onChange?: (value: string) => void;
+    placeholder?: string;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    disabled?: boolean;
+    /** 错误态（F2 状态矩阵——输入类基线） */
+    error?: string;
+    /** 过滤函数（默认包含匹配） */
+    filter?: (options: AutoCompleteOption[], query: string) => AutoCompleteOption[];
+    renderOption?: (option: AutoCompleteOption) => any;
+    onSelect?: (value: string, option: AutoCompleteOption) => void;
+}
+/** 默认过滤：label/value 包含匹配，不区分大小写（纯函数——可单测/SSR） */
+export declare function filterOptions(options: AutoCompleteOption[], query: string): AutoCompleteOption[];
+export declare const AutoComplete: Component<AutoCompleteProps>;

package/dist/level5/client/components/AutoComplete/AutoComplete.ts

@@ -0,0 +1,221 @@
+/** AutoComplete：输入联想：自由输入 + 过滤下拉 + 键盘流 + 选中回填（showcase /components/autocomplete） */
+/**
+ * weifuwu/client/components — AutoComplete 输入联想
+ *
+ * 三库等价：antd AutoComplete / EP Autocomplete / shadcn Combobox（输入侧）。
+ * 自由输入 + 实时联想下拉：包含匹配（不区分大小写）、键盘 ↓↑/Enter/Escape、
+ * 选中回填。与 Select 区别：Select 选固定选项，AutoComplete 输入是自由值。
+ *
+ *   <AutoComplete
+ *     options={[{ value: 'pay', label: '支付平台' }]}
+ *     value={query} onChange={setQuery}
+ *   />
+ *
+ * 裁剪（CS-05，见 docs/client.md）：不做分组/虚拟化候选（Select searchable 覆盖分组场景）；
+ * 自定义渲染用 `renderOption` 透传。
+ */
+
+import type {Component, VNodeChild} from '../../../../level6/client/vdom/index.ts'
+import type { UIContext } from '../../../../level6/client/vdom/index.ts'
+import { h } from '../../../../level6/client/vdom/index.ts'
+
+export interface AutoCompleteOption {
+  value: string
+  label?: VNodeChild
+  disabled?: boolean
+}
+
+export interface AutoCompleteProps {
+  options: AutoCompleteOption[]
+  value?: string
+  onChange?: (value: string)=> void
+  placeholder?: string
+  open?: boolean
+  onOpenChange?: (open: boolean)=> void
+  disabled?: boolean
+  /** 错误态（F2 状态矩阵——输入类基线） */
+  error?: string
+  /** 过滤函数（默认包含匹配） */
+  filter?: (options: AutoCompleteOption[], query: string)=> AutoCompleteOption[]
+  renderOption?: (option: AutoCompleteOption)=> any
+  onSelect?: (value: string, option: AutoCompleteOption)=> void
+}
+
+/** 默认过滤：label/value 包含匹配，不区分大小写（纯函数——可单测/SSR） */
+export function filterOptions(options: AutoCompleteOption[], query: string): AutoCompleteOption[] {
+  const q = query.trim().toLowerCase()
+  if (!q) return options
+  return options.filter(o => {
+    const label = String(o.label ?? o.value).toLowerCase()
+    return label.includes(q) || o.value.toLowerCase().includes(q)
+  })
+}
+
+export const AutoComplete: Component<AutoCompleteProps> = (_init, ctx: UIContext)=> {
+  // render-only：内部状态 let + 显式 render（open 经闭包绑定——§4.5 无 this 陷阱）；
+  // keyword/selected 由 useControlledInput 管理（render 层调用——C3 原语）
+  let open = _init?.open ?? false
+  let activeIndex = -1
+  let latestValue = _init?.value ?? ''
+  let latestOnChange: ((v: string)=> void) | undefined
+  let latestOpen: boolean | undefined = _init?.open
+  let latestOnOpenChange: ((v: boolean)=> void) | undefined
+  let latestOnSelect: ((v: string, o: AutoCompleteOption)=> void) | undefined
+  let wrapEl: HTMLElement | null = null
+  const wrapRef = (el: HTMLElement | null)=> { if (el) wrapEl = el }
+
+  // 命令式弹窗（唯一形态 openPopup）：定位 + 打开自动 refresh + 锚点感知 +
+  // Escape + 外部点击（弹窗纪律——此前普通 fixed div + 手动
+  // usePopupPosition：pos 初始 0 且打开不 refresh → 下拉 0,0 宽 0 不可见）
+  /** 命令式句柄（唯一形态——openPopup——组件内部同步样板） */
+  let handle: import('../../../../level3/vdom/hooks/popup-manager.ts').PopupHandle | null = null
+  const syncDropdown = (dropdown: import('../../../../level6/client/vdom/index.ts').VNode | null): void => {
+    if (open && !handle)
+      handle = ctx.ui.openPopup({
+        key: 'wf-autocomplete',
+        anchor: ()=> wrapEl,
+        placement: 'bottom',
+        center: false, // 左对齐输入框
+        gap: 4,
+        content: ()=> dropdown,
+        onClose: ()=> {
+          handle = null
+          if (open) {
+            open = false
+            ctx.render() // 显式渲染（外部点击/Escape 关闭必须落地）
+            latestOnOpenChange?.(false)
+          }
+        },
+      })
+    else if (!open && handle) { handle.close(); handle = null }
+    else if (handle) handle.update(dropdown)
+  }
+
+  const setOpen = (v: boolean)=> {
+    open = v
+    ctx.render()
+    latestOnOpenChange?.(v)
+  }
+
+  // useControlledInput 原语句柄（render 层调用——闭包变量供 pick 用）
+  let inputCtrl: ReturnType<UIContext['ui']['useControlledInput']> | null = null
+
+  const pick = (option: AutoCompleteOption)=> {
+    inputCtrl?.setValue(option.value)
+    latestOnSelect?.(option.value, option)
+    inputCtrl?.setKeyword('')
+    inputCtrl?.setSelectedLabel(String(option.label ?? option.value)) // 关闭后回填（label 可 VNodeChild——转字符串）
+    activeIndex = -1
+    setOpen(false)
+  }
+
+  // ── render（每次 dirty/props 变化）──
+  return (props: AutoCompleteProps)=> {
+    const { options, value, placeholder = '输入搜索…', disabled, error, renderOption, onSelect } = props
+    // C3 原语：受控 value + 内部输入态/选中态（render 阶段调用——读最新 props）
+    inputCtrl = ctx.ui.useControlledInput({ value, onChange: props.onChange, name: 'AutoComplete' })
+    const keyword = inputCtrl.keyword
+    const selectedLabel = inputCtrl.selectedLabel
+    latestValue = value ?? ''
+    latestOnChange = props.onChange
+    latestOpen = props.open
+    latestOnOpenChange = props.onOpenChange
+    latestOnSelect = onSelect
+    if (props.open !== undefined) open = !!props.open // renderFn 内同步受控值——本次渲染读新值
+
+    // 打开时输入态优先（keyword——用户正在输入）；无输入回退受控值
+    const query = open ? (keyword || latestValue) : latestValue
+    const filtered = (props.filter ?? filterOptions)(options, query)
+    if (activeIndex >= filtered.length) activeIndex = -1
+
+    // IME 组合（中文拼音）：组合期间不处理 onChange/不重渲染——
+    // 否则受控 value 重置打断输入法（Mentions/TagsInput 同款纪律）
+    let composing = false
+    const onInput = (e: any)=> {
+      if (composing || e.isComposing) return
+      const v = e.target.value
+      inputCtrl?.setKeyword(v) // C3 内部输入态（不依赖受控 value 回流）
+      inputCtrl?.setValue(v)
+      // **输入驱动渲染（2027-XX——过滤不更新实证修复）**：open 已开时此前
+      // 不重渲染——dropdown content 停留在首次闭包 vnode（过滤失效——输入
+      // 「支付」仍显示全量 5 条）。open 已开也必须 render（filtered 随输入更新）
+      if (!open) setOpen(true)
+      else ctx.render()
+      activeIndex = -1
+    }
+    const onCompositionStart = ()=> { composing = true }
+    const onCompositionEnd = (e: any)=> {
+      composing = false
+      // 组合完成：处理最终中文值（过滤/回填）
+      const v = (e.target as HTMLInputElement)?.value ?? ''
+      inputCtrl?.setKeyword(v)
+      inputCtrl?.setValue(v)
+      if (!open) setOpen(true)
+    }
+
+    const onKeyDown = (e: any)=> {
+      if (!open && (e.key === 'ArrowDown' || e.key === 'ArrowUp')) {
+        e.preventDefault()
+        setOpen(true)
+        activeIndex = e.key === 'ArrowDown' ? 0 : filtered.length - 1
+        return
+      }
+      if (e.key === 'ArrowDown') {
+        e.preventDefault()
+        activeIndex = (activeIndex + 1) % filtered.length
+        ctx.render()
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault()
+        activeIndex = activeIndex <= 0 ? filtered.length - 1 : activeIndex - 1
+        ctx.render()
+      } else if (e.key === 'Enter') {
+        if (open && activeIndex >= 0 && filtered[activeIndex]) {
+          e.preventDefault()
+          pick(filtered[activeIndex])
+        }
+      } else if (e.key === 'Escape') {
+        e.preventDefault()
+        setOpen(false)
+      }
+    }
+
+    const dropdown = h('div', {
+      class: 'wf-autocomplete-dropdown',
+    }, filtered.map((opt, i)=>
+      h('div', {
+        class: `wf-autocomplete-option${i === activeIndex ? ' wf-autocomplete-option--active' : ''}`,
+        key: opt.value,
+        onMouseDown: (e: any)=> {
+          e.stopPropagation()
+          if (!opt.disabled) pick(opt)
+        },
+      }, renderOption ? renderOption(opt) : (opt.label ?? opt.value)),
+    ))
+
+    const vn = h('div', { class: 'wf-autocomplete-wrap', ref: wrapRef }, [
+      h('input', {
+        // C1 修复后：portal 内部 key 不算用户 keyed → allUnkeyed 按位置复用
+        // input 不重建（此前需手动 key 防焦点丢失——现已治本）
+        class: ['wf-autocomplete-input wf-input', error ? ' wf-autocomplete-input--err' : ''].filter(Boolean).join(' '),
+        'aria-invalid': error ? 'true' : undefined,
+        role: 'combobox',
+        'aria-haspopup': 'listbox',
+        'aria-expanded': String(open),
+        // 打开/输入时显示内部 keyword；关闭时选中 label（无选中回退受控值）
+        value: open ? keyword : (selectedLabel || query),
+        placeholder,
+        disabled,
+        onInput,
+        onKeyDown,
+        onCompositionStart,
+        onCompositionEnd,
+        onFocus: ()=> { if (!open) setOpen(true) },
+      }),
+      // 错误文案（F2 输入类基线——2027-XX 补齐：此前只有错误类/aria 无文案面）
+      error ? h('div', { class: 'wf-input-err' }, error) : null,
+    ])
+    // 命令式同步（受控 + 内容更新——每次渲染恒调用）
+    syncDropdown(dropdown)
+    return vn
+  }
+}

package/dist/level5/client/components/Avatar/Avatar.css

@@ -0,0 +1,18 @@
+/* weifuwu/client/components — Avatar */
+
+.wf-avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  font-family: var(--wf-font-sans);
+  font-weight: var(--wf-font-weight-semibold);
+  color: var(--wf-color-on-brand);
+  flex-shrink: 0;
+  overflow: hidden;
+  object-fit: cover;
+}
+
+.wf-avatar--sm { width: 24px; height: 24px; font-size: 11px; }
+.wf-avatar--md { width: 32px; height: 32px; font-size: 13px; }
+.wf-avatar--lg { width: 40px; height: 40px; font-size: 16px; }

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

@@ -0,0 +1,10 @@
+/** Avatar：头像（首字母/图片），3 种 size（showcase /components/avatar） */
+import type { Component } from '../../../../level6/client/vdom/index.ts';
+export interface AvatarProps {
+    name?: string;
+    src?: string;
+    size?: 'sm' | 'md' | 'lg';
+    /** 指定背景色（覆盖按名字哈希的颜色），如按类型着色：user=蓝 / ai=紫 */
+    color?: string;
+}
+export declare const Avatar: Component<AvatarProps>;

package/dist/level5/client/components/Avatar/Avatar.ts

@@ -0,0 +1,42 @@
+/** Avatar：头像（首字母/图片），3 种 size（showcase /components/avatar） */
+import type { Component } from '../../../../level6/client/vdom/index.ts'
+import type { UIContext } from '../../../../level6/client/vdom/index.ts'
+import { h } from '../../../../level6/client/vdom/index.ts'
+
+export interface AvatarProps {
+  name?: string
+  src?: string
+  size?: 'sm' | 'md' | 'lg'
+  /** 指定背景色（覆盖按名字哈希的颜色），如按类型着色：user=蓝 / ai=紫 */
+  color?: string
+}
+
+const COLORS = ['#4f6ef7', '#22c55e', '#f59e0b', '#ef4444', '#8b5cf6', '#06b6d4', '#ec4899']
+
+function hashColor(name: string): string {
+  let hash = 0
+  for (let i = 0; i < name.length; i++) hash = name.charCodeAt(i) + ((hash << 5) - hash)
+  return COLORS[Math.abs(hash) % COLORS.length]
+}
+
+export const Avatar: Component<AvatarProps> = (_init, _ctx)=>
+  (props)=> {
+  const { name = '', src, size = 'md', color } = props
+  // 按码点取首字符（Array.from 而非 name[0]）——emoji 是代理对，name[0]
+  // 会切出孤立代理项（\ud83d 等），写入文本节点会让 Chrome 的 AX 树/布局
+  // 计算挂死（agent-platform 部门页整页 a11y snapshot 挂死/为空的根因）
+  const initial = Array.from(name.trim())[0]?.toUpperCase() ?? '?'
+
+  if (src) {
+    return h('img', {
+      class: `wf-avatar wf-avatar--${size}`,
+      src,
+      alt: name,
+    })
+  }
+
+  return h('div', {
+    class: `wf-avatar wf-avatar--${size}`,
+    style: { background: color ?? hashColor(name) },
+  }, initial)
+}

package/dist/level5/client/components/AvatarGroup/AvatarGroup.css

@@ -0,0 +1,29 @@
+/* weifuwu/client/components — AvatarGroup */
+
+.wf-avatar-group {
+  display: inline-flex;
+  align-items: center;
+}
+
+.wf-avatar-group-item {
+  margin-left: -6px;
+}
+.wf-avatar-group-item:first-child {
+  margin-left: 0;
+}
+
+.wf-avatar-group-more {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  border-radius: 50%;
+  margin-left: -6px;
+  background: var(--wf-color-bg-tertiary);
+  border: 2px solid var(--wf-color-bg);
+  font-size: var(--wf-font-size-xs);
+  font-weight: var(--wf-font-weight-semibold);
+  color: var(--wf-color-text-secondary);
+  font-family: var(--wf-font-sans);
+}

package/dist/level5/client/components/AvatarGroup/AvatarGroup.d.ts

@@ -0,0 +1,22 @@
+/** AvatarGroup：头像组：堆叠 + max 溢出 +N（showcase /components/avatargroup） */
+/**
+ * weifuwu/client/components — AvatarGroup
+ *
+ * 堆叠头像组（负 margin 重叠）+ max 溢出显示 +N。
+ * 用于群聊成员、协作人列表。
+ * 裁剪（CS-05，见 docs/client.md）：hover 展开 tooltip（Tooltip 可组合）。
+ */
+import type { Component } from '../../../../level6/client/vdom/index.ts';
+import { type AvatarProps } from '../Avatar/Avatar.ts';
+export interface AvatarGroupItem {
+    name?: string;
+    src?: string;
+    color?: string;
+}
+export interface AvatarGroupProps {
+    items: AvatarGroupItem[];
+    max?: number;
+    size?: AvatarProps['size'];
+    className?: string;
+}
+export declare const AvatarGroup: Component<AvatarGroupProps>;

package/dist/level5/client/components/AvatarGroup/AvatarGroup.ts

@@ -0,0 +1,46 @@
+/** AvatarGroup：头像组：堆叠 + max 溢出 +N（showcase /components/avatargroup） */
+/**
+ * weifuwu/client/components — AvatarGroup
+ *
+ * 堆叠头像组（负 margin 重叠）+ max 溢出显示 +N。
+ * 用于群聊成员、协作人列表。
+ * 裁剪（CS-05，见 docs/client.md）：hover 展开 tooltip（Tooltip 可组合）。
+ */
+
+import type { Component } from '../../../../level6/client/vdom/index.ts'
+import type { UIContext } from '../../../../level6/client/vdom/index.ts'
+import { h } from '../../../../level6/client/vdom/index.ts'
+import { Avatar, type AvatarProps } from '../Avatar/Avatar.ts'
+
+export interface AvatarGroupItem {
+  name?: string
+  src?: string
+  color?: string
+}
+
+export interface AvatarGroupProps {
+  items: AvatarGroupItem[]
+  max?: number
+  size?: AvatarProps['size']
+  className?: string
+}
+
+export const AvatarGroup: Component<AvatarGroupProps> = (_init, _ctx)=>
+  (props)=> {
+    const { items, max, size, className } = props
+    if (!items || items.length === 0) return null
+
+    const visible = max && items.length > max ? items.slice(0, max) : items
+    const hiddenCount = max ? Math.max(0, items.length - max) : 0
+
+    const avatars = visible.map((it, i)=>
+      h('span', { key: i, class: 'wf-avatar-group-item' },
+        h(Avatar, { name: it.name, src: it.src, color: it.color, size })))
+
+    const more = hiddenCount > 0
+      ? h('span', { class: 'wf-avatar-group-more', role: 'img', 'aria-label': `还有 ${hiddenCount} 人` }, `+${hiddenCount}`)
+      : null
+
+    return h('div', { class: `wf-avatar-group${className ? ` ${className}` : ''}` },
+      [...avatars, more].filter(Boolean))
+  }

package/dist/level5/client/components/BackTop/BackTop.css

@@ -0,0 +1,47 @@
+/* weifuwu/client/components — BackTop */
+
+.wf-backtop {
+  position: fixed;
+  right: var(--wf-space-lg);
+  bottom: var(--wf-space-lg);
+  z-index: var(--wf-z-popover);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 40px;
+  height: 40px;
+  border-radius: var(--wf-radius);
+  border: none;
+  background: var(--wf-color-bg-secondary);
+  color: var(--wf-color-text-secondary);
+  cursor: pointer;
+  box-shadow: var(--wf-shadow-sm);
+  transition: opacity var(--wf-dur-base) var(--wf-ease-out),
+              transform var(--wf-dur-base) var(--wf-ease-out),
+              background var(--wf-dur-fast) var(--wf-ease-out),
+              visibility var(--wf-dur-base) var(--wf-ease-out);
+}
+
+.wf-backtop:hover {
+  background: var(--wf-color-bg-tertiary);
+  color: var(--wf-color-text);
+}
+
+.wf-backtop:focus-visible {
+  outline: none;
+  box-shadow: var(--wf-focus-ring);
+}
+
+.wf-backtop--hidden {
+  opacity: 0;
+  /* visibility：不可见按钮不得可 Tab 聚焦（a11y——浮钮语义：隐藏即不可达；
+     加入 transition 使收起时 opacity 先动画完再隐藏——展开立即可见） */
+  visibility: hidden;
+  pointer-events: none;
+  transform: translateY(8px);
+}
+
+/* 容器内浮钮（direction=bottom 聊天流——absolute 相对滚动容器——定位偏移同 fixed） */
+.wf-backtop--inline {
+  position: absolute;
+}

package/dist/level5/client/components/BackTop/BackTop.d.ts

@@ -0,0 +1,24 @@
+/** BackTop：回到顶部（滚动超 400px 显示）+ 固定导航（距顶 80px 钉住）（showcase /components/backtop） */
+import type { Component, VNodeChild } from '../../../../level6/client/vdom/index.ts';
+export interface BackTopProps {
+    /** 滚动超过此高度显示（px），默认 400 */
+    visibilityHeight?: number;
+    /** 滚动容器（默认 window；未就绪返回 null——attach 等待 render 重试） */
+    target?: () => HTMLElement | Window | null;
+    /** 平滑滚动，默认 true */
+    smooth?: boolean;
+    /** 方向（默认 'top'——回顶；'bottom'——聊天流回底浮钮） */
+    direction?: 'top' | 'bottom';
+    /** fixed 定位（默认 true——页面级）；容器内浮钮传 false（absolute——祖先需 position:relative） */
+    fixed?: boolean;
+    'aria-label'?: string;
+    children?: VNodeChild;
+    className?: string;
+}
+/** 回到顶部/底部（对应 EP Backtop / antd FloatButton.BackTop）：滚动超阈值显示，点击回位
+ *
+ * 实现：scroll 监听（window/容器统一——阈值翻转才重渲染——无轮询无 IO）。
+ * 历史：IO 哨兵方案（useInView 观察 absolute 哨兵）在「容器滚动 + 组件渲染在
+ * 容器外」组合失效（sentinel 固定于 root 可视区——isIn 恒 true——浮钮永不显示——
+ * agent-browser 实测 2026-09）——chat 首用暴露——统一 scroll 监听。 */
+export declare const BackTop: Component<BackTopProps>;

package/dist/level5/client/components/BackTop/BackTop.ts

@@ -0,0 +1,100 @@
+/** BackTop：回到顶部（滚动超 400px 显示）+ 固定导航（距顶 80px 钉住）（showcase /components/backtop） */
+import type {Component, VNodeChild} from '../../../../level6/client/vdom/index.ts'
+import type { UIContext } from '../../../../level6/client/vdom/index.ts'
+import { h } from '../../../../level6/client/vdom/index.ts'
+import { Icon } from '../Icon/Icon.ts'
+
+export interface BackTopProps {
+  /** 滚动超过此高度显示（px），默认 400 */
+  visibilityHeight?: number
+  /** 滚动容器（默认 window；未就绪返回 null——attach 等待 render 重试） */
+  target?: ()=> HTMLElement | Window | null
+  /** 平滑滚动，默认 true */
+  smooth?: boolean
+  /** 方向（默认 'top'——回顶；'bottom'——聊天流回底浮钮） */
+  direction?: 'top' | 'bottom'
+  /** fixed 定位（默认 true——页面级）；容器内浮钮传 false（absolute——祖先需 position:relative） */
+  fixed?: boolean
+  'aria-label'?: string
+  children?: VNodeChild
+  className?: string
+}
+
+type Scroller = HTMLElement | Window
+
+/** 回到顶部/底部（对应 EP Backtop / antd FloatButton.BackTop）：滚动超阈值显示，点击回位
+ *
+ * 实现：scroll 监听（window/容器统一——阈值翻转才重渲染——无轮询无 IO）。
+ * 历史：IO 哨兵方案（useInView 观察 absolute 哨兵）在「容器滚动 + 组件渲染在
+ * 容器外」组合失效（sentinel 固定于 root 可视区——isIn 恒 true——浮钮永不显示——
+ * agent-browser 实测 2026-09）——chat 首用暴露——统一 scroll 监听。 */
+export const BackTop: Component<BackTopProps> = (_init, ctx)=> {
+  // ── mount（只一次）──
+  let scroller: Scroller | null = null
+  // 状态原语（set 自动重渲染——滚动手势触发渲染无手动 render）
+  const visible = ctx.ui.useSignal(false)
+  let win: Window | null = null
+  const propsRef: any = {}
+
+  const handler = ()=> {
+    const v = propsRef.visibilityHeight ?? 400
+    const next = scroller === win
+      ? (win as Window).scrollY > v
+      : ((scroller as HTMLElement).scrollHeight - (scroller as HTMLElement).scrollTop - (scroller as HTMLElement).clientHeight) > v
+    if (next !== visible.get()) visible.set(next)
+  }
+
+  const attach = ()=> {
+    if (scroller) return // 幂等——render 重试机制防重复 listener
+    const tFn = propsRef.target
+    if (tFn && !tFn()) return // target 声明但未就绪（ref 时序）——每次 render 重试
+    // **浏览器环境纪律（§5.5）**：经 ctx.browser 注入——零全局 window/document
+    // 直接访问（SSR node 无 window——直接引用 = renderFn 抛错 → hole 降级 →
+    // SSR 吸收失败链——backtop 页实证 2027-xx——本次修复根因）
+    win = ctx.browser?.window ?? null
+    if (!win) return // SSR/测试（无浏览器）——不绑定——render 恒隐（客户端首帧后重试）
+    scroller = (tFn ? tFn() : win) as Scroller
+    scroller.addEventListener('scroll', handler, { passive: true })
+    handler() // 初始状态
+  }
+
+  ctx.ui.hold(()=> {
+    scroller?.removeEventListener('scroll', handler)
+    scroller = null
+  })
+
+  return (props)=> {
+    Object.assign(propsRef, props)
+    // attach 需在 target 就绪后：ref（app 层）在 apply 阶段设置——build 期读取为
+    // undefined → 回退 window——容器滚动永不触发（agent-browser 实测 2026-09）。
+    // 每次 render 重试：bodyEl 就绪后的下一次 render 必命中（无 rAF——不可靠）
+    attach()
+    const {
+      direction = 'top', smooth = true, 'aria-label': ariaLabel, children,
+      className, fixed = true,
+    } = props
+    const isBottom = direction === 'bottom'
+    const r = ()=> {
+      if (!scroller) return 0
+      return scroller === win
+        ? (win as Window).document.documentElement.scrollHeight
+        : (scroller as HTMLElement).scrollHeight
+    }
+
+    return h('button', {
+      type: 'button',
+      class: [
+        'wf-backtop',
+        fixed ? '' : 'wf-backtop--inline',
+        visible.get() ? '' : 'wf-backtop--hidden',
+        className,
+      ].filter(Boolean).join(' '),
+      'aria-label': ariaLabel ?? (isBottom ? '回到底部' : '回到顶部'),
+      onClick: ()=> {
+        if (!scroller) return
+        const top = isBottom ? r() : 0
+        ;(scroller as unknown as { scrollTo: (o: { top: number; behavior: ScrollBehavior })=> void }).scrollTo({ top, behavior: smooth ? 'smooth' : 'auto' })
+      },
+    }, children ?? h(Icon, { name: isBottom ? 'arrow-down' : 'arrow-up', size: 16 }))
+  }
+}

package/dist/level5/client/components/Badge/Badge.css

@@ -0,0 +1,49 @@
+/* weifuwu/client/components — Badge */
+
+.wf-badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 2px var(--wf-space-sm);
+  border-radius: var(--wf-badge-radius,  10px);
+  font-family: var(--wf-font-sans);
+  font-size: var(--wf-font-size-xs);
+  font-weight: var(--wf-font-weight-medium);
+  line-height: 1.4;
+  white-space: nowrap;
+}
+
+.wf-badge--default { background: var(--wf-color-bg-tertiary); color: var(--wf-color-text-secondary); }
+.wf-badge--primary { background: var(--wf-color-primary-bg); color: var(--wf-color-primary-text); }
+.wf-badge--success { background: var(--wf-color-success-bg); color: var(--wf-color-success-text); }
+.wf-badge--warning { background: var(--wf-color-warning-bg); color: var(--wf-color-warning-text); }
+.wf-badge--danger { background: var(--wf-color-error-bg); color: var(--wf-color-error-text); }
+.wf-badge--info { background: var(--wf-color-info-bg); color: var(--wf-color-info-text); }
+
+/* Dot variant */
+.wf-badge-dot {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+}
+
+.wf-badge-dot--default { background: var(--wf-color-text-tertiary); }
+.wf-badge-dot--primary { background: var(--wf-color-primary); }
+.wf-badge-dot--success { background: var(--wf-color-success); }
+.wf-badge-dot--warning { background: var(--wf-color-warning); }
+.wf-badge-dot--danger { background: var(--wf-color-error); }
+.wf-badge-dot--info { background: var(--wf-color-info); }
+
+/* 数值角标（count 模式）：圆形，最小宽度保证 2 位数居中 */
+.wf-badge--count {
+  min-width: 18px;
+  height: 18px;
+  padding: 0 var(--wf-space-xs);
+  border-radius: var(--wf-radius-xl);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: var(--wf-font-size-xs);
+  font-weight: var(--wf-font-weight-semibold);
+  line-height: 1;
+}

package/dist/level5/client/components/Badge/Badge.d.ts

@@ -0,0 +1,15 @@
+/** Badge：状态标签 + 圆点，6 种 variant（showcase /components/badge） */
+import type { Component, VNodeChild } from '../../../../level6/client/vdom/index.ts';
+export type BadgeVariant = 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'error';
+export interface BadgeProps {
+    variant?: BadgeVariant;
+    dot?: boolean;
+    children?: VNodeChild;
+    /** 数值角标（与 children 互斥；超出 overflowCount 显示 N+） */
+    count?: number;
+    /** 数值溢出阈值，默认 99（count > 阈值 → 阈值+） */
+    overflowCount?: number;
+    /** count=0 时是否显示（默认 false 隐藏，antd showZero=false 语义） */
+    showZero?: boolean;
+}
+export declare const Badge: Component<BadgeProps>;