VChart

# VChart 工程基准

VChart 是高性能可视化渲染库。工程取舍应优先面向正确、文档化的调用方式：快速的 render/update/release 路径、稳定可预期的 API，以及可用、易用的图表行为。

## 编码习惯

- 不要在热路径中加入大量宽泛的防御式兜底，除非它保护的是明确记录的公共 API 契约，或有真实兼容性需求支撑。
- 优先使用清晰契约，而不是静默归一化。内部非法状态应通过测试或边界校验暴露，不应被每个图元运行时 guard 隐藏。
- per-graphic 的 render/update/state 代码应尽量少分配、少分支。避免不必要的数组创建、对象重建、深比较、resolver 失效、状态清理或重复生命周期工作。
- 按 VRender API 的预期契约调用。除非存在明确的跨版本兼容理由，不要在 VChart 侧包一层本地兜底逻辑。
- 当项目已有标准工具、公共 API 或统一封装能表达同一行为时，必须优先收敛到标准写法；如果标准写法无法满足需求，应修正标准工具或上游契约，而不是在调用点维护多套等价或异化实现。暴露并修复标准路径问题，优先于用局部特例掩盖问题。
- 公共 API 边界要保持易用性，但内部路径不需要长期容忍非标准调用方。
- 性能是大数据与多图 dashboard 场景下的正确性维度。修改 render、update、state、animation、release 路径时，需要考虑 10k 图元和多 chart 页面。
- 测试应锁定有效用法下的预期行为。不要把偶然用法或不支持用法固化成兼容承诺，除非该行为已经被明确纳入 API。

## 文档规范

- 当前项目文档优先使用中文编写。
- 面向外部生态或已有多语言体系的文档，可按现有文档结构补充对应语言版本，但中文说明应优先完整、准确。

## 优先级

1. 有效 spec 和文档化 API 下的正确渲染。
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)。测试不替代必要的单元、性能及发版前全量测试。

More agent context in VisActor/VChart

2 other files this repository gives its agents.