Test/local visual test

.gitignore

@@ -136,3 +136,6 @@ packages/vchart/__tests__/runtime/node/**.png
 *.tsbuildinfo
 .github/hooks/copilot-hooks.json
 .omx/
+
+# Local visual regression artifacts
+.vchart-visual/

AGENTS.md

@@ -24,3 +24,12 @@ VChart 是高性能可视化渲染库。工程取舍应优先面向正确、文
 2. render、update、interaction、animation、release 的高性能。
 3. 稳定且易用的公共调用方式。
 4. 最小化兼容性兜底，只在真实 API 承诺需要时引入。
+
+## 本地视觉回归测试
+
+- 开发完成后，依据改动运行相关目录或单用例；影响公共渲染、布局、数据或状态路径时考虑多个目录，不确定范围时运行全量。命令从仓库根目录执行：`node packages/vchart/scripts/visual-test.mjs --dir components/label` 或 `--case pie-label`。
+- 每次提交 PR 前运行全量：`node packages/vchart/scripts/visual-test.mjs`。默认比较当前工作区（含未提交修改）与官方 develop。`--self-compare` 仅验证稳定性，不能代替基线比较。
+- 查看三图 HTML 或 `agent-summary.md`：视觉差异需要审查和说明，执行错误必须解决；无法运行、基线不支持新功能等阻断应如实记录，不得写成通过，不跳过用例或放宽阈值。
+- 新增功能、修复 bug 或发现覆盖空缺时，补充有明确目的的确定性回归用例，或补强相关用例；交互必须断言真实状态变化。登记到显式清单并按用例指南完成稳定性及反例检查。
+- 开发者或 Agent 独立新增用例不填写 `BugServer case IDs` 行，不填空值或占位 ID。现有迁移项保留真实来源，改写保留原 ID、合并保留多个。未来同步到 BugServer 成功后再补齐真实 ID；本期没有同步功能。
+- 使用 Node.js 22；环境准备、全量/目录/单例命令、报告及清理见 [视觉测试说明](./packages/vchart/__tests__/visual/README.md)，目录与编写规范见 [用例指南](./packages/vchart/__tests__/visual/cases/README.md)。测试不替代必要的单元、性能及发版前全量测试。

packages/vchart/__tests__/visual/DESIGN.md

@@ -0,0 +1,48 @@
+# 本地视觉测试工具设计
+
+工具服务 VChart 核心包的本地开发，以同一批冻结用例比较当前工作区与官方 develop 固定提交的产物。命令和结果协议见 [运行说明](./README.md)，当前平台验证范围见 [验收摘要](./cases/ACCEPTANCE.md)。
+
+## 边界
+
+只提供全量、目录、单用例三种选择，由开发者或 Agent 判断相关范围；不自动推断代码影响，不提供永久截图基线或接受差异命令。不接入线上 case、CI、多产品框架或模型服务。默认比较需要公开 GitHub 和依赖下载；准备完成后的自比较不获取远端基线，报告可离线阅读。
+
+## 职责
+
+| 文件（相对于 packages/vchart）                            | 职责                                              |
+| --------------------------------------------------------- | ------------------------------------------------- |
+| `scripts/visual-test.mjs`                                 | CLI 参数、入口及生命周期                          |
+| `scripts/visual/runner.mjs`                               | 清单校验、选择、冻结、预检、阶段执行及结果校验    |
+| `scripts/visual/build.mjs`                                | 官方基线、独立 worktree、最小构建链与缓存         |
+| `scripts/visual/runtime.mjs`                              | 子进程、回环服务、文件摘要与清理                  |
+| `__tests__/visual/cases/index.mjs`                        | 唯一可执行清单，模块契约见用例指南                |
+| `__tests__/visual/helpers.mjs`、`interaction-helpers.mjs` | 共享绘制、配置、图元定位和状态检查                |
+| `__tests__/visual/page.html`、`visual.spec.mjs`           | 加载指定产物、渲染、交互、验证及最终截图          |
+| `__tests__/visual/settings.mjs`、`playwright.config.mjs`  | 固定环境、单 worker、超时及比较策略               |
+| `__tests__/visual/reporter.mjs`、`report.mjs`             | 增量阶段记录、结果归一化、三图 HTML 与 Agent 报告 |
+
+沿用 `.mjs`、JSDoc 和现有依赖，不增加单独编译链。模块导入不注册信号或启动进程；信号由运行入口管理。
+
+## 执行与隔离
+
+1. 校验参数和环境，建立运行目录及独占锁，记录 runId、PID、开始时间；未知锁不夺取。
+2. 递归冻结当前用例、页面、配置和测试代码，从副本加载清单并固定选择集，记录文件摘要。
+3. 从固定官方地址取得 develop 或指定完整 SHA，不依赖 origin、不以旧缓存代替拉取成功。
+4. 本地使用已有依赖并包含未提交修改；基线用独立 detached worktree，按其锁文件安装。两侧不共享安装目录。
+5. 两侧执行同一最小构建链：内部 bundler、vutils-extension ES、VChart UMD；关闭额外入口与 postTasks。仅清理已知生成路径，检查新产物非空并复制记录摘要。本地构建前后 HEAD 或工作区内容变化则失败。
+6. 通过随机端口的回环 HTTP 服务加载冻结输入。每例新 context，公共绘制检查、动作和最终状态断言、字体就绪及稳定截图后才比较。
+7. 基线全部成功后执行本地阶段，本地禁止生成缺失基线。按精确 ID 集合与完整附件校验结果；缺失、重复或额外结果均失败。
+8. 正常、失败或信号路径逐项清理本次资源；保留原始错误与清理错误，再生成最终 JSON、HTML、Markdown 和退出码。
+
+自比较只构建本地一次，在两侧隔离 context 执行；验证确定性，不证明图表内容正确。用例从页面注入的 VChart 获取实例，不能导入工作区源码而绕过指定产物。截图阶段禁止外网请求；环境与阈值统一配置，不开放放宽阈值或跳过断言的 CLI 参数。
+
+## 缓存与清理
+
+仅缓存最近一次成功基线构建，键包含 SHA、锁文件、Node、平台架构及实际构建配方摘要；报告样式变化不使构建缓存失效。内容摘要错误则重建，权限和磁盘错误明确失败。准备完新缓存再替换旧缓存，每次重新截图；本地每次重建。
+
+SIGINT/SIGTERM 只终止本次进程组并清理浏览器、服务、worktree 和锁。SIGKILL 或断电后人工确认遗留资源，不能终止其他任务。输出集中于忽略目录 `.vchart-visual/`，不提交截图、报告或缓存。
+
+## 结果与扩展原则
+
+`summary.json` 的 `schemaVersion: 1` 是 HTML 与 Agent Markdown 的共同数据源；保留阶段结果、诊断码、环境、摘要和相对证据路径。`finalized` 表示终态，`complete` 表示所有选中用例完成有效比较，两者独立。完整比较无差异为 0，有差异为 1，执行、证据、清理或报告失败为 2。截图断言失败只有在比较证据完整时才能归为差异。
+
+新增 case 遵循 [用例指南](./cases/README.md)，来源 ID 可选且不影响执行。同步到 BugServer 仅为后续计划，本期没有同步状态、任务或命令。修改工具时使用现有 Node 测试入口，故障注入仅操作独立验证目录；单元测试、性能测试和内网发版全量测试继续承担各自职责。