@linhey/rhine-design 0.9.1 → 0.11.0

package/docs/REVIEW_VERIFICATION.md

@@ -0,0 +1,56 @@
+# 产品评审工具验收（2026-10-27）
+
+对应 [#40](https://github.com/linhay/rhine-design/issues/40)，验收时为未提交、未发布候选；后续提交进展见关联 issue。验证基于 Web `cfcb400fa213d9905eae1cab5dcb8ab8f817e03f` 加本任务工作区变更。版本字段仍为 0.10.0，不等于 npm 0.10.0 已具有新入口。
+
+## 证据范围
+
+- 合成数据；源码构建/测试使用 Node 24.21.0。源码工作区使用 React 19.3.1、Vite 8.3.4、TypeScript 5.9.3。
+- 安装包复验覆盖 React/ReactDOM 19.2.0 + Vite 6.4.5 + plugin-react 4.7.0，以及 React/ReactDOM 19.3.1 + Vite 8.3.4 + plugin-react 6.1.2。后续真实 App 隔离试接另覆盖 React 19.2.0 + Vite 6.4.3。仅声明这些实测组合；Vite 7、其他构建器、SSR 未测。
+- Chromium 155 与 WebKit 26.6 完整回归；Firefox 157（Playwright/core 1.64.1，Debian 13 arm64 隔离容器，CLI Node 20.19.2）覆盖静态制品 25 组及故障恢复，未测 Firefox dev。Safari 27.0.1 原生窗口完成草稿/Portal 跨主题保持、保存、400px 画布与 200% CSS zoom smoke。WebKit 引擎结果不冒充 Safari 完整矩阵；CSS zoom 不代表原生浏览器缩放。
+- 本地源码文件摘要、候选 tarball SHA-256、安装目录逐文件比对和原始日志保存在管理工作区的忽略证据目录。没有把候选当作正式版本发布。
+
+## 已执行检查
+
+| 项目 | 结果与范围 |
+| --- | --- |
+| 状态与生命周期 | PASS：URL 多维状态/非法回退，慢 setup 取消、早期资源清理、串行 dispose、reset、异常反馈 |
+| HTTP 模拟 | PASS：Request method/body、credentials omit、调用方/场景 signal、未匹配失败、内存存储 reset |
+| 构建边界 | PASS：静态 HTML 的真实 CSS 引用、非根 base、preview 目录入口、拒绝业务代理、生产目录精确匹配及官方 runtime 排除 |
+| 全库检查 | PASS：287 测试、类型检查、原组件展台构建/CSS/SVG 检查、两个产品评审示例构建 |
+| 真实浏览器 | PASS：Chromium、WebKit 分别执行开发/静态 HTTP 交互与 24 组（三主题 × 400/520/880/1280 宽 × 100%/200% CSS zoom），各 26 组，Firefox 另执行同一静态矩阵 25 组；草稿/Portal/DOM 焦点保留、表单保存、键盘关闭与焦点返回、长文、状态/角色、hash 刷新与前进后退 |
+| 故障恢复与错误留存 | PASS：Chromium/WebKit/Firefox 注入首次画布请求失败、永不完成的 dispose；10 秒后可显式重建 iframe，评审条件保留且旧上下文不继续 setup；旧请求确认不覆盖新状态，错误跨就绪/主题/重载保留并标记原场景，显式确认才清除 |
+| 动效生命周期 | PASS：平台 client 保存、Canvas 播放/暂停/恢复、系统/手动减少动态及系统恢复；切场景旧 Canvas 帧计数停止，慢初始化不覆盖新场景，渲染错误可见且可离开恢复 |
+| 网络/导航 | PASS：上述浏览器运行无真实业务请求/外部出站；未实现请求、同源整页链接/下载路径和外链被阻止，当前文档 hash 可用 |
+| 固定制品消费 | PASS：两套实际安装包分别构建 HTTP/平台两例；Vite 6 dev/preview 与 Vite 8 preview 中样式、主题切换保留、表单提交、平台保存及暂停通过，console/page error 为零 |
+| 真实 App 隔离试接 | PASS：两类真实 App 的固定源码副本安装同一候选，256 个包文件逐一匹配；共 18 组三主题/三宽度渲染与唯一 Provider 检查，另测 Portal/草稿原位保留、模拟保存/reset、产品路由、200% CSS zoom、减少动态与显式重载。178 次请求全为本地静态资源，pageerror 为零；HTTP 产品 619 业务 + 17 设计测试，平台产品 18 项 App/预览测试与类型检查，两者正式/预览构建和生产排除检查通过。仅副本接入，原产品未改；真实产品跨浏览器矩阵未覆盖 |
+| 发布与消费迁移 | SKIPPED：未获本轮发布/消费升级授权；没有 npm 发布、Pages 部署或真实产品代码迁移 |
+| 原生运行 | N/A：工具为 Web 评审，不能证明桌面原生或 UIKit 行为 |
+
+复验入口：`npm run check`；浏览器启动 HTTP dev（18340），以 Python 静态服务在 18342 提供 dist，再运行 `playwright-cli run-code --filename scripts/check-review.js` 与 `playwright-cli run-code --filename scripts/check-review-recovery.js`。用 CLI `open --browser=chrome` / `--browser=webkit` 选择独立会话。默认源码端口与脚本中的固定回归端口一致，避免误测其他页面。截图在 `output/playwright/review-*.png`（忽略目录）。
+
+## 失败与修正保留
+
+1. 早期开发子路径 404：中间件未正确处理 base，随后 HTML transform 又重复拼接 base。已修正为中间件识别 base、由 Vite 转换单一模块绝对路径。
+2. 第一轮静态截图没有样式：生成 HTML 时 CSS 尚未加入 bundle。改为 post generateBundle 后链接最终 CSS，补构建断言、计算样式和实际截图审阅；原交互可运行不能证明视觉通过。
+3. 开发模式出现一次 504 Outdated Optimize Dep，以及 CSS 模块引入 Vite client 的 CSP WebSocket 错误。调整独立优化缓存/扫描入口，并提供无连接的样式客户端。修正后浏览器 console error 为零；单次 504 的其他触发条件未穷尽。
+4. 第一轮焦点返回采样有 4 项瞬时失败。改为有界等待真实 activeElement 恢复，第二轮通过；未修改 Dialog 行为，也不把瞬时观察写成已定位组件缺陷。
+5. 首次 tarball/Vite 6 构建失败，Node 不支持 node_modules 中 TypeScript 插件自动剥离。Vite 入口改为 `.mjs` 运行文件和 `.d.mts` 声明，随后两套制品构建通过。
+6. 最终浏览器回归曾在 reset 消息尚未处理时读取旧输入，出现两项采样失败。脚本改为先确认旧会话 DOM 卸载，再检查新输入；保留原结果，不用可见性冒充 reset 已完成。
+7. 打包清单检查发现宽泛 examples 目录规则会收入嵌套 Vite 缓存。改为精确源码 glob，并加入包清单检查，最终制品排除 node_modules/缓存；所有早期包都仅留本地，未发布。
+8. 首次 `vite preview` 访问目录 URL 404，显式 index.html 可用。将 appType 改为 mpa，补真实 preview HTTP 回归，不用源码 dev 成功代替产物 preview。
+
+9. Firefox 156 在本机 headless 启动报 `Could not find profile folder`，独立 profile 重试仍失败，headed 显示 Profile Missing。与 [Playwright 上游 macOS 27 报告](https://github.com/microsoft/playwright/issues/42768) 的症状一致，尚未独立确认本机根因；未授予额外磁盘访问或更改隐私设置。Safari WebDriver 因远程自动化未启用而拒绝启动，改用原生 UI smoke，未更改该设置。
+10. Linux 补验首次安装器与 CLI 的 Playwright core 版本不一致，下载了 Firefox 1555 构建但 CLI 查找 1553，浏览器未启动；统一 Playwright 与 core 到 1.64.1 后重跑，原启动失败保留。
+11. 真实消费试接保留了合成时间类型错误、快照漏配导致 ENOENT、定位器/滚动/残留浮层导致的首次脚本失败；修正副本 fixture/必要配置及脚本后最终通过。既有测试警告和开发依赖扫描日志保留，不宣称所有日志为零。
+
+12. Firefox 首轮矩阵有两项脚本失败：同步读取 frame URL 早于 hash 跳转，以及预期合成渲染异常的 console 文本仅为 `Error`。诊断确认 hash 随后完成，Error 参数的 message 为预期合成异常；脚本改为有界等待 hash，并读取实际 Error 参数，未泛化忽略所有 Error。修正后 Firefox 静态 25 组通过；Chromium/WebKit 用同版脚本复核。
+
+## 合并前增量验证
+
+2026-10-27 在 `9f010f7` 基础上核对现有 Pages 工作流，发现示例的绝对 `/review-http/`、`/review-platform/` 资源路径不适用于项目站点 `/rhine-design/`。示例改为构建时使用 `./` 相对资源，dev/preview 保留各自目录前缀；工具运行代码和场景协议未改。构建集成测试同时覆盖绝对嵌套 base 与相对 base，全库 `npm run check` 为 288 项测试及全部构建/包清单 PASS。
+
+最终静态产物放在 `/rhine-design/review-http/`、`/rhine-design/review-platform/` 后，Chromium/WebKit 各 25 组矩阵 PASS：样式、动态模块、主题/Portal/草稿、表单、hash 刷新、动效和无业务出站。该增量验证不把此前固定 tarball 摘要改称新源码的包摘要；尚未重新发布 npm 制品。实际线上部署另以对应主线工作流和真实 URL 复验为准。
+
+## 交付边界
+
+评审接口和通用壳已有本地可运行候选，两个示例无需复制壳、URL 或工具栏。尚不能关闭 #40：固定版本发布、稳定在线部署与真实消费项目迁移仍需各自授权和证据。专用静态源、合成数据、host Provider 所有权、显式动效适配和异步关闭边界见[工具契约](REVIEW_TOOL.md)。

package/docs/SUMMARY_TABS.md

@@ -0,0 +1,77 @@
+# 带摘要的页签 · Summary Tabs
+
+版本边界：自 0.11.0 提供；npm 0.10.0 不包含这些字段，见[版本记录](../CHANGELOG.md#01102026-10-27)。实现使用现有 `Tabs` 的 `description` / `status`，不新增另一套组件。规范、组件和展台必须一起验收；消费方不得用后代选择器另改间距。
+
+## 适用范围与结构
+
+同一任务中切换少量独立对象，同时需要知道每个对象当前身份和状态，例如不同客户端、工作区或运行环境。建议2–3项；大量对象优先简洁Tabs或导航列表，完整身份留在内容区，不将大量摘要挤进一排。
+
+每个页签只有两组信息：第一组为名称及一个只读状态；第二组为身份摘要。状态即使未选中也保持可见，不暗示“选中才运行”。详细说明、路径、刷新按钮、停止同步等操作放在面板或操作栏，不能嵌套在Tab按钮中。
+
+```text
+┌── 命中区域：上12 / 下12，水平0 ──────────┐
+│ 名称  ← 8 →  状态                       │ 14/22；状态复用Badge
+│              ↓ 4                       │
+│ 类型 · 当前身份                         │ 12/18
+└────────────── 2px选中线 ────────────────┘
+                 ↓ 24
+面板第一组内容
+```
+
+图示尺寸是CSS像素；文字按行盒对齐，不能以中文字形的上下空白反推padding。
+
+## 间距与排版
+
+| 部位 | 值 / token | 说明 |
+| --- | --- | --- |
+| 名称 | 14/22，600；body / leading-body / weight-heading | 左对齐；不是页面标题 |
+| 摘要 | 12/18，400；caption / leading-caption / weight-regular | muted语义色；不得继承名称加粗 |
+| 状态 | 复用Badge契约 | 当前Badge为12/20、上下2px内距；各主题保留自己的边框、字重和内距，不在Tabs重画 |
+| 名称到状态 | 8，space-2 | 同一flex行；空间不足状态自然换行 |
+| 第一组到摘要 | 4，space-1 | 紧密身份组合；不同于普通卡片标题/说明的8px配方 |
+| 命中区上下内距 | 各12，space-3 | 水平0；首组与末组分别到上下边界 |
+| 相邻页签间距 | 16，space-4 | 不再叠加水平padding |
+| 页签分隔线到面板内容 | 24，space-6 | 由Tabs面板负责；调用方首项不得再加顶部margin |
+| 命中区域 | 最小高度44，自然增高 | 默认莱茵单行名称/状态、单行摘要70px（24+4+18+12×2）；Badge或文字换行可增高 |
+| 底部线 | 普通1px，选中2px | 选中线覆盖该页签命中区宽度；状态徽标不替代选中线 |
+
+带摘要的一组Tab等分可用宽度，均从顶部对齐；第一项与面板正文左缘对齐。容器保持至少必要的焦点外延空间，不加阴影、整块选中底色、额外卡片边框或圆角胶囊。
+
+## 状态、主题与动效
+
+| 状态 | 外观 / 行为 |
+| --- | --- |
+| 未选中 | 名称muted，摘要muted；状态仍用其真实语义色 |
+| 选中 | 名称ink与2px指示线；摘要不加粗、不变为成功色 |
+| 悬停 | 可用页签名称变ink；无抬升、阴影或位移 |
+| 键盘焦点 | 沿用库2px焦点环与3px偏移，和选中线分开 |
+| 禁用 | 沿用库禁用透明度；不能点击，方向键跳过；不是错误状态的替代品 |
+| 加载 | 保留已知身份，状态写“读取中”；未知身份写“尚未读取”，不编造账号 |
+| 错误 / 未知 | 明确文字徽标；保留可信旧值或显示未匹配，详情在面板 |
+
+状态是对象事实，选中是浏览位置；两者不能互相驱动。三主题只通过现有语义tokens、Badge和主题规则变化；橙趣等主题Badge较高时自然抬高整行，不能压缩字高去维持70px。状态外层使用inline-flex，消除额外的行内基线空白。
+
+选中线与面板沿用180ms的库动效，状态文字即时更新，不因标签变化循环动画；系统或手动减少动态时立即呈现。动画、状态与请求成功互不代替。
+
+## 窄窗与可访问性
+
+- 320px局部容器、400/520/880视口和200%缩放保持字号及间距；名称、状态和摘要自然换行，页签等高顶对齐，不固定高度、不裁剪身份，不使用省略号隐藏唯一辨识信息。
+- `label`始终是稳定可访问名称；`description`与`status`通过`aria-describedby`关联。状态更新不改`value`、焦点或当前页签。
+- 左右方向键循环，Home/End到首末可用项；跳过禁用项。隐藏面板保留挂载但退出可访问树。新增摘要不改变这些行为。
+- 状态仅允许纯文本或只读Badge，不允许按钮、链接、菜单、Switch、live region；异步结果由面板反馈，避免多个Tab反复播报。
+- 首次读取、错误及后台状态变化均不自动切页；宿主保存每个对象的状态，不把当前对象复制给其他页签。
+
+## 接入与展台
+
+```tsx
+<Tabs label="工作区" value={selected} onValueChange={setSelected} items={[
+  { value: 'primary', label: '主工作区', description: '研发 · 研究项目',
+    status: <Badge tone="success">同步中</Badge>, content: <PrimaryPanel /> },
+  { value: 'team', label: '协作工作区', description: '协作 · 设计项目',
+    status: <Badge>已停止</Badge>, content: <TeamPanel /> },
+]} />
+```
+
+独立展台 `/#summary-tabs` 提供局部320/520/自适应宽度、正常/加载/错误/禁用/长文本、尺寸说明和可编辑面板草稿。保留 `/#selection` 普通Tabs作对照；两个变体不能共用临时业务CSS。包内入口见[组件契约](../components/README.md)，间距含义见[间距规范](../components/SPACING.md)。
+
+验收同时检查计算样式与实际像素：12/8/4/16/24、名称14/22/600、摘要12/18/400；三主题长文本、键盘、禁用跳过、焦点保留、隐藏面板、状态变化、系统/手动减少动态。局部无横向溢出不替代视觉检查。正式消费需固定包含此能力的版本或提交；本地候选展台不代表能力已经发布。

package/docs/THEMING.md

@@ -144,4 +144,4 @@ import { Background, Surface } from '@linhey/rhine-design';
 
 兼容已有源码调用：`roleTone` 的原有三种值与显式 `theme` / `none` 均保留；省略 `decoration` 的正文及 `AppShell` 改为 `auto`，默认纯色。需要旧版正文纹理的调用方显式传入 `decoration="theme"`。侧栏显式传入 `theme` 现在也会开启纹理；默认仍关闭。以上能力自 0.5.0 提供，不属于 npm 0.4.0。
 
-主题选择的新候选组合见 [ThemePicker / ThemePreview](THEME_PICKER.md)；静态预览避免嵌套 Provider，未发布能力需核对源码与实际安装包。
+主题选择组件 [ThemePicker / ThemePreview](THEME_PICKER.md) 自 0.8.0 提供；静态预览避免嵌套 Provider。接入时核对源码与实际安装包，不由 main 展台推断发布范围。

package/examples/review/http/App.tsx

@@ -0,0 +1,46 @@
+import { useEffect, useState } from 'react';
+import { Button, Dialog, Notice, Stack, Surface, Text, TextField } from '@linhey/rhine-design';
+import { ThemeProvider } from '@linhey/rhine-design/theme';
+import type { ReviewEnvironment } from '@linhey/rhine-design/review';
+import '../product.css';
+type Project = { id: number; name: string };
+export function App({ environment, signal, role, report }: { environment: ReviewEnvironment; signal: AbortSignal; role: string; report(message: string, kind?: 'info' | 'error'): void }) {
+  const [items, setItems] = useState<Project[]>([]);
+  const [status, setStatus] = useState('loading');
+  const [query, setQuery] = useState('');
+  const [draft, setDraft] = useState('');
+  const [open, setOpen] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [details, setDetails] = useState('');
+  useEffect(() => {
+    const abort = new AbortController();
+    setStatus('loading');
+    fetch(`/api/projects?q=${encodeURIComponent(query)}`, { signal: AbortSignal.any([signal, abort.signal]) }).then(async response => {
+      if (!response.ok) throw new Error('合成服务暂不可用');
+      const next = await response.json() as Project[];
+      if (!abort.signal.aborted && !signal.aborted) { setItems(next); setStatus('ready'); }
+    }).catch(error => { if (error.name !== 'AbortError') setStatus('error'); });
+    return () => abort.abort();
+  }, [query, signal]);
+  return <ThemeProvider theme={environment.theme} data-rhine-motion={environment.reducedMotion ? 'reduced' : environment.paused ? 'paused' : 'full'}>
+    <div className="review-product"><Stack gap={4}><Text as="h1" variant="title">项目工作台</Text><Text tone="muted">合成数据 · {role === 'editor' ? '可编辑' : '只读'} · 独立产品路由</Text>
+      <TextField label="搜索项目" value={query} onChange={event => setQuery(event.target.value)} />
+      <TextField label="未保存草稿" value={draft} onChange={event => setDraft(event.target.value)} />
+      <Button variant="secondary" onClick={async () => {
+        try { const { message } = await import('./details'); setDetails(message); }
+        catch (error) { report(String(error), 'error'); }
+      }}>加载延迟模块</Button>{details && <p>{details}</p>}
+      {status === 'loading' ? <p role="status">正在加载合成项目…</p> : status === 'error' ? <Notice title="合成服务暂不可用">请切换状态重试。</Notice> : items.length ? items.map(item => <Surface key={item.id}><Text>{item.name}</Text></Surface>) : <p>暂无项目</p>}
+      <Button variant="secondary" onClick={() => { void fetch('/api/unimplemented').catch(error => report(error.message, 'error')); }}>触发未实现操作</Button>
+    <Dialog trigger={<Button disabled={role !== 'editor'}>新建项目</Button>} open={open} onOpenChange={setOpen} title="新建合成项目" description="仅保存到当前合成场景的内存数据。"><form onSubmit={async event => {
+      event.preventDefault(); setSaving(true);
+      try {
+        const response = await fetch(new Request(`${location.origin}/api/projects`, { method: 'POST', body: JSON.stringify({ name: draft || '新合成项目' }), signal }));
+        if (!response.ok) throw new Error('模拟保存失败');
+        setItems(await response.json() as Project[]); setOpen(false);
+      } catch (error) { report(String(error), 'error'); }
+      finally { setSaving(false); }
+    }}><Stack gap={3}><TextField label="项目名称" value={draft} onChange={event => setDraft(event.target.value)} /><Button type="submit" disabled={saving}>保存项目</Button></Stack></form></Dialog>
+    </Stack></div>
+  </ThemeProvider>;
+}

package/examples/review/http/catalog.tsx

@@ -0,0 +1,44 @@
+import { defineReview } from '@linhey/rhine-design/review';
+export default defineReview({
+  title: '项目工作台 · HTTP 示例',
+  scenes: [{
+    id: 'projects', title: '项目与编辑流程', group: '工作台', themeRoot: 'host',
+    source: 'examples/review/http/App.tsx', issue: 'https://github.com/linhay/rhine-design/issues/40',
+    description: '真实表单、弹窗与路由；HTTP 适配使用内存数据。主题与宽度切换保留草稿，状态或角色切换重新初始化。',
+    dimensions: [
+      { id: 'status', label: '列表状态', options: ['normal', 'loading', 'empty', 'error', 'dense'].map(id => ({ id, label: ({ normal: '正常', loading: '加载', empty: '空', error: '错误', dense: '密集长文' })[id]! })) },
+      { id: 'role', label: '角色', options: [{ id: 'editor', label: '编辑者' }, { id: 'reader', label: '只读成员' }] },
+    ],
+    async setup(context) {
+      const items = context.dimensions.status === 'empty' ? [] : Array.from({ length: context.dimensions.status === 'dense' ? 25 : 3 }, (_, index) => ({ id: index + 1, name: context.dimensions.status === 'dense' ? `合成项目 ${index + 1} · 跨团队设计评审与持续验证的长标题示例` : `合成项目 ${index + 1}` }));
+      context.mockHttp(async request => {
+        const url = new URL(request.url);
+        if (url.pathname !== '/api/projects') return;
+        if (request.method === 'GET') {
+          if (context.dimensions.status === 'loading') return new Promise<Response>((_resolve, reject) => request.signal.addEventListener('abort', () => reject(request.signal.reason), { once: true }));
+          if (context.dimensions.status === 'error') return Response.json({ message: '合成服务暂不可用' }, { status: 503 });
+          return Response.json(items.filter(item => item.name.includes(url.searchParams.get('q') ?? '')));
+        }
+        if (request.method === 'POST') {
+          if (context.dimensions.role !== 'editor') return Response.json({ message: '只读角色' }, { status: 403 });
+          const body = await request.json() as { name: string };
+          items.push({ id: items.length + 1, name: body.name });
+          context.report('模拟项目已保存');
+          return Response.json(items);
+        }
+      });
+      // The adapter is installed before any product module is evaluated.
+      const { App } = await import('./App');
+      context.signal.throwIfAborted();
+      const oldUrl = location.href;
+      history.replaceState(null, '', `${import.meta.env.BASE_URL}projects`);
+      window.dispatchEvent(new PopStateEvent('popstate'));
+      context.onDispose(() => { history.replaceState(null, '', oldUrl); });
+      return {
+        render: environment => <App environment={environment} signal={context.signal} role={context.dimensions.role} report={context.report} />,
+        reset: () => context.report('模拟数据已恢复初始值'),
+        dispose() { items.length = 0; },
+      };
+    },
+  }],
+});

package/examples/review/http/details.ts

@@ -0,0 +1 @@
+export const message = '延迟模块已加载 · 资源 base 与产品路由互相独立';

package/examples/review/http/vite.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { reviewPlugin } from '@linhey/rhine-design/review/vite';
+export default defineConfig(({ command }) => ({
+  root: import.meta.dirname, base: command === 'serve' ? '/review-http/' : './',
+  plugins: [react(), reviewPlugin({ catalog: './catalog.tsx', routerBase: '/product/' })],
+  build: { outDir: '../../../dist/review-http', emptyOutDir: true },
+}));

package/examples/review/platform/Workspace.tsx

@@ -0,0 +1,34 @@
+import { useEffect, useRef, useState } from 'react';
+import { Button, Notice, Stack, Text, TextField } from '@linhey/rhine-design';
+import type { ReviewEnvironment } from '@linhey/rhine-design/review';
+import '../product.css';
+interface Client { read(): string; save(value: string): Promise<void> }
+export function Workspace({ client, environment, dimensions }: { client: Client; environment: ReviewEnvironment; dimensions: Readonly<Record<string, string>> }) {
+  const [draft, setDraft] = useState(client.read);
+  const [saved, setSaved] = useState(false);
+  const canvas = useRef<HTMLCanvasElement>(null);
+  const count = useRef(0);
+  useEffect(() => {
+    const target = canvas.current!;
+    const context = target.getContext('2d')!;
+    let frame = 0;
+    const draw = () => {
+      count.current++;
+      target.dataset.frames = String(count.current);
+      context.clearRect(0, 0, 320, 100);
+      context.fillStyle = environment.theme === 'arknights' ? '#d0ef82' : environment.theme === 'neo-brutalism' ? '#e95725' : '#507058';
+      context.beginPath(); context.arc(160 + Math.sin(count.current / 25) * 110, 50, 14, 0, Math.PI * 2); context.fill();
+      if (!environment.paused && !environment.reducedMotion) frame = requestAnimationFrame(draw);
+    };
+    draw();
+    return () => cancelAnimationFrame(frame);
+  }, [environment.paused, environment.reducedMotion, environment.theme]);
+  return <div className="review-product"><Stack gap={4}><Text as="h1" variant="title">桌面工作区</Text>
+    {dimensions.connection === 'error' ? <Notice title="合成连接失败" /> : dimensions.connection === 'waiting' ? <p role="status">等待模拟连接…</p> : <p>平台模拟已连接 · {dimensions.quota === 'empty' ? '暂无用量' : '合成用量 42'}</p>}
+    <TextField label="工作区名称" value={draft} onChange={event => { setDraft(event.target.value); setSaved(false); }} />
+    <Button disabled={dimensions.connection !== 'ready'} onClick={async () => { await client.save(draft); setSaved(true); }}>保存工作区</Button>
+    {saved && <p role="status">内存工作区已保存</p>}
+    <canvas ref={canvas} width={320} height={100} aria-label="合成动态画布" />
+    <p>{environment.reducedMotion ? '减少动态' : environment.paused ? '已暂停' : '动态播放'}</p>
+  </Stack></div>;
+}

package/examples/review/platform/catalog.tsx

@@ -0,0 +1,46 @@
+import { defineReview, type ReviewScene } from '@linhey/rhine-design/review';
+const workspace: ReviewScene = {
+  id: 'workspace', title: '桌面工作区', group: '平台接口',
+  motionControls: ['full', 'paused'],
+  source: 'examples/review/platform/Workspace.tsx',
+  description: '仅注入内存平台 client，不调用原生配置、下载或业务剪贴板。Canvas 通过显式环境属性暂停、减少动态和恢复。',
+  dimensions: [
+    { id: 'connection', label: '连接阶段', options: [{ id: 'ready', label: '已连接' }, { id: 'waiting', label: '等待连接' }, { id: 'error', label: '连接失败' }] },
+    { id: 'quota', label: '用量状态', options: [{ id: 'normal', label: '正常用量' }, { id: 'empty', label: '暂无用量' }] },
+  ],
+  async setup(context) {
+    const { Workspace } = await import('./Workspace');
+    context.signal.throwIfAborted();
+    let current = '合成工作区';
+    const client = {
+      read: () => current,
+      save: async (value: string) => { context.signal.throwIfAborted(); current = value; context.report('已更新内存工作区名称'); },
+    };
+    return {
+      render: environment => <Workspace client={client} environment={environment} dimensions={context.dimensions} />,
+      dispose() { current = ''; },
+    };
+  },
+};
+export default defineReview({
+  title: '桌面工作区 · 平台示例', scenes: [workspace, {
+    id: 'slow', title: '慢速初始化', group: '生命周期', description: '等待期间可以切回工作区；定时器与迟到结果必须清理。',
+    async setup(context) {
+      await new Promise<void>((resolve, reject) => {
+        const timer = setTimeout(resolve, 4000);
+        context.onDispose(() => { clearTimeout(timer); reject(new DOMException('Disposed', 'AbortError')); });
+      });
+      context.signal.throwIfAborted();
+      return { render: () => <p>慢速初始化完成</p>, dispose() {} };
+    },
+  }, {
+    id: 'stuck-cleanup', title: '清理挂起恢复', group: '故障恢复', description: '离开此场景会遇到永不结束的合成清理；10 秒后可在外层重新载入画布恢复。',
+    setup: () => ({ render: () => <p>此场景模拟清理挂起，请切换到桌面工作区验证恢复。</p>, dispose: () => new Promise<void>(() => {}) }),
+  }, {
+    id: 'cleanup-error', title: '清理错误留存', group: '故障恢复',
+    setup: () => ({ render: () => <p>离开此场景后，合成清理错误应保留到显式确认。</p>, dispose() { throw new Error('合成清理失败'); } }),
+  }, {
+    id: 'failure', title: '渲染错误边界', group: '生命周期',
+    setup: () => ({ render() { throw new Error('合成渲染失败'); }, dispose() {} }),
+  }],
+});

package/examples/review/platform/vite.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { reviewPlugin } from '@linhey/rhine-design/review/vite';
+export default defineConfig(({ command }) => ({
+  root: import.meta.dirname, base: command === 'serve' ? '/review-platform/' : './',
+  plugins: [react(), reviewPlugin({ catalog: './catalog.tsx' })],
+  build: { outDir: '../../../dist/review-platform', emptyOutDir: true },
+}));

package/examples/review/product.css

@@ -0,0 +1,3 @@
+.review-product { padding: 24px; max-width: 840px; margin: 0 auto; overflow-wrap: anywhere; }
+.review-product canvas { display: block; max-width: 100%; border: 1px solid var(--rhine-line); }
+@media (max-width: 400px) { .review-product { padding: 12px; } }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linhey/rhine-design",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public",
@@ -23,7 +23,12 @@
     "./styles.css": "./components/styles.css",
     "./theme-arknights.css": "./components/theme-arknights.css",
     "./theme-neo-brutalism.css": "./components/theme-neo-brutalism.css",
-    "./logo.svg": "./components/assets/logo.svg"
+    "./logo.svg": "./components/assets/logo.svg",
+    "./review": "./review/index.ts",
+    "./review/vite": {
+      "types": "./review/vite.d.mts",
+      "import": "./review/vite.mjs"
+    }
   },
   "sideEffects": [
     "./components/index.ts",
@@ -47,15 +52,22 @@
     "vitest.config.ts",
     "package-lock.json",
     "scripts",
-    "skills"
+    "skills",
+    "review",
+    "examples/review/*/*.ts",
+    "examples/review/*/*.tsx",
+    "examples/review/*.css"
   ],
   "scripts": {
     "dev": "vite --host 127.0.0.1 --port 18309 --strictPort",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "build": "npm run typecheck && vite build && node scripts/check-build.mjs",
-    "check": "npm run test && npm run build",
-    "prepublishOnly": "npm run check"
+    "check": "npm run test && npm run build && npm run review:build && node scripts/check-review-package.mjs",
+    "prepublishOnly": "npm run check",
+    "review:http": "vite --config examples/review/http/vite.config.ts --host 127.0.0.1 --port 18340 --strictPort",
+    "review:platform": "vite --config examples/review/platform/vite.config.ts --host 127.0.0.1 --port 18341 --strictPort",
+    "review:build": "vite build --config examples/review/http/vite.config.ts && vite build --config examples/review/platform/vite.config.ts"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/preview/CheckboxRowGallery.tsx

@@ -0,0 +1,26 @@
+import { useState } from 'react';
+import { Checkbox, Stack, Text } from '../components';
+
+const choices = [
+  { id: 'a', label: '示例项目 A', hint: '内存卡 · 14 项' },
+  { id: 'b', label: '跨团队拍摄与素材整理的较长示例项目名称', hint: '移动设备 · 128 项，包含待整理素材' },
+  { id: 'c', label: 'Archive_With_A_Very_Long_Unbroken_Synthetic_Project_Name' },
+  { id: 'd', label: '其他来源' },
+];
+export function CheckboxRowGallery() {
+  const [selected, setSelected] = useState(['a']);
+  const [width, setWidth] = useState('240');
+  return <Stack gap={4}>
+    <Text as="h2" variant="heading">侧栏双行多选</Text>
+    <Text tone="muted">纯合成项目。整行、说明和留白均可选择；长名称自然换行。</Text>
+    <label>侧栏宽度 <select value={width} onChange={event => setWidth(event.target.value)}>{['160', '240', '320'].map(value => <option key={value} value={value}>{value}px</option>)}</select></label>
+    <div data-checkbox-rows style={{ width: Number(width), maxWidth: '100%' }}><Stack gap={2}>
+      <Checkbox layout="row" label="全部项目" hint="选择四个示例项目" checked={selected.length === choices.length} indeterminate={selected.length > 0 && selected.length < choices.length} onChange={event => setSelected(event.target.checked ? choices.map(item => item.id) : [])} />
+      {choices.map(item => <Checkbox key={item.id} layout="row" label={item.label} hint={item.hint} checked={selected.includes(item.id)} onChange={event => setSelected(current => event.target.checked ? [...current, item.id] : current.filter(id => id !== item.id))} />)}
+      <Checkbox layout="row" label="不可用项目" hint="当前无法读取" disabled />
+      <Checkbox layout="row" label="已选但不可用" hint="等待重新连接" disabled checked />
+    </Stack></div>
+    <Text variant="caption">已选 {selected.length} 项</Text>
+    <Checkbox label="默认表单布局" hint="保留旧表单说明的位置和命中范围。" />
+  </Stack>;
+}

package/preview/CommonGallery.tsx

@@ -30,6 +30,6 @@ export function CommonGallery({ section }: { section?: string }) {
       <Menu label="更多操作" trigger={<Button variant="secondary">更多操作</Button>} items={[{id:'refresh',label:'刷新',onSelect:()=>setAction('菜单：刷新')},{id:'disabled',label:'导出（暂不可用）',disabled:true,onSelect:()=>{}},{id:'archive',label:'归档示例',danger:true,onSelect:()=>setAction('菜单：归档示例')}]}/>
       <Dialog trigger={<Button variant="secondary">打开对话框</Button>} title="编辑工作区" description="此对话框仅演示输入、焦点与关闭行为。"><Stack><TextField label="工作区名称" defaultValue="研究工作区"/><Textarea label="工作区说明"/><Popover trigger={<Button variant="secondary">对话框内详情</Button>} title="嵌套详情"><Text>Escape先关闭当前气泡，再返回对话框。</Text></Popover></Stack></Dialog>
       <ConfirmDialog trigger={<Button variant="danger">打开确认框</Button>} title="停止演示任务？" description="这是合成操作，不会修改实际同步。默认焦点在取消按钮。" confirmLabel="停止演示任务" danger onConfirm={async()=>{if(confirmFail)throw new Error('demo');setAction('确认已完成（演示）');}}/>
-    </Inline><Checkbox label="模拟确认操作失败" checked={confirmFail} onChange={event=>setConfirmFail(event.target.checked)}/><Text variant="caption" tone="muted">{action}。Tab/方向键/Escape可操作；减少动态保留相同功能。</Text><Divider/><Inline><Button variant="secondary" onClick={()=>{setToastTone('success');setToast(true);}}>显示成功通知</Button><Button variant="secondary" onClick={()=>{setToastTone('error');setToast(true);}}>显示错误通知</Button></Inline><Toast open={toast} onOpenChange={setToast} tone={toastTone} title={toastTone==='success'?'演示操作已完成':'演示操作失败'} description={toastTone==='success'?'5秒后关闭；悬停、聚焦或页面隐藏时暂停。':'错误通知保持显示，请重试或手动关闭。'}/></Stack></Surface></section>}
+    </Inline><Checkbox label="模拟确认操作失败" checked={confirmFail} onChange={event=>setConfirmFail(event.target.checked)}/><Text variant="caption" tone="muted">{action}。Tab/方向键/Escape可操作；减少动态保留相同功能。</Text><Divider/><Inline><Button variant="secondary" onClick={()=>{setToastTone('success');setToast(true);}}>显示成功通知</Button><Button variant="secondary" onClick={()=>{setToastTone('error');setToast(true);}}>显示错误通知</Button></Inline><Toast placement="floating" open={toast} onOpenChange={setToast} tone={toastTone} title={toastTone==='success'?'演示操作已完成':'演示操作失败'} description={toastTone==='success'?'5秒后关闭；悬停、聚焦或页面隐藏时暂停。':'错误通知保持显示，请重试或手动关闭。'}/></Stack></Surface></section>}
   </>;
 }

package/preview/CompactFilterBarGallery.tsx

@@ -0,0 +1,19 @@
+import { useState } from 'react';
+import { Button, Inline, ListFilterBar, SegmentedControl, Select, Stack, Text } from '../components';
+
+export function CompactFilterBarGallery() {
+  const [range, setRange] = useState('today');
+  const [feedback, setFeedback] = useState('normal');
+  return <Stack gap={4}>
+    <Text>筛选抽屉仅保留必要字段；进行中与失败仍然可见。</Text>
+    <Inline gap={2}>
+      {['normal', 'pending', 'error'].map(state => <Button key={state} variant="secondary" aria-pressed={feedback === state} onClick={() => setFeedback(state)}>{({ normal: '正常', pending: '加载', error: '失败' })[state]}</Button>)}
+    </Inline>
+    <ListFilterBar label="紧凑筛选示例" result="120 条合成记录" drawerDescription={null} drawerResult={null}
+      pending={feedback === 'pending'} error={feedback === 'error' ? '暂时无法更新合成结果，请重试。' : undefined}
+      primary={[{ id: 'platform', label: '平台', control: <Select label="平台" defaultValue="all"><option value="all">全部平台</option></Select> }]}
+      filters={[{ id: 'range', label: '时间快捷', control: <SegmentedControl fullWidth label="时间快捷" value={range} onValueChange={setRange} items={[{ value: 'today', label: '今天' }, { value: 'yesterday', label: '昨天' }, { value: 'week', label: '本周' }]} /> }]}
+    />
+    <SegmentedControl fullWidth label="等宽长文本与禁用示例" value="first" onValueChange={() => {}} items={[{ value: 'first', label: '较长的第一个范围' }, { value: 'second', label: '第二范围' }, { value: 'third', label: '不可选择', disabled: true }]} />
+  </Stack>;
+}

package/preview/ComponentTypographyGallery.tsx

@@ -0,0 +1,23 @@
+import { useState } from 'react';
+import { Button, CopyButton, EmptyState, ErrorSummary, Fieldset, MediaCard, MediaViewer, Stack, Steps, Text, TextField, ThemePicker } from '../components';
+
+const description = '示例辅助说明：这是一段用于检查长文本自然换行的合成内容，来源、时间与读取状态应保持完整可读。';
+export function ComponentTypographyGallery() {
+  const [open, setOpen] = useState(false);
+  const [next, setNext] = useState(false);
+  return <Stack gap={4}>
+    <Text as="h2" variant="heading">公共组件文字配对</Text>
+    <EmptyState title="没有匹配结果：请检查名称、日期与当前范围" description={description} action={<Button onClick={() => setOpen(true)}>打开文字检查</Button>} />
+    <MediaViewer open={open} onOpenChange={setOpen} trigger={<Button>打开媒体示例</Button>} title={next ? '下一项合成媒体' : '示例媒体与较长标题：检查字号、行高和字重'} description={description}
+      onNext={() => setNext(true)} onPrevious={() => setNext(false)}
+      actions={<label>显示方式 <select aria-label="显示方式"><option>适应窗口</option><option>原始尺寸</option></select></label>}>
+      <Text>合成画布：不加载真实媒体。</Text>
+    </MediaViewer>
+    <MediaCard title="读取状态" kind="photo" state="loading" onOpen={() => setOpen(true)} />
+    <CopyButton value="synthetic-example" label="模拟复制" copy={async () => {}} />
+    <Steps current={0} items={[{ id:'one',label:'检查说明',description }]} />
+    <Fieldset legend="分组提示" hint={description}><TextField id="typography-example" label="示例字段" /></Fieldset>
+    <ErrorSummary title="请检查以下字段的完整内容" errors={[{fieldId:'typography-example',message:'定位示例字段'}]} />
+    <ThemePicker value="rhine" onValueChange={() => {}} options={[{value:'rhine',label:'仅展示文字状态',previewSrc:'data:image/png;base64,invalid'}]} />
+  </Stack>;
+}

package/preview/DenseFilterControlsGallery.tsx

@@ -0,0 +1,21 @@
+import { useState } from 'react';
+import { Button, DateRangePicker, Inline, RemoteMultiSelect, Stack, Surface, Text, type Choice, type DateRange } from '../components';
+
+const departments: Choice[] = Array.from({ length: 100 }, (_, i) => ({ value: `synthetic-${i}`, label: `合成部门 ${i + 1}${i % 8 === 0 ? ' · 跨团队协作与长期计划' : ''}` }));
+
+export function DenseFilterControlsGallery() {
+  const [selected, setSelected] = useState(departments.slice(0, 90));
+  const [query, setQuery] = useState('');
+  const [date, setDate] = useState<DateRange>({ start: '2026-10-01', end: '2026-10-24' });
+  const [error, setError] = useState<string | null>(null);
+  // Fixture filtering is local; production hosts keep server-side query ownership.
+  const options = departments.filter(item => item.label.includes(query));
+  return <Surface><Stack gap={4}>
+    <Text as="h2" variant="heading">密集筛选控件</Text>
+    <Text tone="muted">100 个合成部门、90 个已选项；可搜索、展开移除或清空。日期保留原生键盘和日历。</Text>
+    <Inline gap={2}><Button variant="secondary" onClick={() => setSelected(departments)}>全选部门</Button><Button variant="quiet" onClick={() => setSelected([])}>清空部门</Button></Inline>
+    <RemoteMultiSelect label="部门" query={query} onQueryChange={setQuery} value={selected} onValueChange={setSelected} options={options} maxVisibleTags={2} placeholder="搜索部门" />
+    <DateRangePicker compact label="日期区间" value={date} onValueChange={setDate} min="2026-01-01" max="2026-12-31" clearable={false} required onValidationChange={setError} />
+    <Text variant="caption" tone="muted">{error || `${date.start} 至 ${date.end}`}</Text>
+  </Stack></Surface>;
+}

package/preview/GalleryShell.tsx

@@ -1,15 +1,16 @@
 import { useEffect, useRef, useState, type ReactNode } from 'react';
 import { Breadcrumbs, Button, Logo, SegmentedControl, Select, SideNav } from '../components';
 import { ThemeProvider, themes, useTheme, type ThemeName } from '../components/theme';
+import { componentCount, packageVersion } from './packageInfo';
 import './shell.css';
 import './theme-arknights.css';
 import './theme-neo-brutalism.css';
 
 export const galleryGroups = [
-  { label: '开始', items: [['top', '设计总览'], ['subscriptions', '订阅管理示例']] },
+  { label: '开始', items: [['top', '设计总览'], ['subscriptions', '订阅管理示例'], ['compact-filters', '紧凑与大量筛选'], ['checkbox-rows', '侧栏双行多选'], ['component-typography', '组件文字配对']] },
   { label: '应用能力', items: [['app-shell', '背景与多侧栏'], ['advanced-forms', '复杂表单'], ['advanced-data', '受控数据表'], ['media', '媒体卡片与查看器'], ['monitoring', '健康详情与图表']] },
   { label: '设计语言', items: [['foundation', '视觉基础'], ['backgrounds', '场景背景'], ['spacing', '间距与组合'], ['typography', '字体与文字'], ['brand', '品牌标志']] },
-  { label: '通用组件', items: [['actions', '按钮与输入'], ['selection', '选择与切换'], ['feedback', '状态与加载'], ['disclosure', '展开与组合'], ['data', '数据与分页'], ['forms', '表单与选择'], ['utilities', '操作与布局'], ['overlays', '浮层与反馈'], ['overlay-bounds', '浮层缩放与边界'], ['settings-dialog', '设置导航弹窗'], ['theme-picker', '主题预览与选择'], ['navigation', '导航与步骤'], ['form-workflow', '表单流程']] },
+  { label: '通用组件', items: [['actions', '按钮与输入'], ['selection', '选择与切换'], ['summary-tabs', '带摘要的页签'], ['feedback', '状态与加载'], ['disclosure', '展开与组合'], ['data', '数据与分页'], ['forms', '表单与选择'], ['utilities', '操作与布局'], ['overlays', '浮层与反馈'], ['overlay-bounds', '浮层缩放与边界'], ['settings-dialog', '设置导航弹窗'], ['theme-picker', '主题预览与选择'], ['navigation', '导航与步骤'], ['form-workflow', '表单流程']] },
   { label: '交互与动效', items: [['patterns', '场景与交互指南'], ['compact-account', '紧凑账号与凭证'], ['list-filter-bar', '列表筛选栏'], ['date-range-filter', '日期筛选组合'], ['motion', '动效实验室'], ['startup', '启动动画'], ['orbit', '轨道星空'], ['neutron-star', '中子星']] },
 ] as const;
 export type GallerySection = typeof galleryGroups[number]['items'][number][0];
@@ -94,7 +95,7 @@ function GalleryContent({ motion, onMotionChange, children }: GalleryShellProps)
       <SideNav id="gallery-navigation" className="ds-sidebar-nav" aria-label="组件目录" currentId={section} groups={galleryGroups.map(group=>({label:group.label,items:group.items.map(([id,label])=>({id,label,href:`#${id}`}))}))} onNavigate={item=>{
         setMenuOpen(false); if(section===item.id) main.current?.focus({preventScroll:true});
       }}/>
-      <div className="ds-sidebar-foot"><span>COMPONENT LIBRARY</span><span>66 个组件 · 0.8.0</span><span className="ak-readout">{readout}</span></div>
+      <div className="ds-sidebar-foot"><span>COMPONENT LIBRARY</span><span>{componentCount} 个组件 · 源码包版本 {packageVersion}</span><span>发布范围见版本记录</span><span className="ak-readout">{readout}</span></div>
     </aside>
     <main className="ds-workspace" id="gallery-content" ref={main} tabIndex={-1} aria-label={label}>
       <header className="ds-workspace-head"><Breadcrumbs label="展台位置" items={[{label:"组件展台",href:"#top"},{label}]} /><div className="ds-head-controls"><SegmentedControl label="动效偏好" items={[{value:'system',label:'跟随系统'},{value:'reduced',label:'减少动态'}]} value={motion} onValueChange={onMotionChange} /><Select label="界面主题" value={theme} onChange={event => {

package/preview/OrbitGallery.tsx

@@ -12,7 +12,7 @@ export function OrbitGallery() {
     <div className="ds-section-title"><span>ORBIT</span><h2>轨道星空 · 品牌艺术背景</h2></div>
     <p className="ds-caption">莱茵的折纸鸟、战术的悬浮源石晶簇、橙趣的草莓甜甜圈。每个主题都有自己的物件，也可以切换到原始深色星空。</p>
     <Inline gap={3}>
-      <Badge>0.7.0</Badge>
+      <Badge>主题艺术自 0.8.0 提供</Badge>
       <SegmentedControl label="画面风格" value={appearance} onValueChange={value => setAppearance(value as 'theme' | 'original')} items={[{ value: 'theme', label: '跟随主题' }, { value: 'original', label: '原始深色' }]} />
       <Button variant="secondary" onClick={() => setReplay(value => value + 1)}>重播轨道</Button>
       <Switch label="减少轨道动态" checked={reduced} onCheckedChange={setReduced} />

package/preview/SpacingGallery.tsx

@@ -1,10 +1,11 @@
 import { useState } from 'react';
-import { Button, DataTable, Grid, Inline, Notice, Select, Stack, Surface, Text, type Spacing } from '../components';
+import { Button, DataTable, Grid, Inline, Notice, SegmentedControl, Select, Stack, Surface, Text, type Spacing } from '../components';
 import './spacing.css';
 
 const scale: Spacing[] = [1, 2, 3, 4, 6, 8, 12];
 export function SpacingGallery() {
   const [state, setState] = useState('normal');
+  const [metric, setMetric] = useState('volume');
   const [selected, setSelected] = useState<string[]>(['research']);
   return <section id="spacing">
     <div className="ds-section-title"><span>SPACE</span><h2>间距与组合 · 让关系可见</h2></div>
@@ -12,6 +13,13 @@ export function SpacingGallery() {
       <Text tone="muted">同组紧、组间松。间距使用已有 token；gap 的数字是后缀，例如 gap=4 对应16px。</Text>
       <Surface><Stack gap={4}>{scale.map(space => <div className="ds-spacing-scale" key={space}><Text variant="code">space-{space}</Text><span className="ds-spacing-bar" style={{width:`var(--rhine-space-${space})`}} aria-hidden="true"/><Text numeric variant="caption">{space * 4}px</Text></div>)}</Stack></Surface>
       <Select label="卡片内容状态" value={state} onChange={event=>setState(event.target.value)}><option value="normal">默认</option><option value="loading">检查中</option><option value="error">读取失败</option><option value="long">长文案</option></Select>
+      <Surface><Stack gap={4}>
+        <Inline gap={4} style={{justifyContent:'space-between'}}>
+          <Stack gap={2}><Text as="h3" variant="heading">{state==='long'?'长标题示例：按业务维度查看统计分布':'统计分布'}</Text></Stack>
+          <SegmentedControl size="compact" label="统计维度" items={[{value:'volume',label:'用量'},{value:'count',label:'次数',disabled:state==='loading'}]} value={metric} onValueChange={setMetric}/>
+        </Inline>
+        {state==='error'?<Notice tone="error" title="统计暂不可用">保留所选维度，可重新读取。</Notice>:<Text tone="muted">{state==='loading'?'正在读取统计…':`当前维度：${metric==='volume'?'用量':'次数'}。紧凑视觉 32px，点击区域至少 44px；标题与操作居中对齐，窄窗自然换行。`}</Text>}
+      </Stack></Surface>
       <Grid gap={6} minWidth={280}>
         <Stack gap={3}>
           <Text variant="caption" tone="muted">24px 内边距 · 8px 标题/说明 · 16px 内容/操作</Text>