iter(g325): avatar 破图自动回退文字头像，不再露浏览器碎图标

.ua/backlog.json

@@ -3311,6 +3311,15 @@
       "motivation": "setRows 已支持整体换源并按 rowKey 剔除失效选择，但列定义仍是构造时写死：动态列表（按角色 / 视图切换列集）只能重建整个实例，排序与筛选状态全丢；setColumns 与 setRows 对称——换列后指向不存在列的 sorting / filters 失去语义，应剔除而不是静默残留。",
       "acceptance": "① core 新增 setColumns(next)：引用未变不动；换列后剔除 sorting / filters 里 key 不在新列集的条目，其余状态（分页 / 选择）保持；② getColumns 返回最新列集，getCellValue 按新列 accessor 取值；③ smoke 冒烟补断言（失效剔除 + 未变短路 + accessor 跟随）；④ npm run check 通过。",
       "notes": ""
+    },
+    {
+      "id": "g325",
+      "domain": "visual",
+      "status": "open",
+      "title": "avatar 破图回退文字头像：src 加载失败不再露碎图标",
+      "motivation": "avatar 有 src 时直接渲染 img，加载失败（404 / 网络断开 / 权限过期）会露出浏览器默认碎图标，圆形容器里一块灰裂图比没有头像更难看；image 组件已有 error 兜底，avatar 没跟，同类组件口径不一致。",
+      "acceptance": "① avatar img 注册 error 监听：加载失败就地替换为与无 src 时同款的文字头像（名称首字 + role=img + aria-label），尺寸与语义底色不变；② 正常加载路径零变化（不加多余请求）；③ manifest 文档 avatar props/步骤同步补一条兜底说明，verify 双向校验过；④ npm run check 通过。",
+      "notes": ""
     }
   ]
 }

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T17:03:14.418Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T17:17:55.311Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -527,6 +527,7 @@ avatar({ name: '张三' }); avatar({ name: 'Alice', size: 40, variant: 'success'
 2. 有图片就传 src：渲染 img 并用 name 作 alt，读屏语义完整；图片缺失时由浏览器 alt 兜底
 3. 尺寸用 size（像素）控制，头像不参与布局拉伸（flex:none），可安全排进 .row 与表格单元格
 4. 需要区分类别（在线/告警）时用 variant 换底色档，颜色一律来自令牌
+5. src 加载失败（404 / 断网）时自动回退为文字头像：首字占位、role=img 与 aria-label 不变，尺寸与语义底色保持，不会露出浏览器碎图标
 
 现场演示：apps/docs/demo.html#sec-avatar
 
@@ -2578,7 +2579,7 @@ API 速览：
 - card(props, ...children)：卡片容器
 - badge(props)：徽标，variant = default | success | warning | danger
 - tag(props)：可关闭标签，variant 五档语义色，closable + onClose 支持从数据源移除（纯展示请用 badge）
-- avatar(props)：头像，有 src 渲染图片（alt 用名称）、无 src 用首字占位，size 可调 + 四档语义底色
+- avatar(props)：头像，有 src 渲染图片（alt 用名称）、无 src 用首字占位，src 加载失败自动回退文字头像，size 可调 + 四档语义底色
 - alert(props)：提示条，variant 四档语义色 + 可选 title 与 closable 关闭按钮，role=alert 读屏可播报
 - toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失（悬停暂停、移出续时），出入场微动画；showToast(props) 为完整入参版本（closable 显示关闭按钮，同屏最多 4 条）
 - tooltip(props, trigger)：包裹式悬浮提示，hover / 键盘聚焦延迟出场，Esc 收起；触摸屏按下即出、抬手延迟 1.2s 收起，气泡 pointer-events: none 不挡点击

packages/skin/ui/src/avatar.ts

@@ -1,15 +1,17 @@
 import { h } from '@ui-arch/frame';
 import type { AvatarProps } from './types.js';
 
-/*** 头像：有 src 渲染图片（alt 用名称），否则用名称首字做占位；尺寸与语义底色由 props 决定 ***/
+/*** 头像：有 src 渲染图片（alt 用名称），否则用名称首字做占位；src 加载失败就地回退文字头像，尺寸与语义底色不变 ***/
 export function avatar(props: AvatarProps): HTMLElement {
   const size = `${props.size ?? 32}px`;
+  const textAvatar = (): HTMLElement =>
+    h('span', { class: 'ua-avatar-text', role: 'img', 'aria-label': props.name }, firstChar(props.name)); // 文字头像补 role=img，aria-label 才会被读屏当名称播报
+  const img = props.src ? h('img', { class: 'ua-avatar-img', src: props.src, alt: props.name }) : null;
+  img?.addEventListener('error', () => img.replaceWith(textAvatar())); // 破图兜底：碎图标比空白更刺眼，回退首字占位
   return h(
     'span',
     { class: `ua-avatar ua-avatar-${props.variant ?? 'default'}`, style: `width:${size};height:${size}`, title: props.name },
-    props.src
-      ? h('img', { class: 'ua-avatar-img', src: props.src, alt: props.name })
-      : h('span', { class: 'ua-avatar-text', role: 'img', 'aria-label': props.name }, firstChar(props.name)), // 文字头像补 role=img，aria-label 才会被读屏当名称播报
+    img ?? textAvatar(),
   );
 }
 

packages/skin/ui/ua.manifest.json

@@ -29,7 +29,7 @@
       "card(props, ...children)：卡片容器",
       "badge(props)：徽标，variant = default | success | warning | danger",
       "tag(props)：可关闭标签，variant 五档语义色，closable + onClose 支持从数据源移除（纯展示请用 badge）",
-      "avatar(props)：头像，有 src 渲染图片（alt 用名称）、无 src 用首字占位，size 可调 + 四档语义底色",
+      "avatar(props)：头像，有 src 渲染图片（alt 用名称）、无 src 用首字占位，src 加载失败自动回退文字头像，size 可调 + 四档语义底色",
       "alert(props)：提示条，variant 四档语义色 + 可选 title 与 closable 关闭按钮，role=alert 读屏可播报",
       "toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失（悬停暂停、移出续时），出入场微动画；showToast(props) 为完整入参版本（closable 显示关闭按钮，同屏最多 4 条）",
       "tooltip(props, trigger)：包裹式悬浮提示，hover / 键盘聚焦延迟出场，Esc 收起；触摸屏按下即出、抬手延迟 1.2s 收起，气泡 pointer-events: none 不挡点击",
@@ -1019,7 +1019,8 @@
           "只传 name：用名称首字做占位（中文取首字、英文大写），底色走 accent 淡化，暗色自动适配",
           "有图片就传 src：渲染 img 并用 name 作 alt，读屏语义完整；图片缺失时由浏览器 alt 兜底",
           "尺寸用 size（像素）控制，头像不参与布局拉伸（flex:none），可安全排进 .row 与表格单元格",
-          "需要区分类别（在线/告警）时用 variant 换底色档，颜色一律来自令牌"
+          "需要区分类别（在线/告警）时用 variant 换底色档，颜色一律来自令牌",
+          "src 加载失败（404 / 断网）时自动回退为文字头像：首字占位、role=img 与 aria-label 不变，尺寸与语义底色保持，不会露出浏览器碎图标"
         ]
       },
       {