# Design Notes

MoonPixelAnimKit 的目标是提供可复用的像素动画资源数据层。解析、校验、运行时状态与渲染适配彼此分离，调用方可以只使用所需部分。

## 模块职责

- `types.mbt`：公共数据模型、几何类型和错误类型。
- `byte_reader.mbt`：有边界保护的小端字节读取器。
- `json_helpers.mbt`：JSON 字段读取、路径和转义辅助。
- `parser.mbt`：Aseprite sprite sheet JSON 解析。
- `ase_binary.mbt`：`.ase/.aseprite` 文件头、帧和常见 chunk 元数据解析。
- `validation.mbt`：结构、范围、命名和运行时就绪性检查。
- `runtime.mbt`：动画 clip、library、player 和确定性时间采样。
- `hitboxes.mbt`：slice 到帧级 box 表的转换与相交查询。
- `analytics.mbt`：atlas、时长、时间轴和素材策略统计。
- `naming.mbt`：编号帧序列分组与缺口诊断。
- `compatibility.mbt`：Phaser 3、Canvas 2D 和通用运行时导出预检。
- `exporters.mbt`：runtime manifest、Phaser plan、Canvas draw plan。
- `report.mbt`：CLI 使用的 text/json 报告。
- `fixtures.mbt`：完全由代码构造的测试与示例输入。

## 数据流

1. JSON 或二进制字节进入解析器，得到结构化结果或带路径/偏移的错误。
2. 校验器与策略检查器只读取模型，不修改源数据。
3. runtime、analytics、naming 和 hitbox 模块从同一模型派生确定性结果。
4. exporter 只生成目标运行时所需的数据计划，不引入渲染器依赖。

## 安全与边界

- 字节读取器对负偏移、越界和截断输入返回安全默认值，顶层解析器负责转换为显式错误。
- 动画播放器会消费完整时间增量，非法帧时长会停止播放，避免无限推进。
- compressed cel 只做识别和诊断，不对不受支持的像素流作猜测性解码。
- 所有 fixture 均在源码中构造，仓库不依赖商业素材或外部二进制样本。

## 扩展规则

新增 chunk、渲染器适配或解码能力时，应保持公共模型向后兼容，为成功、错误和截断输入补充测试，并同步 `pkg.generated.mbti`、API 文档和变更日志。压缩像素解码应作为独立模块接入，不能让基础元数据解析强制依赖第三方压缩库。