docs(09): 提交 render-anim 动画解析计划与摘要

This commit is contained in:
AncTe committed 2026-11-15 20:17:35 +08:00
1 parent ffb51a1ff9
commit d56d2a8ae4
8 files changed
+3872

No files matched your search

@@ -0,0 +1,768 @@
---
phase: 09-minimum-browser-runnable
plan: 54
type: execute
# 编号说明:09-01..09-53 均已占用,本计划使用下一个空闲编号 09-54。
# depends_on 09-52(创建包与类型骨架)与 09-53(当前 IAnimationParsedData / IAnimationAnimater 契约)。
wave: 3
depends_on:
- 09-52
- 09-53
files_modified:
- packages/render-anim/src/parse.ts
- packages/render-anim/src/animater.ts
- packages/render-anim/src/index.ts
- packages/render-anim/src/__test__/parse.test.ts
- packages/render-anim/src/__test__/animater.test.ts
- .planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md
autonomous: false
requirements: []
estimate:
# 未校准估算(confidence: low),SUMMARY 须声明。
# 成本主要在 v2 二进制解析、帧包围盒公式、动画器惰性合成、Node 环境 fake DOM 测试与类型门禁往返。
# 该估算(180k)超出 100k 智能区间预算;用户已明确接受保持单个组合计划、不拆分为 09-54 / 09-55。
# 本计划不声称符合智能区间预算,SUMMARY 必须如实记录该接受项。
tokens: 180000
raw_tokens: 180000
tasks: 6
confidence: low
must_haves:
truths:
- "**第一个 block 点是 Task 0 的 `blocking-human` 汇报关卡(AGENTS.md / D-03)**:汇报 v2 二进制布局、解析器与动画器设计、帧包围盒/原点公式、画布与 HD/AA 设置、测试与验证形态、影响范围与待批准命名;然后停下等待用户恰好回复「可以执行」。"
- "**v2 解析完整落地**:`parseRenderAnimation(buffer: ArrayBuffer): Promise<IAnimationParsedData>` 按 `ANIM` + version 2 + imageDataSize + metaDataSize 读取;图像段按 sprite count + 每 sprite 宽高 + 单个 WebP 读取;元数据按 UTF-8 JSON 读取;返回 `{ texture, bitmaps, frames, blend }`,不实现 v1 兼容。"
- "**浏览器 API 且无 Node/原生依赖**:解析使用 `DataView`、`Uint8Array`、`TextDecoder`、`Blob`、`createImageBitmap` 与 `new Texture(...)`;生产代码不引用 Node 缓冲、原生图像库、文件系统或进程 API。"
- "**校验覆盖畸形输入**:签名、版本、总长度、imageDataSize / metaDataSize、sprite 数量与尺寸、bitmap 数量、bitmap 越界、帧对象索引、ratio、blend、opacity、mirror、音效字段均被校验;失败抛出明确错误。"
- "**帧包围盒 / 原点公式确定**:`eff = rawScale * ratio`;`w = bitmap.width * eff / 100`、`h = bitmap.height * eff / 100`;`hx = (w/2)*|cos a| + (h/2)*|sin a|`、`hy = (w/2)*|sin a| + (h/2)*|cos a|`;`width = max(1, ceil(maxX - minX))`、`height = max(1, ceil(maxY - minY))`、`originX = -minX`、`originY = -minY`;空帧为 1x1、原点 0,0。"
- "**动画器惰性合成**:`RenderAnimater implements ITextureAnimater<IAnimationParsedData>`;`once` / `cycled` 逐帧创建 `MotaOffscreenCanvas2D`,调用 `setHD(false)`、`setAntiAliasing(false)`、`size(frame.width, frame.height)`,按旧的居中变换绘制,yield `{ source: canvas.canvas, rect: { x: 0, y: 0, w: frame.width, h: frame.height } }`;下次 `.next()` 恢复后清理/释放上一帧画布,正常完成时释放最后一帧;提前 `.return()` 不清理、交给 GC(SUMMARY 如实记录);不使用 `try/finally`;空帧 yield 透明 1x1;不 dispose 源纹理;不包含帧计时。"
- "**出口与测试**:`index.ts` 依次导出 `./types`、`./parse`、`./animater`;`parse.test.ts` 与 `animater.test.ts` 在 Node 环境用 fake DOM / fake canvas 与 mock `createImageBitmap` 覆盖解析、校验、帧数学、生成器序列、清理与不 dispose 纹理;targeted vitest、prettier、eslint 通过;过滤后的 `vue-tsc` 通过(或 SUMMARY 明确写「类型检查未运行」)。"
- "**范围受控且不提交**:只写 `files_modified` 的 6 个路径;`types.ts`、`package.json`、其它包、配置、既有计划/摘要均不改;不新增依赖;不跑游戏 / 浏览器 / dev server;0 次提交。"
artifacts:
- path: packages/render-anim/src/parse.ts
provides: "v2 二进制解析器 `parseRenderAnimation`、内部 raw 类型与校验、帧包围盒/原点计算"
- path: packages/render-anim/src/animater.ts
provides: "`RenderAnimater implements ITextureAnimater<IAnimationParsedData>`,逐帧惰性合成与清理"
- path: packages/render-anim/src/index.ts
provides: "包根导出:`./types`、`./parse`、`./animater`"
- path: packages/render-anim/src/__test__/parse.test.ts
provides: "解析、校验与帧数学的 Node 安全测试"
- path: packages/render-anim/src/__test__/animater.test.ts
provides: "生成器序列、绘制参数、清理与不 dispose 纹理的 Node 安全测试"
- path: .planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md
provides: "实现结果、公式、测试与门禁真实输出、未做项、未校准估算、0 次提交"
key_links:
- "`parseRenderAnimation` → `new Blob([webpBytes], { type: 'image/webp' })` → `createImageBitmap` → `new Texture(image)` → `IAnimationParsedData.texture`"
- "`IAnimationObject.scale` 保存 `rawScale * ratio`(有效百分数)→ `RenderAnimater` 用 `bitmap.width * object.scale / 100` 计算真实尺寸,因此 `IAnimationParsedData` 不需要 ratio 成员"
- "`RenderAnimater` → `MotaOffscreenCanvas2D` → yield `{ source: canvas.canvas, rect }`,其中 `source` 是 `HTMLCanvasElement` 而不是画布包装对象"
- "`ITextureAnimater<IAnimationParsedData>` ← `@motajs/render` 根导出 ← `packages/render/src/assets/types.ts`;`once` / `cycled` 的 `data` 是 09-53 固定的纯解析数据"
- "`index.ts` 的三个星号导出 ↔ 消费方从 `@motajs/render-anim` 直接取得类型、解析器与动画器"
- "测试文件在 `vi.hoisted` 中先安装 fake DOM / fake canvas,再导入解析器 / 动画器;因为 `@motajs/render` 根桶在模块加载期就会创建离屏画布"
assumptions:
- "**工作树基线(规划日实测)**:09-52 创建的 `packages/render-anim` 的 `package.json`、`src/types.ts`、`src/index.ts` 已提交(HEAD `7bf9fe9`,代码提交 `81a7956`),当前 `git status --porcelain -uall -- packages/render-anim` 为空;09-53 已把 `types.ts` 改为 `IAnimationParsedData` + `IAnimationAnimater`,当前 `types.ts` 含 1 个 `export const enum` + 5 个 `export interface` + 1 个 `export type`。"
- "**`@motajs/render` 导出(规划日实测)**:`Texture`(`packages/render/src/assets/texture.ts`)、`MotaOffscreenCanvas2D`(`packages/render/src/core/canvas2d.ts`)、`ITextureAnimater<T>` / `ITextureRenderable` / `ITexture`(`packages/render/src/assets/types.ts`)、`SizedCanvasImageSource`(`packages/render/src/types.ts`)均可从包根取得。`Texture` 构造器接受 `SizedCanvasImageSource`,`MotaOffscreenCanvas2D` 构造器使用 `document.createElement('canvas')` 与 `devicePixelRatio`。"
- "**模块加载期 DOM 依赖(规划日实测)**:`packages/render/src/core/graphics.ts` 第 30 行、`packages/render/src/core/misc.ts` 第 21 行、`packages/render/src/core/utils.ts` 第 4 行在模块加载期创建画布或检测 WebGL,因此 Node 测试必须在导入前用 `vi.hoisted` 安装 fake DOM / fake canvas / `devicePixelRatio`。不得修改 `packages/render` 来规避。"
- "**旧引擎语义(规划日实测)**:`D:/github/mota-js/libs/maps.js:3068-3092` 的 `_drawAnimateFrame`;`D:/github/mota-js/libs/ui.js:572-625` 的居中变换顺序为 `translate → scale(镜像)→ rotate → drawImage(-w/2, -h/2, w, h)`。旧格式与容器参考 `D:/github/motajs-monorepo/packages/libs/h5animate/lib/{types,encoder,decoder,converter,webp}.ts`,只参考容器/布局,不复用 `sharp`。"
- "**工具链(规划日实测)**:`node` v24.21.0;`node_modules/vitest/vitest.mjs`、`node_modules/prettier/bin/prettier.cjs`、`node_modules/eslint/bin/eslint.js`、`node_modules/vue-tsc/bin/vue-tsc.js` 均存在;根 `vite.config.ts` 已把 `@motajs/*` 映射到 `packages/*/src`,`vitest` 可直接运行包内测试。"
- "**本 run 无 RESEARCH / 无 VALIDATION**:本阶段无 requirement ID(`requirements: []`),Nyquist 不适用;spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip)。"
prohibitions:
- "不得在用户恰好回复「可以执行」之前执行任何任务或派发执行子代理(AGENTS.md / D-03)。"
- "不得修改 `packages/render-anim/src/types.ts`(公开类型固定)、`packages/render-anim/package.json`、根配置、锁文件、其它包或任何既有计划 / 摘要;不得新增依赖或 vitest setup 配置。"
- "不得实现 v1 兼容、`sharp`、Node 缓冲 / 文件系统 / 进程 API;生产代码不得出现类型专用导入、`any`、顶层副作用、导出变量或 `export default`。"
- "不得把 `MotaOffscreenCanvas2D` 本身作为 `ITextureRenderable.source`(必须是 `canvas.canvas`);不得在动画器内实现帧计时、循环定时或请求动画帧。"
- "不得 dispose / close 传入的源纹理;不得让解析器在成功返回后仍持有未交给调用方的 ImageBitmap。"
- "不得改写用户给定的 v2 布局、公开类型名、成员名与语义;新增公开 / 受保护 / 私有命名必须先经 Task 0 批准。"
- "不得运行游戏、浏览器、dev server 或 `pnpm install`;不得执行任何 git 写命令,本计划全程 0 次提交。"
open_items:
- "**OI-1(Task 0 批准)**:导出解析器名 `parseRenderAnimation`;内部接口名 `IAnimationHeader` / `IRawAnimationMeta` / `IRawAnimationFrame` / `IRawAnimationObject` / `IRawAnimationSound` / `IRawAnimationBitmap` / `ISpriteDimension` / `IFrameBox`;内部函数名 `readHeader` / `readSpriteDimensions` / `readRawMeta` / `validateMeta` / `validateBitmapBounds` / `toFrame` / `toObject` / `computeFrameBox` / `toBlendMode` / `isRecord` / `isNumber` / `isInteger`;常量名 `ANIMATION_SIGNATURE` / `ANIMATION_VERSION` / `ANIMATION_HEADER_SIZE`;动画器私有方法 `composeFrame` / `sequence`。"
- "**OI-2(Task 0 批准)**:公开类型没有 ratio 成员,因此解析器把 `ratio` 折入 `IAnimationObject.scale`(保存 `rawScale * ratio`,仍是百分数),动画器用 `/ 100` 计算真实尺寸;这是在不改 `types.ts` 前提下的唯一可行语义。"
- "**OI-3(用户已决定 1B,无需再批准)**:生产代码不使用 `try/finally`。清理策略:下次 `.next()` 恢复后清理/释放上一帧画布;正常完成时释放最后一帧画布;提前 `.return()` 跳过正常结束路径,最后一帧交给 GC,本计划不承诺 `.return()` 清理,SUMMARY 如实记录该取舍。"
- "**OI-4(Task 0 批准)**:raw 帧对象元组按 `[index, x, y, scale, opacity, mirror?, rotate?]` 接受 5–7 个元素,缺省 `mirror` / `rotate` 为 0;其余字段严格校验。"
- "**OI-5(只记录)**:解析器不修改 `Texture.isBitmap`;`data.texture` 由调用方拥有,调用方负责 `dispose()`。"
- "**OI-6(只记录,可见跳过)**:运行时浏览器行为不做 E2E 测试;测试只在 Node 环境以 fake DOM / fake canvas / mock `createImageBitmap` 验证纯逻辑与绘制调用参数。"
- "**OI-7(用户已接受)**:`estimate` 为 180k(`confidence: low`,未校准),超出 100k 智能区间预算;用户明确接受保持单个组合计划、不拆分为 09-54 / 09-55,本计划不声称符合智能区间预算,SUMMARY 必须如实记录该接受项。"
- "**OI-8(只记录)**:09-52 / 09-53 产物已提交(HEAD `7bf9fe9`);本计划不提交任何内容,改动留在工作树供审阅。"
- "**OI-9(只记录限制)**:sprite 尺寸表只用于校验 `>= 1` 与计算 WebP 偏移,不与元数据 `bitmaps` 或解码后的 `image.width` / `image.height` 交叉比对;裁剪矩形以 `bitmaps` 为准。计划不推测性拒绝,SUMMARY 如实记录该限制。"
- "**OI-10(只记录限制)**:Task 5 的范围闸门以 Task 1 的 `git status --porcelain -uall` 路径集合为基线:相关根之外的新增与删除条目(`addedOut` / `removedOut`)必须为空,相关根之内的新增条目必须恰为允许集合、`removedIn` 必须为空,从而保留「不越界写包外文件」的保证;但基线时已存在的脏条目若被外部改动、其内容变化在 porcelain 路径集合中不可见(同一条目仍是脏的)。本计划执行期间不并发修改工作树,且 `packages/render-anim` 在 Task 1 已断言干净,故该盲区被限制在包外既有脏条目;SUMMARY 如实记录该限制。"
---
<!-- planner-discipline-allow: Buffer -->
<!-- planner-discipline-allow: sharp -->
<!-- planner-discipline-allow: require( -->
<!-- planner-discipline-allow: node: -->
<!-- planner-discipline-allow: import type -->
<!-- planner-discipline-allow: any -->
<!-- planner-discipline-allow: texture.dispose -->
<!-- planner-discipline-allow: data.texture.dispose -->
<!-- planner-discipline-allow: RenderAnimater -->
<!-- planner-discipline-allow: parseRenderAnimation -->
<!-- planner-discipline-allow: IAnimationParsedData -->
<!-- planner-discipline-allow: IAnimationAnimater -->
<!-- planner-discipline-allow: finally -->
<!-- planner-discipline-allow: try/finally -->
<objective>
Phase 9 · 第 54 个计划(09-52 / 09-53 的实现增量)—— 实现浏览器专用 `@motajs/render-anim` 的运行时:v2 二进制解析器 + `RenderAnimater` + 包根导出 + Node 安全测试。
**要解决的问题:** 09-52 只落了包骨架,09-53 只固定了 `IAnimationParsedData` / `IAnimationAnimater` 类型契约;当前 `index.ts` 仍只有 `export * from './types';`,包没有任何可运行能力。本计划把 v2 `.animate` 二进制解析成 `IAnimationParsedData`,并实现能把每帧合成为离屏画布、交给渲染系统的 `RenderAnimater`。
**做法(锁定设计):**
- `packages/render-anim/src/parse.ts`:实现 `parseRenderAnimation(buffer: ArrayBuffer): Promise<IAnimationParsedData>`;解析 `ANIM` + version 2 头部、sprite 尺寸表、单个 WebP、UTF-8 JSON 元数据;用 `DataView` / `Uint8Array` / `TextDecoder` / `Blob` / `createImageBitmap` 与 `new Texture(...)`;校验全部畸形输入;按旧引擎居中语义计算每帧 `width/height/originX/originY`;把 `ratio` 折入 `IAnimationObject.scale`。
- `packages/render-anim/src/animater.ts`:实现 `RenderAnimater implements ITextureAnimater<IAnimationParsedData>`;`once` / `cycled` 逐帧惰性创建 `MotaOffscreenCanvas2D`,关闭 HD 与抗锯齿,按 `translate → mirror → rotate → drawImage` 绘制;yield `canvas.canvas` + `{ x: 0, y: 0, w, h }`;下次 `.next()` 恢复后清理并释放上一帧画布,正常完成时释放最后一帧,提前 `.return()` 交给 GC(不使用 `try/finally`);空帧为透明 1x1;不 dispose 源纹理;不包含帧计时。
- `packages/render-anim/src/index.ts`:导出 `./types`、`./parse`、`./animater`。
- `packages/render-anim/src/__test__/parse.test.ts` / `animater.test.ts`:Node 环境 fake DOM / fake canvas / mock `createImageBitmap`;覆盖解析、校验、帧数学、生成器序列、清理与不 dispose 纹理。
**约束:** 只写 `files_modified` 的 6 个路径;不改 `types.ts` / `package.json` / 其它包 / 配置 / 既有计划;不新增依赖;不跑游戏 / 浏览器 / dev server;不提交。(D-01 增量派发 / D-02 计划累积追加 / D-03 执行前汇报 / D-04 命名先反馈 / D-05 默认不逐阶段验证 / D-06 范围由用户界定。)
**修改方式声明(AGENTS.md):** 执行期间的全部源码、测试与 `09-54-SUMMARY.md` 写入均由**派发子代理(`gsd-executor`)执行**,非内联执行;本计划文件自身由规划流程(`gsd-planner`)创建。除 `files_modified` 外无任何写入。
**可见跳过:** spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip)。本阶段无 requirement ID,不创建 RESEARCH.md / VALIDATION.md,Nyquist 验证不适用。
</objective>
## 本计划产出物(Artifacts this plan produces)
| 类型 | 名称 / 路径 | 说明 |
|------|-------------|------|
| 新建(解析器) | `packages/render-anim/src/parse.ts` | `parseRenderAnimation` + 内部 raw 类型 / 校验 / 帧数学 |
| 新建(动画器) | `packages/render-anim/src/animater.ts` | `RenderAnimater implements ITextureAnimater<IAnimationParsedData>` |
| 修改(导出) | `packages/render-anim/src/index.ts` | 三行星号导出:`./types`、`./parse`、`./animater` |
| 新建(测试) | `packages/render-anim/src/__test__/parse.test.ts` | 解析、校验、帧数学测试 |
| 新建(测试) | `packages/render-anim/src/__test__/animater.test.ts` | 生成器、绘制参数、清理测试 |
| 交付 | `.planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md` | 实现结果、公式、门禁真实输出、未做项、未校准估算、0 次提交 |
| 只验证不修改 | `packages/render-anim/src/types.ts` | 公开类型固定,哈希与 Task 1 基线一致 |
| 只验证不修改 | `packages/render-anim/package.json` | 仅 `name` + `@motajs/render: workspace:*`,哈希与 Task 1 基线一致 |
## v2 二进制布局(解析器的唯一字节依据)
| 偏移 | 长度 | 字段 | 说明 |
|------|------|------|------|
| 0 | 4 | signature | ASCII `ANIM`;按大端 UInt32 读为 `0x414E494D` |
| 4 | 4 | version | UInt32LE,必须为 `2` |
| 8 | 4 | imageDataSize | UInt32LE,图像段总字节数(含 sprite 表与 WebP) |
| 12 | 4 | metaDataSize | UInt32LE,元数据 JSON 字节数 |
| 16 | 4 | spriteCount | UInt32LE,必须 ≥ 1 |
| 20 | spriteCount × 8 | sprite dimensions | 每个 sprite 依次 `width` / `height`,各 UInt32LE,必须 ≥ 1 |
| `20 + spriteCount * 8` | `imageDataSize - 4 - spriteCount * 8` | WebP | 单个 WebP 图像块,长度必须 ≥ 1 |
| `16 + imageDataSize` | `metaDataSize` | metadata | UTF-8 JSON,长度必须 ≥ 1 |
**总长度恒等式:** `buffer.byteLength === 16 + imageDataSize + metaDataSize`;不满足即拒绝。头部固定 16 字节;`imageDataSize` 覆盖从偏移 16 开始的整段图像数据(含 4 字节 spriteCount 与 sprite 尺寸表)。
**sprite 尺寸表的用途与已知限制:** sprite 宽高在读表时校验为 `>= 1`,sprite 数量用于计算 WebP 起始偏移;除此之外不与元数据 `bitmaps` 或解码后的 `image.width` / `image.height` 交叉比对。现有格式未给出「sprite 表尺寸必须等于 bitmap 尺寸或解码图尺寸之和」的依据,推测性拒绝可能误杀合法文件,因此裁剪矩形一律以元数据 `bitmaps` 为准。该限制必须由 Task 5 的 SUMMARY 如实记录。
**元数据 JSON(`IRawAnimationMeta`,用户给定):**
```ts
type IRawAnimationObject = [
index: number,
x: number,
y: number,
scale: number,
opacity: number,
mirror?: number,
rotate?: number,
];
interface IRawAnimationSound {
name: string;
volume?: number;
pitch?: number;
}
interface IRawAnimationBitmap {
x: number;
y: number;
width: number;
height: number;
}
interface IRawAnimationFrame {
objects?: IRawAnimationObject[];
sound?: IRawAnimationSound[];
}
interface IRawAnimationMeta {
ratio: number;
blend: number; // 0 = normal, 1 = add
bitmaps: IRawAnimationBitmap[];
frame: IRawAnimationFrame[];
}
```
`ratio` 为动画整体缩放系数;`blend` 映射到 `AnimationBlendMode.Normal` / `AnimationBlendMode.Add`。`objects` 元组固定 5–7 个元素:前 5 个必填,`mirror` / `rotate` 可选,缺省为 0;`bitmaps` 一律使用 `IRawAnimationBitmap`,`sound` 一律使用 `IRawAnimationSound`,文件中不得出现内联重复的对象类型。
## 解析器设计(`parse.ts`)
**公开入口:** `export async function parseRenderAnimation(buffer: ArrayBuffer): Promise<IAnimationParsedData>`。
**解析与校验顺序(先纯字节/JSON 校验,再解码图像,避免解码后才发现结构错误):**
1. `new DataView(buffer)`;读头部:签名、版本、`imageDataSize`、`metaDataSize`;执行总长度恒等式与最小长度校验。
2. 读 `spriteCount` 与每个 sprite 的宽高;要求 `spriteCount >= 1`、`4 + spriteCount * 8 < imageDataSize`、每个宽高 `>= 1`。
3. 切出 WebP 字节(`webpOffset = 20 + spriteCount * 8`、`webpSize = imageDataSize - 4 - spriteCount * 8`)与元数据字节(`metaOffset = 16 + imageDataSize`)。
4. `new TextDecoder('utf-8').decode(metaBytes)` 后 `JSON.parse`;**不写 `try-catch`**,JSON 语法错误由 `JSON.parse` 直接抛出。
5. 校验 raw 元数据:`ratio` 有限且 `> 0`;`blend` 为 `0` 或 `1`;`bitmaps` 为数组且长度等于 `spriteCount`;每个 bitmap 的 `x/y` 有限且 `>= 0`、`width/height` 有限且 `>= 1`;`frame` 为数组;每帧 `objects` 若存在则为数组,每个元组长度 5–7,`index` 为整数且在 `[0, bitmaps.length)`,`x/y/scale/opacity/rotate` 有限,`scale > 0`,`opacity` 在 `[0, 255]`,`mirror` 为有限数字(缺省 0;非 0 即镜像),`rotate` 缺省 0;每帧 `sound` 若存在则为数组,`name` 为非空字符串,`volume` / `pitch` 若存在则有限。
6. `await createImageBitmap(new Blob([webpBytes], { type: 'image/webp' }))` 得到 `ImageBitmap`。
7. 用解码后的 `image.width` / `image.height` 校验每个 bitmap 在纹理范围内:`x >= 0`、`y >= 0`、`width >= 1`、`height >= 1`、`x + width <= image.width`、`y + height <= image.height`;失败时先 `image.close()` 再抛出,避免泄漏。
8. `const texture = new Texture(image)`。
9. 逐帧转换:`objects` 用 `toObject`(`scale = rawScale * ratio`,`mirror` / `rotate` 缺省 0);用 `computeFrameBox` 计算 `width/height/originX/originY`;`sound` 原样保留可选字段。
10. 返回 `{ texture, bitmaps, frames, blend }`;`bitmaps` 使用 raw 元数据中的 `x/y/width/height`,不按 ratio 改尺寸(它们是纹理源裁剪矩形)。
**错误策略:** 所有校验失败抛出 `Error`,消息为明确中文(例如签名无效、版本不支持、长度不符、sprite 数量无效、位图越界、帧对象索引越界、混合模式无效);不写 `try-catch`,不吞掉 `JSON.parse` / `createImageBitmap` 的错误。
**浏览器 API 约束:** `DataView` / `Uint8Array` / `TextDecoder` / `Blob` / `createImageBitmap` / `Texture`;生产代码不引入 Node 内置模块、原生图像库或文件系统 API。
## 帧包围盒 / 原点公式(解析器与动画器共用)
**记号:** 对帧内每个对象 `i`:
- `eff_i = rawScale_i * ratio`(解析器存入 `IAnimationObject.scale` 的有效百分数)
- `w_i = bitmap.width * eff_i / 100`
- `h_i = bitmap.height * eff_i / 100`
- `a_i = rotate_i * PI / 180`
- `hx_i = (w_i / 2) * |cos(a_i)| + (h_i / 2) * |sin(a_i)|`
- `hy_i = (w_i / 2) * |sin(a_i)| + (h_i / 2) * |cos(a_i)|`
- `left_i = x_i - hx_i`、`right_i = x_i + hx_i`
- `top_i = y_i - hy_i`、`bottom_i = y_i + hy_i`
**并集(无对象时全部取 0):**
- `minX = min(left_i)`、`maxX = max(right_i)`
- `minY = min(top_i)`、`maxY = max(bottom_i)`
**帧尺寸与原点:**
- `width = max(1, ceil(maxX - minX))`
- `height = max(1, ceil(maxY - minY))`
- `originX = -minX`(动画中心在帧画布内的横坐标)
- `originY = -minY`
**镜像:** `mirror` 只影响绘制方向;矩形以对象中心为轴翻转后,轴对齐包围盒不变,因此不进入 `hx_i` / `hy_i` 公式。
**绘制位置(动画器):** 对象中心在帧画布内为 `(originX + x_i, originY + y_i)`;先 `translate` 到该点,再按旧顺序 `scale(-1, 1)`(mirror)→ `rotate(-rotate_i * PI / 180)` → `drawImage(source, bitmap.x, bitmap.y, bitmap.width, bitmap.height, -w_i/2, -h_i/2, w_i, h_i)`。
**算例 1(无旋转):** 单个 32×32 bitmap,`ratio = 1`、`rawScale = 100`、`x = y = 0`、`rotate = 0`。`eff = 100`、`w = h = 32`、`hx = hy = 16`;`minX = -16`、`maxX = 16`、`minY = -16`、`maxY = 16`;`width = height = 32`、`originX = originY = 16`;绘制中心 `(16, 16)`,左上角 `(0, 0)`。
**算例 2(45° 旋转):** 同上但 `rotate = 45`。`hx = hy = 16 * 0.7071 + 16 * 0.7071 ≈ 22.627`;`width = height = ceil(45.254) = 46`;`originX = originY ≈ 22.627`。
**算例 3(空帧):** `objects` 为空;`minX = maxX = minY = maxY = 0`;`width = height = 1`、`originX = originY = 0`;动画器返回透明 1x1。
## 动画器设计(`animater.ts`)
- `export class RenderAnimater implements ITextureAnimater<IAnimationParsedData>`。
- `once(texture, data)` / `cycled(texture, data)` 返回 `Generator<ITextureRenderable, void>`;二者委托私有生成器 `sequence(texture, data, cycled)`,`once` 走一遍,`cycled` 回到第 0 帧无限循环。
- `sequence` 在 `data.frames.length === 0` 时直接 `return`(不 yield)。
- 每帧调用私有 `composeFrame(texture, data, frame)`:
- `const canvas = new MotaOffscreenCanvas2D();`
- `canvas.setHD(false);`
- `canvas.setAntiAliasing(false);`
- `canvas.size(frame.width, frame.height);`(`size` 会 clamp 到至少 1×1)
- 遍历 `frame.objects`,按上文公式绘制;每个对象 `ctx.save()` / `ctx.restore()`,`ctx.globalAlpha = object.opacity / 255`。
- 返回 `canvas`。
- yield `{ source: canvas.canvas, rect: { x: 0, y: 0, w: frame.width, h: frame.height } }`;`source` 必须是 `HTMLCanvasElement`(`canvas.canvas`),不能是 `MotaOffscreenCanvas2D` 包装对象。
- **清理策略(用户决定 1B,不使用 `try/finally`):** `sequence` 用局部变量保留上一帧画布引用;每次 `.next()` 从 yield 恢复后、合成新帧之前,先对上一帧执行 `canvas.clear()` 并把 `canvas.canvas.width` / `canvas.canvas.height` 设为 `0` 释放后备存储。`once` 走完最后一帧、生成器正常结束时,释放最后一帧画布。提前调用 `.return()` 会跳过正常结束路径,最后一帧画布不做清理、交给 GC;这是有意的取舍,SUMMARY 必须如实记录,本计划不承诺 `.return()` 清理。
- 空帧没有对象,`composeFrame` 仍创建 1×1 画布,不调用 `drawImage`,yield 透明 1×1。
- 不实现帧计时 / 循环定时 / 请求动画帧;`once` / `cycled` 只控制帧序列。
- 不调用 `texture.dispose()` / `data.texture.dispose()`;源纹理由调用方拥有。
## 导出与命名(Task 0 逐项批准)
| 类别 | 名称 | 说明 |
|------|------|------|
| 导出函数 | `parseRenderAnimation` | `(buffer: ArrayBuffer) => Promise<IAnimationParsedData>` |
| 导出类 | `RenderAnimater` | `implements ITextureAnimater<IAnimationParsedData>` |
| 内部接口 | `IAnimationHeader` | `imageDataSize` / `metaDataSize` |
| 内部接口 | `IRawAnimationMeta` | 用户给定的 raw 元数据 |
| 内部接口 | `IRawAnimationFrame` | `objects?` / `sound?` |
| 内部类型 | `IRawAnimationObject` | `[index, x, y, scale, opacity, mirror?, rotate?]` |
| 内部接口 | `IRawAnimationSound` | `name` / `volume?` / `pitch?` |
| 内部接口 | `IRawAnimationBitmap` | `x` / `y` / `width` / `height` |
| 内部接口 | `ISpriteDimension` | `width` / `height` |
| 内部接口 | `IFrameBox` | `width` / `height` / `originX` / `originY` |
| 内部函数 | `readHeader` / `readSpriteDimensions` / `readRawMeta` / `validateMeta` / `validateBitmapBounds` / `toFrame` / `toObject` / `computeFrameBox` / `toBlendMode` | 解析、校验、转换 |
| 内部类型守卫 | `isRecord` / `isNumber` / `isInteger` | 运行时校验 |
| 内部常量(不导出) | `ANIMATION_SIGNATURE` / `ANIMATION_VERSION` / `ANIMATION_HEADER_SIZE` | `0x414e494d` / `2` / `16` |
| 私有方法 | `composeFrame` / `sequence` | 单帧合成 / 帧序列 |
| 导出文件 | `src/index.ts` | 依次 `export * from './types';`、`export * from './parse';`、`export * from './animater';` |
**不得新增表中之外的公开名称;内部辅助名称若需调整,先在 Task 0 说明。**
**jsDoc 要求:** 公开导出 `parseRenderAnimation` 必须带中文 jsDoc(入参 `ArrayBuffer`、返回 `Promise<IAnimationParsedData>`、失败时抛出错误);`RenderAnimater` 类与公开方法 `once` / `cycled` 必须带中文 jsDoc(惰性逐帧合成、yield 的 `source` / `rect`、清理语义:下次 `.next()` 清理上一帧、正常完成释放最后一帧、提前 `.return()` 交给 GC)。内部接口 / 函数按 dev.md 在源头写注释,不得复述代码。
## 覆盖审计(Multi-Source Coverage Audit)
| 源 | 条目 | 覆盖位置 |
|----|------|----------|
| GOAL(ROADMAP §Phase 9) | 「可在浏览器中运行并验证的最小版本」 | 本计划提供动画解析与合成运行时,是渲染端可运行能力的一部分 |
| REQ | 本阶段无 requirement ID(`requirements: []`) | Nyquist 不适用(可见跳过) |
| RESEARCH | 本 run 无 RESEARCH.md | 使用旧引擎 `maps.js` / `ui.js` 与 h5animate 容器参考 |
| CONTEXT D-01 | 增量派发,一个任务一个计划 | 本计划即该派发的唯一计划 |
| CONTEXT D-02 | 计划可累积追加 | plan 54,排在 09-01..09-53 之后(编号说明见 frontmatter) |
| CONTEXT D-03 | 执行前必须先汇报并等待「可以执行」 | Task 0(`blocking-human`),`autonomous: false` |
| CONTEXT D-04 | 新命名必须先反馈获批 | 「导出与命名」表 + Task 0 逐项批准 |
| CONTEXT D-05 | 默认不逐阶段验证 | 本计划仍做 targeted vitest / 静态门禁;不做浏览器 E2E |
| CONTEXT D-06 | 范围由用户界定 | `files_modified` 6 项 + Task 5 范围 / 哈希门禁 |
| 用户设计 | v2 头部 / sprite 表 / 单 WebP / UTF-8 JSON | 「v2 二进制布局」+ Task 2 |
| 用户设计 | 浏览器 API,无 Node 缓冲 / 原生图像库 / v1 兼容 | `<objective>` + Task 2 / Task 3 静态门禁 |
| 用户设计 | 位图范围与帧对象索引校验 | 「解析器设计」第 5–7 步 + Task 2 + Task 4 测试 |
| 用户设计 | 帧包围盒 / 原点公式(scale / rotate / mirror) | 「帧包围盒 / 原点公式」+ Task 2 + Task 4 测试 |
| 用户设计 | 空帧 1x1、原点 0,0、透明输出 | 公式算例 3 + Task 2 / Task 3 / Task 4 |
| 用户设计 | `RenderAnimater` 惰性画布、HD/AA 关闭、清理、不 dispose 纹理、无计时 | 「动画器设计」+ Task 3 + Task 4 测试 |
| 用户设计 | `index.ts` 三个导出 | 「导出与命名」+ Task 3 |
| 用户设计 | Node 安全测试、不跑游戏 / 浏览器 / dev server | Task 4 + `<verification>` |
| 用户设计 | 不改 `types.ts` / `package.json`、不新增依赖、不提交 | Task 1 / Task 3 / Task 5 哈希与范围门禁 |
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/09-minimum-browser-runnable/09-CONTEXT.md
@AGENTS.md
@dev.md
@packages/render-anim/src/types.ts
@packages/render-anim/src/index.ts
@packages/render-anim/package.json
@.planning/phases/09-minimum-browser-runnable/09-52-PLAN.md
@.planning/phases/09-minimum-browser-runnable/09-52-SUMMARY.md
@.planning/phases/09-minimum-browser-runnable/09-53-PLAN.md
@.planning/phases/09-minimum-browser-runnable/09-53-SUMMARY.md
@packages/render/src/assets/types.ts
@packages/render/src/assets/texture.ts
@packages/render/src/assets/animater.ts
@packages/render/src/core/canvas2d.ts
@packages/render/src/types.ts
@vite.config.ts
@tsconfig.json
@.prettierrc
@eslint.config.js
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 预执行汇报关卡 —— 汇报 v2 布局、解析器与动画器设计、帧公式、画布策略、测试形态、影响与命名,等待恰好「可以执行」</name>
<precondition>`packages/render-anim/src/types.ts` 已含 `IAnimationParsedData` 与 `IAnimationAnimater`;`packages/render-anim/src/index.ts` 仍只有 `export * from './types';`;`packages/render-anim/package.json` 仅含 `name` 与 `@motajs/render: workspace:*`;`node_modules` 内 vitest / prettier / eslint / vue-tsc 均存在。</precondition>
<files>无(本任务只读,不写任何文件;汇报后停下等待「可以执行」)</files>
<read_first>
- `.planning/phases/09-minimum-browser-runnable/09-CONTEXT.md`(D-01 增量派发、D-03 汇报关卡、D-04 命名批准、D-06 范围界定)
- `AGENTS.md`(执行前须获批、命名先反馈、既有注释不得修改、最小修改也走 GSD、不派发额外子代理)
- `dev.md`(CRLF、4 空格、首行 import、禁止类型专用导入、无必要 `any`、模块无副作用、公开接口放 `types.ts`、不转发导出)
- `packages/render-anim/src/types.ts`、`packages/render-anim/src/index.ts`、`packages/render-anim/package.json`
- `packages/render/src/assets/types.ts`(`ITextureAnimater` / `ITextureRenderable` / `ITexture`)、`packages/render/src/assets/texture.ts`(`Texture` 构造与 `source`)、`packages/render/src/core/canvas2d.ts`(`setHD` / `setAntiAliasing` / `size` / `clear` / `canvas`)
- `D:/github/mota-js/libs/maps.js:3068-3092`(旧动画帧绘制)、`D:/github/mota-js/libs/ui.js:572-625`(居中变换顺序)
- `D:/github/motajs-monorepo/packages/libs/h5animate/lib/types.ts`、`decoder.ts`、`encoder.ts`(容器布局参考,不复用 `sharp`)
- 本计划的「v2 二进制布局」「解析器设计」「帧包围盒 / 原点公式」「动画器设计」「导出与命名」五节
- `vite.config.ts`、`tsconfig.json`、`.prettierrc`、`eslint.config.js`(测试与门禁配置)
</read_first>
<what-built>
一份待批准的浏览器动画运行时实现计划(`09-54-PLAN.md`):在 09-52 包骨架与 09-53 类型契约之上,新增 v2 二进制解析器 `parseRenderAnimation`、逐帧惰性合成 `RenderAnimater`、包根导出与 Node 安全测试;不实现 v1 兼容、不新增依赖、不提交。本计划为单个组合计划,不拆分为 09-54 / 09-55。
</what-built>
<action>
**停下并向用户汇报,等待其恰好回复「可以执行」后才继续;本任务不写任何文件、不建目录、不派发执行子代理。**
① **要做什么 / 为什么:** 09-52 只创建了包骨架,09-53 只固定了类型;`index.ts` 目前只有 `export * from './types';`,包没有解析与合成能力。本计划实现浏览器专用 v2 动画运行时:把 `.animate` 二进制解析为 `IAnimationParsedData`,并用 `RenderAnimater` 把每帧合成为离屏画布交给渲染系统。
② **v2 二进制布局:** 头部 16 字节 = `ANIM`(大端 UInt32 `0x414E494D`)+ UInt32LE version `2` + UInt32LE `imageDataSize` + UInt32LE `metaDataSize`;偏移 16 起为 UInt32LE `spriteCount` + 每 sprite 的 UInt32LE `width` / `height` + 单个 WebP;偏移 `16 + imageDataSize` 起为 `metaDataSize` 字节 UTF-8 JSON。总长度必须严格等于 `16 + imageDataSize + metaDataSize`。元数据字段为 `ratio` / `blend` / `bitmaps` / `frame`(`frame.objects` 为 `[index, x, y, scale, opacity, mirror?, rotate?]` 的 5–7 元素元组数组,`frame.sound` 为可选音效数组)。
③ **解析器设计:** `parseRenderAnimation(buffer: ArrayBuffer): Promise<IAnimationParsedData>`;先校验头部 / sprite 表 / 元数据 JSON,再 `createImageBitmap(new Blob([...], { type: 'image/webp' }))`,用解码尺寸校验 bitmap 越界,最后 `new Texture(image)` 并逐帧转换;返回 `{ texture, bitmaps, frames, blend }`。所有畸形输入抛出明确错误;不写 `try-catch`;不使用 Node 缓冲 / 原生图像库 / v1 兼容。
④ **帧包围盒 / 原点公式:** `eff = rawScale * ratio`;`w = bitmap.width * eff / 100`、`h = bitmap.height * eff / 100`;`hx = (w/2)*|cos a| + (h/2)*|sin a|`、`hy = (w/2)*|sin a| + (h/2)*|cos a|`;并集求 `minX/minY/maxX/maxY`;`width = max(1, ceil(maxX - minX))`、`height = max(1, ceil(maxY - minY))`、`originX = -minX`、`originY = -minY`;空帧 1x1、原点 0,0;mirror 不改变包围盒。计划正文含无旋转、45° 旋转与空帧三个算例。
⑤ **动画器设计:** `RenderAnimater implements ITextureAnimater<IAnimationParsedData>`;`once` / `cycled` 委托 `sequence`;每帧 `new MotaOffscreenCanvas2D()`,`setHD(false)`、`setAntiAliasing(false)`、`size(frame.width, frame.height)`;按 `translate(originX + x, originY + y)` → `scale(-1, 1)`(mirror)→ `rotate(-rotate * PI / 180)` → `drawImage(...)` 绘制,`globalAlpha = opacity / 255`;yield `{ source: canvas.canvas, rect: { x: 0, y: 0, w: frame.width, h: frame.height } }`;清理策略(用户决定 1B):下次 `.next()` 恢复后 `clear()` 并把上一帧物理画布宽高设为 `0`,正常完成时释放最后一帧,提前 `.return()` 交给 GC,不使用 `try/finally`;空帧透明 1x1;不 dispose 源纹理;无帧计时。
⑥ **导出与命名:** `src/index.ts` 依次导出 `./types`、`./parse`、`./animater`;公开新增名称为 `parseRenderAnimation` 与 `RenderAnimater`;二者与 `once` / `cycled` 均须带中文 jsDoc;内部名称与私有方法见「导出与命名」表(`IAnimationHeader` / `IRawAnimation*` / `ISpriteDimension` / `IFrameBox` / `readHeader` / `readSpriteDimensions` / `readRawMeta` / `validateMeta` / `validateBitmapBounds` / `toFrame` / `toObject` / `computeFrameBox` / `toBlendMode` / `isRecord` / `isNumber` / `isInteger` / `ANIMATION_*` / `composeFrame` / `sequence`)。请逐项确认;如需改名请在批准前说明。
⑦ **测试与验证形态:** Node 环境 targeted vitest(`node node_modules/vitest/vitest.mjs run packages/render-anim`);解析器测试用自建 v2 二进制构造器、mock `createImageBitmap`、fake DOM;动画器测试用 fake canvas / fake 2D context 断言序列、绘制参数、下次 `.next()` 清理上一帧、正常完成释放最后一帧、提前 `.return()` 交给 GC;prettier / eslint / CRLF / BOM / 静态内容门禁;`vue-tsc --noEmit` 只过滤 `packages/render-anim` 诊断。**不做浏览器 E2E,不跑游戏 / dev server / 真实 WebP 素材**;运行时浏览器行为不做主张。
⑧ **影响范围:** 只写 `packages/render-anim/src/parse.ts`、`animater.ts`、`index.ts`、`__test__/parse.test.ts`、`__test__/animater.test.ts` 与 `09-54-SUMMARY.md`;不改 `types.ts`、`package.json`、其它包、根配置、锁文件、既有计划 / 摘要;不新增依赖;不运行 `pnpm install`;不执行 git 写命令,**0 次提交**。
⑨ **已定取舍与待批准项:** (a) 公开类型没有 ratio,解析器把 `ratio` 折入 `IAnimationObject.scale`(保存 `rawScale * ratio`,仍为百分数),动画器用 `/ 100`;(b) **清理策略已由用户决定为 1B**:生产代码不使用 `try/finally`,下次 `.next()` 恢复后清理上一帧、正常完成时释放最后一帧、提前 `.return()` 交给 GC(不承诺清理,SUMMARY 如实记录);(c) raw 帧对象元组接受 5–7 个元素,缺省 `mirror` / `rotate` 为 0;(d) `Texture.isBitmap` 不修改,纹理由调用方 dispose;(e) `estimate` 为 180k、超出 100k 智能区间预算,用户已明确接受保持单个组合计划、不拆分。
⑩ **等待批准:** 请确认以上内容后,回复恰好四个字「可以执行」。任何修改意见请直接说明;未收到「可以执行」之前不开始 Task 1–5 的任何一步。
</action>
<verify>用户针对本计划恰好回复「可以执行」后才进入 Task 1–5;在此之前不执行 Task 1 / Task 2 / Task 3 / Task 4 / Task 5 的任何一步,也不派发执行子代理。</verify>
<done>已完整汇报 ①–⑩(v2 布局、解析器设计、帧公式与算例、动画器设计与 1B 清理策略、导出与命名与 jsDoc、测试与验证形态、影响范围与 180k 估算接受项、已定取舍与待批准项、等待批准),并收到用户针对本计划的「可以执行」回复。</done>
<how-to-verify>
逐条核对 ①–⑩ 是否与你的意图一致,特别是:② 的 v2 字节布局与总长度恒等式;③ 的校验顺序与错误策略;④ 的帧包围盒 / 原点公式与三个算例;⑤ 的画布 HD/AA、1B 清理与空帧策略;⑥ 的命名表与 jsDoc 要求;⑦ 的 Node 测试口径与「不做浏览器 E2E」;⑧ 的范围、180k 估算接受项与 0 次提交;⑨ 的已定取舍与待批准项。
</how-to-verify>
<resume-signal>请在确认本计划(尤其是 ② 的布局、③ 的解析顺序、④ 的帧公式、⑤ 的画布清理、⑥ 的命名、⑨ 的取舍)后,回复恰好四个字「可以执行」。任何修改意见请直接说明。</resume-signal>
<acceptance_criteria>
- 已向用户逐条汇报 ①–⑩,包含 v2 布局表、解析顺序、帧公式与算例、动画器画布策略、命名表与已定取舍 / 待批准项,而不是只报两个类名。
- 已明确说明公开类型不含 ratio,故 `ratio` 折入 `IAnimationObject.scale` 的处理方式,并将其列为显式批准项。
- 已明确说明清理策略为用户决定的 1B(不使用 `try/finally`:下次 `.next()` 清理上一帧、正常完成释放最后一帧、提前 `.return()` 交给 GC),并说明不承诺 `.return()` 清理。
- 已说明 `estimate` 为 180k、超出 100k 智能区间预算,且用户已接受保持单个组合计划、不拆分。
- 已说明测试只在 Node 环境使用 fake DOM / fake canvas / mock `createImageBitmap`,不做真实浏览器或真实 WebP E2E。
- 已说明影响范围(6 个写入路径、`types.ts` / `package.json` 只验证、不新增依赖、不提交)与验证形态。
- 用户针对本计划明确回复「可以执行」后才进入 Task 1–5;在此之前未执行任何任务、未派发执行子代理。
</acceptance_criteria>
</task>
<task type="auto">
<name>Task 1: 读取当前契约与旧引擎语义,采集范围 / 哈希基线(只读,临时文件仅写 TEMP)</name>
<files>无(本任务只读仓库文件;只在 `process.env.TEMP` 目录写基线临时文件,不写仓库内任何文件)</files>
<read_first>
- `AGENTS.md`(执行前获批、命名先反馈、既有注释不得修改、最小修改也走 GSD、GSD 流程豁免范围)
- `dev.md`(CRLF、4 空格、首行 import、禁止类型专用导入、无必要 `any`、模块无副作用、公开接口放 `types.ts`、不转发导出)
- `packages/render-anim/src/types.ts`(当前 `IAnimationParsedData` / `IAnimationAnimater` / `IAnimationObject` / `IAnimationFrame` / `IAnimationBitmap` / `IAnimationSound`)
- `packages/render-anim/src/index.ts`、`packages/render-anim/package.json`(当前导出与依赖)
- `packages/render/src/assets/types.ts`(`ITexture` / `ITextureAnimater<T>` / `ITextureRenderable` / `IRect`)
- `packages/render/src/assets/texture.ts`(`Texture` 构造、`source`、`render`、`clampRect`、`dispose`)
- `packages/render/src/core/canvas2d.ts`(`MotaOffscreenCanvas2D` 构造、`setHD`、`setAntiAliasing`、`size`、`clear`、`canvas` / `ctx`)
- `packages/render/src/types.ts`(`SizedCanvasImageSource`)
- `D:/github/mota-js/libs/maps.js:3068-3092`(`_drawAnimateFrame` 的 `realWidth` / `realHeight` / `cx` / `cy` / `ix` / `iy` / `opacity` / `angle` / `mirror`)
- `D:/github/mota-js/libs/loader.js:369-385`(旧字段 `zoom` / `opacity` / `mirror` / `angle`)
- `D:/github/mota-js/libs/ui.js:572-625`(居中变换顺序 `translate → scale → rotate → drawImage`)
- `D:/github/motajs-monorepo/packages/libs/h5animate/lib/types.ts`、`decoder.ts`、`encoder.ts`(容器布局参考,不复用 `sharp`)
- `.planning/phases/09-minimum-browser-runnable/09-52-PLAN.md`、`09-52-SUMMARY.md`、`09-53-PLAN.md`、`09-53-SUMMARY.md`(包骨架与类型契约来源)
- `vite.config.ts`、`tsconfig.json`、`.prettierrc`、`eslint.config.js`(测试、路径映射与格式 / lint 配置)
- 本计划的「v2 二进制布局」「解析器设计」「帧包围盒 / 原点公式」「动画器设计」四节
</read_first>
<action>
仅在收到用户恰好回复「可以执行」之后执行。本任务不写仓库内文件,只读取并记录,供 Task 2 落码、Task 3 复核、Task 4 测试、Task 5 写 SUMMARY。
1. 读取并在执行笔记中记录以下事实:
- `AGENTS.md`:执行前须获批、命名先反馈、不得修改既有注释、最小修改也走 GSD、GSD 流程豁免范围。
- `dev.md`:CRLF、4 空格、模块无副作用、不转发导出、无类型专用导入、import 必须在首行且中间不夹注释 / 空行、命名规则、注释规范、类型规范(无必要 `any`、显式成员类型、合理 `readonly`、对象类型单独 `interface`、公开接口放 `types.ts`)。
- `types.ts` 的当前成员:`IAnimationParsedData`(`texture` / `bitmaps` / `frames` / `blend`)与 `IAnimationAnimater = ITextureAnimater<IAnimationParsedData>`;`IAnimationObject`(`index` / `x` / `y` / `scale` / `opacity` / `mirror` / `rotate`);`IAnimationFrame`(`width` / `height` / `originX` / `originY` / `objects` / `sound?`);`IAnimationBitmap`(`x` / `y` / `width` / `height`);`IAnimationSound`(`name` / `volume?` / `pitch?`)。
- `index.ts` 当前只有一行 `export * from './types';`;`package.json` 只有 `name` 与 `dependencies['@motajs/render'] = 'workspace:*'`。
- `@motajs/render` 的 `Texture` 与 `MotaOffscreenCanvas2D` 可从包根取得;`Texture` 构造器接受 `SizedCanvasImageSource`;`MotaOffscreenCanvas2D` 构造器使用 `document.createElement('canvas')` 与 `devicePixelRatio`。
- `packages/render/src/core/graphics.ts:30`、`misc.ts:21`、`utils.ts:4` 在模块加载期创建画布 / 检测 WebGL;Node 测试必须在导入前安装 fake DOM。
- 旧引擎公式逐项核对:`realWidth = image.width * ratio * zoom / 100`、`realHeight = image.height * ratio * zoom / 100`、`cx = centerX + t.x`、`cy = centerY + t.y`、`ix = cx - realWidth / 2`、`iy = cy - realHeight / 2`、`opacity = t.opacity / 255`、`angle = -t.angle * Math.PI / 180`、`mirror` 为 `ctx.scale(-1, 1)`;变换顺序为 `translate → scale → rotate → drawImage(-w/2, -h/2, w, h)`。若与本计划公式不一致,停下上报,不得自行改公式。
2. 记录**精确目标形态**:`parse.ts` 的公开导出、内部 raw 类型 / 校验函数 / 帧公式;`animater.ts` 的类、`once` / `cycled`、`composeFrame` / `sequence`、画布设置与清理;`index.ts` 三行导出。方案中不得出现「导出与命名」表之外的公开名称。
3. 采集**范围基线**:`%TEMP%` 不是文件系统路径,基线文件的实际位置由 Node 的 `process.env.TEMP` 解析;后续门禁统一用 `(process.env.TEMP||'.')`。用 `node` 把当前 `git status --porcelain -uall` 的完整输出(先统一为 LF)写入 `gsd-09-54-status.txt`(UTF-8 无 BOM),并回显绝对路径。写入后必须立刻断言基线文件内容与当前 `git status --porcelain -uall` 完全一致(见 `<verify>` 第 1 条),否则重新采集;不得用 `.trim()` 之外的方式放宽比较。
4. 采集**哈希基线**:对以下路径逐个执行 `git hash-object`,把「无空格路径 + 空格 + 40 位哈希」写入同一 `process.env.TEMP` 目录下的 `gsd-09-54-hashes.txt`(UTF-8 无 BOM):`packages/render-anim/src/types.ts`、`packages/render-anim/package.json`、`packages/render-anim/src/index.ts`、`.planning/phases/09-minimum-browser-runnable/09-52-PLAN.md`、`09-52-SUMMARY.md`、`09-53-PLAN.md`、`09-53-SUMMARY.md`、`09-54-PLAN.md`。`index.ts` 纳入基线是为了证明它只被 Task 3 按计划改写;`types.ts` / `package.json` 与既有计划 / 摘要纳入基线是为了证明未被改动。新文件 `parse.ts` / `animater.ts` / 测试文件在 Task 1 时不存在,由 Task 2 / Task 3 / Task 4 创建,Task 5 用存在性与内容门禁检查。
5. 断言当前状态:`types.ts` 含 `IAnimationParsedData` 与 `IAnimationAnimater = ITextureAnimater<IAnimationParsedData>`;`index.ts` 恰为一行 `export * from './types';`(CRLF);`package.json` 含 `@motajs/render-anim` 与 `"@motajs/render": "workspace:*"`;`parse.ts`、`animater.ts`、`src/__test__/parse.test.ts`、`src/__test__/animater.test.ts` 均不存在。任一不符,停下上报,不得继续 Task 2。
6. 确认 `packages/render-anim` 的工作树干净:`git status --porcelain -uall -- packages/render-anim` 输出为空(`package.json`、`src/index.ts`、`src/types.ts` 已在 HEAD `7bf9fe9` 中跟踪)。任一命令非 0 退出或输出非空,必须停下上报,不得继续 Task 2。
7. 采集**工具链事实**:`node --version`、`vitest.mjs` / `prettier.cjs` / `eslint.js` / `vue-tsc.js` 均存在;`vite.config.ts` 的 `@motajs/*` 别名覆盖 `packages/*/src`;`tsconfig.json` 的 `include` 覆盖 `packages/**/*.ts`。写入执行笔记供 Task 4 / Task 5 引用。
</action>
<verify>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const p=(process.env.TEMP||'.')+'/gsd-09-54-status.txt';const base=fs.readFileSync(p,'utf8').replace(/\r\n/g,'\n').trim();const now=execSync('git status --porcelain -uall',{encoding:'utf8'}).replace(/\r\n/g,'\n').trim();if(base!==now){console.error('baseline drift');process.exit(1);}console.log('OK: status baseline matches current tree');"</automated>
<fails_when>基线文件与当前 `git status --porcelain -uall` 不一致(打印 `baseline drift`,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const p=(process.env.TEMP||'.')+'/gsd-09-54-hashes.txt';const s=fs.readFileSync(p,'utf8').replace(/\r\n/g,'\n').trim().split('\n').filter(Boolean);const ok=s.length===8&&s.every(l=>{const a=l.split(' ');return a.length===2&&a[1].length===40&&!/[^0-9a-f]/.test(a[1]);});if(!ok){console.error(s.join('\n'));process.exit(1);}console.log(s.join('\n'));"</automated>
<fails_when>哈希基线不是 8 行,或任一行不是「无空格路径 + 40 位小写十六进制」,脚本打印内容并以 1 退出。</fails_when>
<automated>node -e "const fs=require('fs');const q=String.fromCharCode(39);const types=fs.readFileSync('packages/render-anim/src/types.ts','utf8');const idx=fs.readFileSync('packages/render-anim/src/index.ts','utf8').replace(/\r\n/g,'\n').trim();const pkg=fs.readFileSync('packages/render-anim/package.json','utf8');const want='export * from '+q+'./types'+q+';';const fail=[];if(types.indexOf('export interface IAnimationParsedData')===-1){fail.push('missing IAnimationParsedData');}if(types.indexOf('export type IAnimationAnimater = ITextureAnimater<IAnimationParsedData>;')===-1){fail.push('missing IAnimationAnimater alias');}if(idx!==want){fail.push('index.ts is not the single types export');}if(pkg.indexOf('@motajs/render-anim')===-1){fail.push('package name missing');}if(pkg.indexOf('@motajs/render')===-1||pkg.indexOf('workspace:*')===-1){fail.push('workspace dependency missing');}if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: current types/index/package match assumptions');"</automated>
<fails_when>`types.ts` 缺少新类型、`index.ts` 不是单行 types 导出、或 `package.json` 缺少包名 / workspace 依赖(打印缺失项,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const files=['packages/render-anim/src/parse.ts','packages/render-anim/src/animater.ts','packages/render-anim/src/__test__/parse.test.ts','packages/render-anim/src/__test__/animater.test.ts'];const exist=files.filter(f=>fs.existsSync(f));if(exist.length){console.error('unexpected existing files: '+exist.join(', '));process.exit(1);}console.log('OK: parser/animater/test files do not exist yet');"</automated>
<fails_when>Task 1 时 `parse.ts` / `animater.ts` / 测试文件已存在(打印已存在文件,退出码 1),说明范围或状态与计划不符。</fails_when>
<automated>node -e "const{execSync}=require('child_process');const out=execSync('git status --porcelain -uall -- packages/render-anim',{encoding:'utf8'}).trim();if(out){console.error(out);process.exit(1);}console.log('OK: render-anim working tree clean');"</automated>
<fails_when>`packages/render-anim` 的 `git status --porcelain -uall` 非空(打印实际状态,退出码 1),说明三个已跟踪文件存在未提交改动,与计划假设不符。</fails_when>
</verify>
<acceptance_criteria>
- 已读取并在执行笔记中记录 `read_first` 列出的全部事实(规则、当前类型、`@motajs/render` 面、旧引擎公式与变换顺序、测试 / 格式 / 类型配置)。
- 已逐项核对旧引擎公式,确认与本计划「帧包围盒 / 原点公式」一致;若不一致已停下上报。
- `process.env.TEMP` 目录下的 `gsd-09-54-status.txt`(与门禁 `(process.env.TEMP||'.')` 解析一致,不是 `%TEMP%` 字面量)已生成,且 Task 1 结束时与当前 `git status --porcelain -uall` 完全一致。
- `process.env.TEMP` 目录下的 `gsd-09-54-hashes.txt` 恰有 8 行,覆盖 `types.ts`、`package.json`、`index.ts`、09-52 / 09-53 的计划与摘要、`09-54-PLAN.md`,每行「无空格路径 + 空格 + 40 位哈希」。
- 已确认 `types.ts` 含 `IAnimationParsedData` 与 `IAnimationAnimater`;`index.ts` 仍只有 `export * from './types';`;`package.json` 依赖正确;解析器 / 动画器 / 测试文件尚不存在。
- 已确认 `packages/render-anim` 工作树干净(三个文件已在 HEAD `7bf9fe9` 中跟踪),并记录了工具链与路径映射事实。
</acceptance_criteria>
<done>已读取并记录 dev.md / AGENTS.md 的适用规则、当前 `types.ts` / `index.ts` / `package.json`、`@motajs/render` 的 `Texture` / `MotaOffscreenCanvas2D` / 动画接口、旧引擎 `_drawAnimateFrame` 与 `ui.drawImage` 的语义、h5animate 容器布局与测试 / 格式 / 类型配置;`process.env.TEMP` 下的 `gsd-09-54-status.txt` 与 `gsd-09-54-hashes.txt`(8 条,含 `09-54-PLAN.md`)已生成;已确认解析器 / 动画器 / 测试文件尚不存在,`packages/render-anim` 工作树干净(三个文件已在 HEAD `7bf9fe9` 中跟踪)。</done>
</task>
<task type="auto">
<name>Task 2: 新建 `parse.ts` —— v2 二进制解析、校验与帧包围盒 / 原点计算</name>
<files>packages/render-anim/src/parse.ts</files>
<read_first>
- `.planning/phases/09-minimum-browser-runnable/09-54-PLAN.md` 的「v2 二进制布局」「解析器设计」「帧包围盒 / 原点公式」「导出与命名」(唯一内容依据)
- `packages/render-anim/src/types.ts`(`IAnimationParsedData` / `IAnimationFrame` / `IAnimationObject` / `IAnimationBitmap` / `IAnimationSound` / `AnimationBlendMode`)
- `packages/render/src/assets/texture.ts`(`new Texture(image)` 与 `source`)
- `packages/render/src/types.ts`(`SizedCanvasImageSource`)
- `D:/github/mota-js/libs/maps.js:3068-3092`、`D:/github/mota-js/libs/ui.js:572-625`(旧中心语义与变换顺序)
- `D:/github/motajs-monorepo/packages/libs/h5animate/lib/decoder.ts`、`encoder.ts`(容器布局,仅参考)
- `dev.md`(CRLF、4 空格、首行 import、无类型专用导入 / 无必要 `any`、对象类型单独 `interface`、无副作用模块)
</read_first>
<action>
仅在 Task 1 完成且收到「可以执行」之后执行。本任务只新建 `packages/render-anim/src/parse.ts`,不得写其它任何文件。
1. 按「v2 二进制布局」实现字节读取:头部 16 字节、`spriteCount` + sprite 宽高表、单个 WebP、UTF-8 JSON;用 `DataView` 与 `Uint8Array`,不得依赖 Node 专属缓冲 / 文件系统 / 原生图像库。
2. 按「解析器设计」实现 `parseRenderAnimation(buffer: ArrayBuffer): Promise<IAnimationParsedData>`:
- 先做头部 / sprite 表 / 总长度 / 元数据 JSON 校验,再 `createImageBitmap(new Blob([webpBytes], { type: 'image/webp' }))`。
- 用解码后的 `image.width` / `image.height` 校验 bitmap 越界;失败先 `image.close()` 再抛出。
- `new Texture(image)` 后逐帧转换;`frame.objects` 的 `scale` 存 `rawScale * ratio`(有效百分数),`mirror` / `rotate` 缺省 0。
- 返回 `{ texture, bitmaps, frames, blend }`;`blend` 用 `0 → Normal`、`1 → Add`。
- `metaDataSize` / `imageDataSize` / sprite 数量 / bitmap 数量 / 帧对象索引 / ratio / blend / opacity / mirror / 音效字段全部按「解析器设计」校验;错误消息用明确中文。
- 不写 `try-catch`;`JSON.parse` 与 `createImageBitmap` 的错误自然抛出。
3. 按「帧包围盒 / 原点公式」实现 `computeFrameBox`:`eff = object.scale`(已含 ratio);`w = bitmap.width * eff / 100`、`h = bitmap.height * eff / 100`;`hx` / `hy` 使用 `Math.abs`、`Math.cos`、`Math.sin`;并集后 `width = Math.max(1, Math.ceil(maxX - minX))`、`height = Math.max(1, Math.ceil(maxY - minY))`、`originX = -minX`、`originY = -minY`;无对象时 1x1、原点 0,0;mirror 不进入公式。
4. 文件结构按 dev.md:首行是普通 `import`,所有 import 连续且中间不夹注释 / 空行;不写类型专用导入;不使用 `any`;对象类型单独声明 `interface`;raw 元组用内部类型别名;模块只包含函数 / 接口 / 常量声明,不写顶层执行代码或导出变量;长文件用 `//#region` 按「常量 / 内部类型 / 校验 / 帧数学 / 导出解析器」分区。内部命名严格使用「导出与命名」表;任何新增 / 改动命名先停下上报。`parseRenderAnimation` 必须有中文 jsDoc,说明入参 `ArrayBuffer`、返回 `Promise<IAnimationParsedData>`、失败时抛出错误;内部接口 / 函数按 dev.md 在源头写注释,不得复述代码。
5. 不写 `index.ts`、`animater.ts`、测试或 SUMMARY;不运行 `prettier --write` 以外的格式化命令;不得改 `types.ts` / `package.json`。
</action>
<verify>
<automated>node -e "const fs=require('fs');if(!fs.existsSync('packages/render-anim/src/parse.ts')){console.error('missing parse.ts');process.exit(1);}console.log('OK: parse.ts exists');"</automated>
<fails_when>`packages/render-anim/src/parse.ts` 不存在(退出码 1)。</fails_when>
<automated>node node_modules/prettier/bin/prettier.cjs --check packages/render-anim/src/parse.ts</automated>
<fails_when>输出不是 `All matched files use Prettier code style!`,或退出码非 0(prettier 列出待格式化文件)。</fails_when>
<automated>node node_modules/eslint/bin/eslint.js packages/render-anim/src/parse.ts</automated>
<fails_when>eslint 打印任一 error / warning,或退出码非 0。</fails_when>
<automated>node -e "const fs=require('fs');const b=fs.readFileSync('packages/render-anim/src/parse.ts');const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;const ok=lf===crlf&&tabs===0&&!bom;console.log((ok?'OK':'FAIL')+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);process.exit(ok?0:1);"</automated>
<fails_when>出现非 CRLF 换行、制表符或 BOM(打印 `FAIL`,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const need=['export async function parseRenderAnimation','new DataView','createImageBitmap','new Blob','TextDecoder','new Texture','Math.ceil','Math.abs','Math.cos','Math.sin','ANIMATION_SIGNATURE','ANIMATION_VERSION','ANIMATION_HEADER_SIZE'];const miss=need.filter(n=>t.indexOf(n)===-1);if(miss.length){console.error('missing: '+miss.join(', '));process.exit(1);}console.log('OK: parser key tokens present');"</automated>
<fails_when>解析器缺少公开入口、浏览器 API、帧数学函数或常量之一(打印缺失列表,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const i=t.indexOf('export async function parseRenderAnimation');const pre=i>=0?t.slice(Math.max(0,i-1500),i):'';const ok=i>=0&&/\/\*\*[\s\S]*?\*\//.test(pre);if(!ok){console.error('missing jsDoc for parseRenderAnimation');process.exit(1);}console.log('OK: parseRenderAnimation has jsDoc');"</automated>
<fails_when>`parseRenderAnimation` 不存在,或其正上方没有 `/** ... */` jsDoc 注释(退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8').replace(/\r\n/g,'\n');const hits=[];if(/\bBuffer\b/.test(t))hits.push('Buffer');if(/\bsharp\b/.test(t))hits.push('sharp');if(/require\s*\(/.test(t))hits.push('require(');if(/node:/.test(t))hits.push('node:');if(/^\s*import\s+type\b/m.test(t))hits.push('import type');if(/export default/.test(t))hits.push('export default');if(/:\s*any\b|<any>/.test(t))hits.push('any');const topLevel=t.split('\n').filter(l=>/^(let|var)\s/.test(l)||/^export\s+(const|let|var)\s/.test(l));const firstLine=t.split('\n')[0]||'';const fail=[];if(hits.length){fail.push('forbidden: '+hits.join(', '));}if(topLevel.length){fail.push('top-level mutable/exported variable: '+topLevel.join(' | '));}if(!/^import\b/.test(firstLine)){fail.push('first line is not an import');}console.log(fail.length?'FAIL\n'+fail.join('\n'):'OK: parser is browser-only and side-effect free');process.exit(fail.length?1:0);"</automated>
<fails_when>解析器出现 Node / 原生依赖、类型专用导入、`any`、`export default`、顶层 `let` / `var` 或导出的变量声明,或首行不是普通 `import`(打印 `FAIL`,退出码 1)。非导出的顶层 `const` 常量声明是允许的。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8').replace(/\r\n/g,'\n');const ex=t.split('\n').filter(l=>/^export\s/.test(l));const ok=ex.length===1&&ex[0].indexOf('export async function parseRenderAnimation')===0;console.log(ex.join('\n'));if(!ok){console.error('unexpected export set');process.exit(1);}console.log('OK: parse.ts exports only parseRenderAnimation');"</automated>
<fails_when>`parse.ts` 的 `export` 行不是恰好一条 `export async function parseRenderAnimation...`(打印实际 export 行与 `unexpected export set`,退出码 1);内部接口 / 函数 / 常量不得导出。</fails_when>
</verify>
<acceptance_criteria>
- `parse.ts` 已按 v2 布局读取头部 / sprite 表 / WebP / UTF-8 JSON,公开入口为 `parseRenderAnimation(buffer: ArrayBuffer): Promise<IAnimationParsedData>`。
- 解析顺序为先字节 / JSON 校验、再解码、再越界校验、最后构造 `Texture` 与帧;失败路径会 `image.close()` 避免泄漏。
- raw 元数据与帧对象校验覆盖签名、版本、总长度、sprite 数量 / 尺寸、bitmap 数量 / 越界、对象索引、ratio、blend、opacity、mirror、音效字段。
- 帧公式严格按「帧包围盒 / 原点公式」:`eff = rawScale * ratio`、`w/h` 按 `/100`、`hx/hy` 使用绝对值三角函数、`ceil` 尺寸、`origin = -min`;空帧 1x1、原点 0,0;mirror 不改变包围盒。
- 生产代码无 Node 专属依赖、原生图像库、类型专用导入、`any`、`export default`、顶层副作用;命名严格使用「导出与命名」表;`parseRenderAnimation` 带中文 jsDoc(入参 / 返回值 / 失败抛出)。
- prettier `--check`、eslint、CRLF / BOM / 制表符与内容 / 禁止项门禁通过。
</acceptance_criteria>
<done>`parse.ts` 已实现 `parseRenderAnimation`:读取 v2 头部 / sprite 表 / 单 WebP / UTF-8 JSON,执行完整校验,按旧引擎中心语义计算每帧 `width/height/originX/originY`,把 `ratio` 折入 `object.scale`,返回 `{ texture, bitmaps, frames, blend }`;无 Node / 原生依赖、无类型专用导入 / `any` / 顶层副作用;`parseRenderAnimation` 带中文 jsDoc;prettier、eslint、CRLF / BOM 与内容门禁通过。</done>
</task>
<task type="auto">
<name>Task 3: 新建 `animater.ts` 与改写 `index.ts` —— 惰性帧合成、清理与包根导出</name>
<files>packages/render-anim/src/animater.ts, packages/render-anim/src/index.ts</files>
<read_first>
- `.planning/phases/09-minimum-browser-runnable/09-54-PLAN.md` 的「帧包围盒 / 原点公式」「动画器设计」「导出与命名」(唯一内容依据)
- `packages/render-anim/src/types.ts`(`IAnimationParsedData` / `IAnimationFrame` / `IAnimationObject` / `IAnimationBitmap`)
- `packages/render/src/assets/types.ts`(`ITextureAnimater<T>` / `ITextureRenderable` / `ITexture`)
- `packages/render/src/core/canvas2d.ts`(`MotaOffscreenCanvas2D` 构造、`setHD`、`setAntiAliasing`、`size`、`clear`、`canvas` / `ctx`)
- `packages/render/src/types.ts`(`SizedCanvasImageSource`)
- `D:/github/mota-js/libs/maps.js:3068-3092`、`D:/github/mota-js/libs/ui.js:572-625`(旧绘制语义)
- `dev.md`(CRLF、4 空格、首行 import、无类型专用导入 / 无必要 `any`、类必须 `implements`、私有方法放在调用者之前且处于合理分区、无副作用模块)
</read_first>
<action>
仅在 Task 1 / Task 2 完成且收到「可以执行」之后执行。本任务只新建 `packages/render-anim/src/animater.ts` 并改写 `packages/render-anim/src/index.ts`,不得写其它任何文件。
1. 新建 `animater.ts`,按「动画器设计」实现:
- `export class RenderAnimater implements ITextureAnimater<IAnimationParsedData>`。
- `*once(texture, data)` / `*cycled(texture, data)` 返回 `Generator<ITextureRenderable, void>`,二者用 `yield*` 委托私有 `sequence(texture, data, cycled)`。
- `sequence`:`data.frames.length === 0` 时直接 `return`;用局部变量保存上一帧画布;每次循环从 yield 恢复后、合成新帧前,先对上一帧执行 `canvas.clear()` 并把 `canvas.canvas.width` / `canvas.canvas.height` 设为 `0`;然后 `composeFrame` 并保存为当前帧;yield `{ source: canvas.canvas, rect: { x: 0, y: 0, w: frame.width, h: frame.height } }`;`once` 走完最后一帧后清理最后一帧并结束,`cycled` 回到第 0 帧;**不使用 `try/finally`**(用户决定 1B),提前 `.return()` 不清理最后一帧、交给 GC,不得承诺 `.return()` 清理。
- `composeFrame`:`new MotaOffscreenCanvas2D()`;`setHD(false)`;`setAntiAliasing(false)`;`size(frame.width, frame.height)`;遍历 `frame.objects`,`bitmap = data.bitmaps[object.index]`,`realWidth = bitmap.width * object.scale / 100`、`realHeight = bitmap.height * object.scale / 100`,`cx = frame.originX + object.x`、`cy = frame.originY + object.y`;`ctx.save()` → `translate(cx, cy)` → `if (object.mirror) ctx.scale(-1, 1)` → `if (object.rotate) ctx.rotate(-object.rotate * Math.PI / 180)` → `ctx.globalAlpha = object.opacity / 255` → `ctx.drawImage(texture.source, bitmap.x, bitmap.y, bitmap.width, bitmap.height, -realWidth / 2, -realHeight / 2, realWidth, realHeight)` → `ctx.restore()`。
- 空帧仍创建 1x1 画布、不调用 `drawImage`,yield 透明 1x1。
- 不实现帧计时 / 定时器 / 请求动画帧;不调用 `texture.dispose()` / `data.texture.dispose()`;不把 `MotaOffscreenCanvas2D` 本身作为 `source`。
2. 改写 `index.ts` 为恰好三行(顺序固定):
- `export * from './types';`
- `export * from './parse';`
- `export * from './animater';`
不写默认导出、不转发其它包内容、不夹注释与空行。
3. 文件结构按 dev.md:首行普通 `import`,import 连续且不夹注释 / 空行;无类型专用导入;无 `any`;类有接口并用 `implements`;私有方法 `composeFrame` / `sequence` 放在 `once` / `cycled` 之前并处于「合成」/「序列」分区;长文件用 `//#region`。不得使用「导出与命名」表之外的名称。`RenderAnimater` 类与公开方法 `once` / `cycled` 必须有中文 jsDoc,说明惰性逐帧合成、yield 的 `source` / `rect` 与清理语义(下次 `.next()` 清理上一帧、正常完成释放最后一帧、提前 `.return()` 交给 GC)。
4. 不写测试或 SUMMARY;不运行 `prettier --write` 以外的格式化命令;不得改 `types.ts` / `package.json` / `parse.ts`。
</action>
<verify>
<automated>node -e "const fs=require('fs');for(const f of ['packages/render-anim/src/animater.ts','packages/render-anim/src/index.ts']){if(!fs.existsSync(f)){console.error('missing '+f);process.exit(1);}}console.log('OK: animater.ts and index.ts exist');"</automated>
<fails_when>`animater.ts` 或 `index.ts` 不存在(退出码 1)。</fails_when>
<automated>node node_modules/prettier/bin/prettier.cjs --check packages/render-anim/src/animater.ts packages/render-anim/src/index.ts</automated>
<fails_when>输出不是 `All matched files use Prettier code style!`,或退出码非 0。</fails_when>
<automated>node node_modules/eslint/bin/eslint.js packages/render-anim/src/animater.ts packages/render-anim/src/index.ts</automated>
<fails_when>eslint 打印任一 error / warning,或退出码非 0。</fails_when>
<automated>node -e "const fs=require('fs');for(const f of ['packages/render-anim/src/animater.ts','packages/render-anim/src/index.ts']){const b=fs.readFileSync(f);const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF;if(lf!==crlf||tabs!==0||bom){console.error('FAIL '+f+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);process.exit(1);}}console.log('OK: both files are CRLF, no tabs, no BOM');"</automated>
<fails_when>任一文件出现非 CRLF 换行、制表符或 BOM(打印 `FAIL` 与文件,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const q=String.fromCharCode(39);const t=fs.readFileSync('packages/render-anim/src/index.ts','utf8').replace(/\r\n/g,'\n').trim();const want=['export * from '+q+'./types'+q+';','export * from '+q+'./parse'+q+';','export * from '+q+'./animater'+q+';'].join('\n');if(t!==want){console.error('index.ts mismatch:'+String.fromCharCode(10)+t);process.exit(1);}console.log('OK: index.ts has exactly the 3 exports in order');"</automated>
<fails_when>`index.ts` 不是恰好三行星号导出且顺序为 types / parse / animater(打印实际内容,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/animater.ts','utf8');const need=['export class RenderAnimater implements ITextureAnimater<IAnimationParsedData>','*once(','*cycled(','new MotaOffscreenCanvas2D()','setHD(false)','setAntiAliasing(false)','canvas.canvas','source: canvas.canvas','originX + object.x','originY + object.y','scale(-1, 1)','-object.rotate * Math.PI / 180','object.opacity / 255','canvas.clear()'];const miss=need.filter(n=>t.indexOf(n)===-1);const bad=['texture.dispose','data.texture.dispose','setTimeout','requestAnimationFrame','setInterval','finally {','try {'];const hits=bad.filter(n=>t.indexOf(n)!==-1);const fail=[];if(miss.length){fail.push('missing: '+miss.join(', '));}if(hits.length){fail.push('forbidden: '+hits.join(', '));}console.log(fail.length?'FAIL\n'+fail.join('\n'):'OK: animater matches required shape');process.exit(fail.length?1:0);"</automated>
<fails_when>动画器缺少类 / 方法 / 画布设置 / 清理 / 绘制顺序 / `canvas.canvas` 之一,或出现纹理 dispose / 计时 API / `try {` / `finally {` 代码块(打印 `FAIL` 与差异,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/animater.ts','utf8');const targets=['export class RenderAnimater','*once(','*cycled('];const miss=targets.filter(n=>{const i=t.indexOf(n);if(i<0){return true;}return !/\/\*\*[\s\S]*?\*\//.test(t.slice(Math.max(0,i-1500),i));});if(miss.length){console.error('missing jsDoc: '+miss.join(', '));process.exit(1);}console.log('OK: RenderAnimater and once/cycled have jsDoc');"</automated>
<fails_when>`RenderAnimater` 类或公开方法 `once` / `cycled` 缺失,或正上方没有 `/** ... */` jsDoc 注释(退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/animater.ts','utf8').replace(/\r\n/g,'\n');const ex=t.split('\n').filter(l=>/^export\s/.test(l));const ok=ex.length===1&&ex[0].indexOf('export class RenderAnimater')===0;console.log(ex.join('\n'));if(!ok){console.error('unexpected export set');process.exit(1);}console.log('OK: animater.ts exports only RenderAnimater');"</automated>
<fails_when>`animater.ts` 的 `export` 行不是恰好一条 `export class RenderAnimater...`(打印实际 export 行与 `unexpected export set`,退出码 1);内部辅助方法不得导出。</fails_when>
</verify>
<acceptance_criteria>
- `RenderAnimater` 实现 `ITextureAnimater<IAnimationParsedData>`,`once` / `cycled` 返回 `Generator<ITextureRenderable, void>` 并委托 `sequence`。
- 每帧创建 `MotaOffscreenCanvas2D`,`setHD(false)`、`setAntiAliasing(false)`、`size(frame.width, frame.height)`;按 `translate → mirror → rotate → globalAlpha → drawImage` 绘制。
- yield 的 `source` 是 `canvas.canvas`(HTMLCanvasElement),`rect` 为 `{ x: 0, y: 0, w: frame.width, h: frame.height }`。
- 下次 `.next()` 恢复后清理并释放上一帧画布;`once` 正常完成时释放最后一帧;提前 `.return()` 不清理、交给 GC(不使用 `try/finally`,不承诺 `.return()` 清理);空帧为透明 1x1;`frames` 为空时不 yield;不 dispose 源纹理;无帧计时。
- `RenderAnimater` 类与公开方法 `once` / `cycled` 带中文 jsDoc。
- `index.ts` 恰有三行星号导出且顺序为 `./types`、`./parse`、`./animater`。
- prettier、eslint、CRLF / BOM / 制表符、导出 / jsDoc 与动画器内容门禁通过。
</acceptance_criteria>
<done>`animater.ts` 已实现 `RenderAnimater` 的惰性逐帧合成:HD/AA 关闭、按旧中心语义绘制、yield `canvas.canvas` + 帧矩形、下次 `.next()` 恢复后清理上一帧并在正常完成时释放最后一帧(提前 `.return()` 交给 GC,不使用 `try/finally`)、空帧透明 1x1、不 dispose 源纹理、无帧计时;`RenderAnimater` 与 `once` / `cycled` 带中文 jsDoc;`index.ts` 已改为三行星号导出;prettier、eslint、CRLF / BOM 与内容门禁通过。</done>
</task>
<task type="auto">
<name>Task 4: 新建 Node 安全测试并运行 targeted vitest / prettier / eslint / 过滤类型门禁</name>
<files>packages/render-anim/src/__test__/parse.test.ts, packages/render-anim/src/__test__/animater.test.ts</files>
<read_first>
- `.planning/phases/09-minimum-browser-runnable/09-54-PLAN.md` 的「v2 二进制布局」「解析器设计」「帧包围盒 / 原点公式」「动画器设计」(测试断言的唯一依据)
- `packages/render-anim/src/parse.ts`、`packages/render-anim/src/animater.ts`、`packages/render-anim/src/index.ts`(被测对象)
- `packages/render-anim/src/types.ts`(类型与 `AnimationBlendMode`)
- `packages/render/src/assets/types.ts`、`packages/render/src/core/canvas2d.ts`(fake 对象需要满足的最小面)
- 既有测试风格:`packages/system/src/hotkey/__test__/system.test.ts`(`vi.hoisted` 先于 import、`vi.stubGlobal`、每个 `it` 前一行注释)
- `vite.config.ts`、`tsconfig.json`、`eslint.config.js`(测试路径 / 别名 / lint)
- `dev.md`(测试文件只强制「每个 `it` 前一行说明注释」)
</read_first>
<action>
仅在 Task 1–3 完成且收到「可以执行」之后执行。本任务只新建两个测试文件,不得写其它任何文件。
1. **fake DOM / fake canvas 准备(每个测试文件各自 `vi.hoisted` 安装,因 `vi.hoisted` 不能引用导入的辅助函数):**
- `vi.stubGlobal('document', { createElement: () => fakeCanvas() })`;`vi.stubGlobal('devicePixelRatio', 1)`。
- fake canvas 至少提供 `width`、`height`、`getContext(type)`;`type` 为 `webgl` / `webgl2` 时返回 `null`,否则返回 fake 2D context。
- fake 2D context 提供 `save` / `restore` / `setTransform` / `scale` / `rotate` / `translate` / `clearRect` / `drawImage` / `setLineDash` / `transform` 等为 `vi.fn()`,并有 `imageSmoothingEnabled` / `globalAlpha` 可写属性。
- 这是为了在导入 `@motajs/render` 根桶前满足 `graphics.ts:30`、`misc.ts:21`、`utils.ts:4` 的模块加载期画布创建;不得修改 `packages/render`。
2. **`parse.test.ts` 覆盖(每个 `it` 前一行中文注释说明测试内容):**
- 自建 v2 二进制构造器:写入 `ANIM`、version 2、`imageDataSize`、`metaDataSize`、spriteCount、sprite 宽高、任意 WebP 字节、UTF-8 JSON;`vi.stubGlobal('createImageBitmap', vi.fn(async () => fakeBitmap))`。
- 正常解析:返回 `texture.source` 为 fake bitmap、`bitmaps` 与 raw 一致、`frames` 数量正确、`blend` 映射正确。
- blend:`0 → AnimationBlendMode.Normal`、`1 → AnimationBlendMode.Add`。
- ratio 折入 scale:raw `scale = 50`、`ratio = 2` → `object.scale === 100`。
- 帧数学:单对象 32×32、无旋转 → `width/height = 32`、`originX/originY = 16`;45° 旋转 → `width/height = 46`、`originX/originY ≈ 22.627`;多对象并集;空帧 → 1×1、原点 0,0;mirror 不改变包围盒。
- 音效:`name` / `volume` / `pitch` 保留(含中文名,验证 UTF-8 解码)。
- 5 元素元组成功路径:`frame.objects` 元组只写前 5 个元素时成功解析,`mirror` / `rotate` 缺省为 0,帧数学按 `rotate = 0` 计算(`hx = w/2`、`hy = h/2`,不出现 `Math.cos` / `Math.sin` 影响)。
- 失败路径(逐项覆盖解析器所有已声明校验):签名错误、版本非 2、总长度不符、`imageDataSize` / `metaDataSize` 与总长度不一致、`spriteCount` 为 0、sprite 宽或高为 0、`bitmaps` 不是数组、`frame` 不是数组、`bitmap` 数量与 sprite 数不一致、bitmap `x` / `y` 为负或 `width` / `height` 小于 1、解码后 bitmap 越界、`objects` 不是数组、`sound` 不是数组、对象元组长度小于 5 或大于 7、对象索引越界或非整数、`x` / `y` / `rotate` 非有限数字、`scale` 非有限或 `<= 0`、`ratio` 非有限或 `<= 0`、`blend` 非 0/1、`opacity` 非有限或超出 `[0, 255]`、`mirror` 非有限数字、音效 `name` 非非空字符串或 `volume` / `pitch` 非有限;每项断言抛出明确错误。
- 不自动 dispose:fake bitmap 的 `close` 未被调用(成功解析路径)。
3. **`animater.test.ts` 覆盖(每个 `it` 前一行中文注释说明测试内容):**
- 用 fake `ITexture`(只提供 `source` 等最小面)与 `IAnimationParsedData`。
- `once` 两帧:依次 yield 两个 `ITextureRenderable`,`rect` 与帧尺寸一致,`source` 为 fake canvas 元素。
- 恢复时清理:第一次 `next()` 后记录 canvas0;第二次 `next()` 后 canvas0 的物理宽高为 0 且 `clearRect` 被调用。
- 正常完成释放最后一帧:`once` 走完最后一帧后再次调用 `next()` 返回 `done`,断言最后一帧画布已被 `clear` 且物理宽高为 0(不是交给 GC)。
- 提前 `.return()`:`next()` 后 `return()`,断言最后一帧画布未被清理(`clear` 未被再次调用),验证计划声明的「交给 GC、不承诺清理」行为,不主张 `.return()` 清理。
- `cycled`:帧数 N,连续 `next()` N+1 次后帧序回到第 0 帧。
- 空帧:yield 1×1,`drawImage` 未被调用。
- 绘制参数:`translate(frame.originX + x, frame.originY + y)`、mirror 时 `scale(-1, 1)`、`rotate(-rotate * Math.PI / 180)`、`globalAlpha = opacity / 255`、`drawImage` 的源矩形与目标矩形符合公式。
- `frames` 为空:`once` / `cycled` 首次 `next()` 即 `done`。
- 不 dispose 源纹理:fake texture 的 `dispose` 未被调用。
4. **运行与修复:** 先运行 `node node_modules/vitest/vitest.mjs run packages/render-anim`;失败时只修改测试或回到 Task 2 / Task 3 修正源码(不得放宽断言、不得跳过测试、不得改 `packages/render`)。随后运行 prettier / eslint / CRLF 门禁与过滤类型门禁;测试类型错误必须修复,不得用 `// @ts-ignore` 掩盖(确需 `// @ts-expect-error` 时按 dev.md 说明原因,且测试文件可豁免 dev.md 其它规则)。
5. 不写 SUMMARY;不运行游戏 / 浏览器 / dev server;不运行 `pnpm install`;不执行 git 写命令。
</action>
<verify>
<automated>node -e "const fs=require('fs');for(const f of ['packages/render-anim/src/__test__/parse.test.ts','packages/render-anim/src/__test__/animater.test.ts']){if(!fs.existsSync(f)){console.error('missing '+f);process.exit(1);}}console.log('OK: both test files exist');"</automated>
<fails_when>任一测试文件不存在(退出码 1)。</fails_when>
<automated>node node_modules/vitest/vitest.mjs run packages/render-anim</automated>
<fails_when>vitest 任一测试失败、抛出未捕获错误、或退出码非 0。</fails_when>
<automated>node node_modules/prettier/bin/prettier.cjs --check packages/render-anim/src/parse.ts packages/render-anim/src/animater.ts packages/render-anim/src/index.ts packages/render-anim/src/__test__/parse.test.ts packages/render-anim/src/__test__/animater.test.ts</automated>
<fails_when>输出不是 `All matched files use Prettier code style!`,或退出码非 0。</fails_when>
<automated>node node_modules/eslint/bin/eslint.js packages/render-anim/src/parse.ts packages/render-anim/src/animater.ts packages/render-anim/src/index.ts packages/render-anim/src/__test__/parse.test.ts packages/render-anim/src/__test__/animater.test.ts</automated>
<fails_when>eslint 打印任一 error / warning,或退出码非 0。</fails_when>
<automated>node -e "const fs=require('fs');const files=['packages/render-anim/src/parse.ts','packages/render-anim/src/animater.ts','packages/render-anim/src/index.ts','packages/render-anim/src/__test__/parse.test.ts','packages/render-anim/src/__test__/animater.test.ts'];for(const f of files){const b=fs.readFileSync(f);const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF;if(lf!==crlf||tabs!==0||bom){console.error('FAIL '+f+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);process.exit(1);}}console.log('OK: all 5 files are CRLF, no tabs, no BOM');"</automated>
<fails_when>任一文件出现非 CRLF 换行、制表符或 BOM(打印 `FAIL` 与文件,退出码 1)。</fails_when>
<automated>node -e "const{execSync}=require('child_process');const run=cmd=>{try{return{out:execSync(cmd,{encoding:'utf8',maxBuffer:67108864,stdio:['ignore','pipe','pipe']}),status:0};}catch(e){return{out:String(e.stdout||'')+String(e.stderr||''),status:typeof e.status==='number'?e.status:null,code:e.code||null};}};const v=run('node node_modules/vue-tsc/bin/vue-tsc.js --version');if(v.status!==0){console.error('SENTINEL FAIL: vue-tsc could not start: '+v.out+(v.code?' code='+v.code:''));process.exit(2);}const r=run('node node_modules/vue-tsc/bin/vue-tsc.js --noEmit');if(r.status===null){console.error('SENTINEL FAIL: type check did not complete: '+r.out+(r.code?' code='+r.code:''));process.exit(2);}const hits=r.out.split(/\r?\n/).filter(l=>/packages[\\\/]render-anim[\\\/]/.test(l));console.log('sentinel: vue-tsc '+v.out.trim()+' | type check exit '+r.status);console.log(hits.length?hits.join('\n'):'OK: no render-anim diagnostics');process.exit(hits.length?1:0);"</automated>
<fails_when>`vue-tsc --version` 哨兵无法启动(退出码 2),或 `--noEmit` 进程未正常结束、`status` 为 `null`(退出码 2);或过滤后仍出现任一 `packages/render-anim` 诊断(打印诊断并以 1 退出)。其它文件的诊断与 `vue-tsc` 非 0 退出码不参与判定。</fails_when>
</verify>
<acceptance_criteria>
- `parse.test.ts` 与 `animater.test.ts` 均存在,且在 Node 环境运行;所有 `it` 前有一行中文说明注释。
- 解析测试覆盖正常解析、blend、ratio 折入 scale、帧数学(无旋转 / 45° / 多对象 / 空帧 / mirror)、5 元素元组默认 `mirror` / `rotate = 0`、音效 UTF-8,以及逐项列出的全部失败路径(长度 / sprite / 非数组 `bitmaps` / `frame` / `objects` / `sound` / 元组长度 5–7 / bitmap / 索引 / `x` / `y` / `rotate` / `scale` / ratio / blend / opacity / mirror / 音效)与成功路径不自动 close。
- 动画器测试覆盖 `once` / `cycled` 序列、下次 `.next()` 清理上一帧、正常完成释放最后一帧、提前 `.return()` 不清理(交给 GC)、空帧 1×1、绘制参数、`frames` 为空与不 dispose 源纹理。
- `node node_modules/vitest/vitest.mjs run packages/render-anim` 全部通过;prettier、eslint、CRLF / BOM / 制表符门禁通过。
- 过滤类型门禁先通过 `vue-tsc --version` 哨兵、确认 `--noEmit` 进程正常结束,再对 `packages/render-anim` 诊断为 0 行(或 SUMMARY 明确写「类型检查未运行」)。
- 未修改 `/packages/render`、`types.ts`、`package.json`,未运行游戏 / 浏览器 / dev server,未执行 git 写命令。
</acceptance_criteria>
<done>两个测试文件已创建并通过 targeted vitest;解析、校验、帧数学、生成器序列、下次 `.next()` 清理与正常完成释放、提前 `.return()` 交给 GC、不 dispose 纹理均有覆盖;prettier / eslint / CRLF / BOM / 制表符与过滤类型门禁通过(哨兵确认 `vue-tsc` 可启动且 `--noEmit` 正常结束,`packages/render-anim` 诊断 0 行);未改其它包 / 配置,未提交。</done>
</task>
<task type="auto">
<name>Task 5: 范围 / 哈希闸门自检并写 `09-54-SUMMARY.md`</name>
<files>.planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md</files>
<read_first>
- `.planning/phases/09-minimum-browser-runnable/09-54-PLAN.md` 的 `<success_criteria>` 与「覆盖审计」(SUMMARY 必须覆盖的条目)
- `process.env.TEMP` 目录下的 `gsd-09-54-status.txt` 与 `gsd-09-54-hashes.txt`(Task 1 采集的范围 / 哈希基线;与门禁 `(process.env.TEMP||'.')` 解析一致)
- Task 1–4 的执行笔记与各门禁真实输出
- `packages/render-anim/src/parse.ts`、`animater.ts`、`index.ts`、`__test__/parse.test.ts`、`animater.test.ts`(最终形态)
- `09-52-SUMMARY.md`、`09-53-SUMMARY.md`(SUMMARY 的 frontmatter 与内容风格)
</read_first>
<action>
只写 `09-54-SUMMARY.md`,不修改任何代码文件。
1. **写 SUMMARY 前的范围闸门(SUMMARY 允许尚不存在)**:用下面命令只在相关根目录(`packages/render-anim/` 与 `.planning/phases/09-minimum-browser-runnable/`)内比对 Task 1 基线,同时要求相关根之外没有任何新增 / 删除条目:`node -e "const{execSync}=require('child_process'),fs=require('fs');const base=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-54-status.txt','utf8').split(/\r?\n/).filter(l=>l.length>0);const cur=execSync('git status --porcelain -uall',{encoding:'utf8'}).split(/\r?\n/).filter(l=>l.length>0);const added=cur.filter(l=>base.indexOf(l)===-1);const removed=base.filter(l=>cur.indexOf(l)===-1);const inScope=l=>{const p=l.slice(3);return p.indexOf('packages/render-anim/')===0||p.indexOf('.planning/phases/09-minimum-browser-runnable/')===0;};const addedIn=added.filter(inScope);const addedOut=added.filter(l=>!inScope(l));const removedIn=removed.filter(inScope);const removedOut=removed.filter(l=>!inScope(l));const allow=['?? packages/render-anim/src/parse.ts','?? packages/render-anim/src/animater.ts','?? packages/render-anim/src/__test__/parse.test.ts','?? packages/render-anim/src/__test__/animater.test.ts',' M packages/render-anim/src/index.ts'];const extra=addedIn.filter(l=>allow.indexOf(l)===-1);const missing=allow.filter(l=>addedIn.indexOf(l)===-1);console.log('addedIn:\n'+addedIn.join('\n'));console.log('addedOut:\n'+addedOut.join('\n'));console.log('removedIn:\n'+removedIn.join('\n'));console.log('removedOut:\n'+removedOut.join('\n'));console.log('extra:\n'+extra.join('\n'));console.log('missing:\n'+missing.join('\n'));if(extra.length||missing.length||removedIn.length||addedOut.length||removedOut.length){console.error('pre-write range drift');process.exit(1);}console.log('OK: pre-write range matches the 5 expected entries');"`。要求 `addedIn` 恰为 Task 2–4 创建的 4 个新文件(`parse.ts`、`animater.ts`、两个测试文件)加 ` M packages/render-anim/src/index.ts`(共 5 项),`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 均为空;`index.ts` 是已跟踪文件,Task 3 修改后会出现 ` M` 行;`types.ts` / `package.json` 保持干净。`addedOut` / `removedOut` 为空保留「不越界写包外文件」的保证;基线中已存在的包外脏条目若被外部改动,其内容漂移在 porcelain 路径集合中不可见,该限制见 OI-10。任何额外的相关条目都必须停下上报,不得用子串匹配放宽。这条命令必须在写入 SUMMARY 之前成功执行。
2. **哈希闸门**:运行 `<verify>` 第 2 条命令。要求 8 条基线中只有 `packages/render-anim/src/index.ts` 的哈希变化;`types.ts`、`package.json`、09-52 / 09-53 的计划与摘要、`09-54-PLAN.md` 逐字不变。若 `index.ts` 未变化或出现第二处变化,停下上报。
3. **写 `09-54-SUMMARY.md`**(UTF-8 无 BOM、CRLF、4 空格缩进、Markdown 文件名连字符命名),frontmatter 至少包含 `phase: 09-minimum-browser-runnable`、`plan: 54`、`subsystem: render-anim`、`tags`、`requires`、`provides`、`affects`、`actuals`(tokens / tasks / commits: 0)、`tech-stack`、`key-files`(created / modified)、`key-decisions`、`patterns-established`、`duration`、`completed`、`status: complete`。正文至少包含:
- **本计划范围**:逐字写出 `files_modified` 及其 6 个路径;只实现 v2 解析器、`RenderAnimater`、包根导出与测试;不改 `types.ts` / `package.json` / 其它包;不新增依赖;不跑游戏 / 浏览器 / dev server;0 次提交;09-54 / 波次 3 / `depends_on: 09-52, 09-53` 的编号说明。
- **v2 布局与解析结果**:头部 / sprite 表 / 单 WebP / UTF-8 JSON;`parseRenderAnimation` 的返回形态;校验清单与错误策略;`ratio` 折入 `object.scale` 的说明。
- **帧公式**:逐字写出 `eff` / `w` / `h` / `hx` / `hy` / `minX` / `maxX` / `minY` / `maxY` / `width` / `height` / `originX` / `originY` 公式与三个算例(无旋转、45°、空帧)。
- **动画器行为**:`MotaOffscreenCanvas2D`、`setHD(false)`、`setAntiAliasing(false)`、`size`、`translate → mirror → rotate → globalAlpha → drawImage`、`canvas.canvas` + 帧矩形、下次 `.next()` 清理上一帧、正常完成释放最后一帧、提前 `.return()` 交给 GC(不使用 `try/finally`,不承诺 `.return()` 清理)、空帧 1×1、不 dispose 源纹理、无帧计时。
- **Task 1 基线**:8 条哈希、`packages/render-anim` 工作树干净(三个文件已跟踪)、工具链与路径映射事实。
- **门禁真实结果**:targeted vitest、prettier、eslint、CRLF / BOM / 制表符、内容 / 禁止项门禁的实际输出(逐字粘贴关键行);类型门禁「已运行(0 行 render-anim 诊断)」或「未运行」二选一,不得含糊;范围闸门与哈希闸门的实际输出。
- **未做 / 跳过项与已知限制**:不做浏览器 E2E、不跑游戏 / dev server、不使用真实 WebP 素材、不运行 `pnpm install`、不执行 git 写命令;sprite 尺寸表不与元数据 `bitmaps` 或解码图尺寸交叉比对(OI-9);范围闸门对 Task 1 基线中已存在的包外脏条目只能校验路径集合、无法发现其内容漂移(OI-10)。
- **待确认项 / 已定项**:OI-1 命名、OI-2 ratio 折入 scale、OI-3 已由用户决定为 1B(不使用 `try/finally`)、OI-4 元组长度、OI-5 `Texture.isBitmap`、OI-6 无浏览器 E2E、OI-7 未校准估算(180k,用户已接受不拆分、不声称符合智能区间预算)、OI-8 已提交基线(HEAD `7bf9fe9`)与本计划 0 次提交。
- **估算**:`confidence: low`,未校准,`tokens: 180000` 超出 100k 智能区间预算;用户已明确接受保持单个组合计划、不拆分为 09-54 / 09-55;实际字节 / 行数与测试数量按最终文件测量。
4. **写 SUMMARY 后的范围闸门**:运行 `<verify>` 第 3 条命令,要求 `addedIn` 恰为 Task 2–4 的 4 个新文件、` M packages/render-anim/src/index.ts` 与 `?? .planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md`(共 6 项),`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 均为空。
5. 不写 `09-54-RESEARCH.md` / `09-54-VALIDATION.md`;不改 `STATE.md` / `ROADMAP.md` / `09-CONTEXT.md` / 09-52 / 09-53 / `types.ts` / `package.json`。
</action>
<verify>
<automated>node -e "const fs=require('fs');const f='.planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md';const s=fs.readFileSync(f,'utf8');const need=['09-54','parseRenderAnimation','RenderAnimater','IAnimationParsedData','originX','prettier','eslint','vitest','类型门禁','0 次提交','files_modified','浏览器 E2E'];const miss=need.filter(n=>s.indexOf(n)===-1);if(miss.length){console.error('missing '+miss.join(','));process.exit(1);}console.log('OK: summary present');"</automated>
<fails_when>SUMMARY 缺少任一必需关键词(打印 `missing <列表>`,退出码 1),或文件不存在(抛出异常并以非 0 退出)。</fails_when>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const p=(process.env.TEMP||'.')+'/gsd-09-54-hashes.txt';const base=fs.readFileSync(p,'utf8').replace(/\r\n/g,'\n').trim().split('\n').filter(Boolean);const now=base.map(l=>{const f=l.split(' ')[0];return f+' '+execSync('git hash-object '+f,{encoding:'utf8'}).trim();});const changed=now.filter((l,k)=>l!==base[k]);const index=now.filter(l=>l.split(' ')[0]==='packages/render-anim/src/index.ts');const ok=base.length===8&&changed.length===1&&index.length===1&&changed[0]===index[0];console.log('changed:\n'+changed.join('\n'));if(!ok){console.error('unexpected changed set');process.exit(1);}console.log('OK: only index.ts changed among baseline');"</automated>
<fails_when>除 `index.ts` 外还有基线路径变化,或 `index.ts` 未变化,或基线行数不是 8(打印 `unexpected changed set`,退出码 1)。</fails_when>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const base=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-54-status.txt','utf8').split(/\r?\n/).filter(l=>l.length>0);const cur=execSync('git status --porcelain -uall',{encoding:'utf8'}).split(/\r?\n/).filter(l=>l.length>0);const inScope=l=>{const p=l.slice(3);return p.indexOf('packages/render-anim/')===0||p.indexOf('.planning/phases/09-minimum-browser-runnable/')===0;};const added=cur.filter(l=>base.indexOf(l)===-1);const removed=base.filter(l=>cur.indexOf(l)===-1);const addedIn=added.filter(inScope);const addedOut=added.filter(l=>!inScope(l));const removedIn=removed.filter(inScope);const removedOut=removed.filter(l=>!inScope(l));const allow=['?? packages/render-anim/src/parse.ts','?? packages/render-anim/src/animater.ts','?? packages/render-anim/src/__test__/parse.test.ts','?? packages/render-anim/src/__test__/animater.test.ts',' M packages/render-anim/src/index.ts','?? .planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md'];const extra=addedIn.filter(l=>allow.indexOf(l)===-1);const missing=allow.filter(l=>addedIn.indexOf(l)===-1);console.log('addedIn:\n'+addedIn.join('\n'));console.log('addedOut:\n'+addedOut.join('\n'));console.log('removedIn:\n'+removedIn.join('\n'));console.log('removedOut:\n'+removedOut.join('\n'));console.log('extra:\n'+extra.join('\n'));console.log('missing:\n'+missing.join('\n'));process.exit(extra.length+missing.length+removedIn.length+addedOut.length+removedOut.length?1:0);"</automated>
<fails_when>`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 任一非空,或 `addedIn` 中出现允许集合之外的路径(打印对应列表,退出码 1)。`addedOut` / `removedOut` 非空表示在相关根之外新增或删除条目,即越界写包外文件。</fails_when>
<automated>node -e "const fs=require('fs');const b=fs.readFileSync('.planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md');const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF;const ok=lf===crlf&&tabs===0&&!bom;console.log((ok?'OK':'FAIL')+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);process.exit(ok?0:1);"</automated>
<fails_when>SUMMARY 出现非 CRLF 换行、制表符或 BOM(打印 `FAIL`,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- 写前范围闸门已用 `<action>` 第 1 步给出的显式 `node` 命令执行,`addedIn` 恰为 Task 2–4 的 4 个新文件加 ` M packages/render-anim/src/index.ts`、`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 为空;写后范围闸门 `addedIn` 恰为这 4 个新文件、`index.ts` 修改行与 `09-54-SUMMARY.md`,`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 为空。
- 哈希闸门确认 8 条基线中只有 `index.ts` 变化;`types.ts`、`package.json`、09-52 / 09-53、`09-54-PLAN.md` 逐字不变。
- `09-54-SUMMARY.md` 含 frontmatter 与本计划范围(逐字写出 `files_modified` 及 6 个路径)、v2 布局与解析结果、帧公式与算例、动画器行为、Task 1 基线、各门禁真实结果(含类型门禁哨兵与运行状态)、未做项与已知限制(OI-9 / OI-10)、待确认项与未校准估算(含 180k 超出 100k 智能区间预算、用户接受不拆分的记录)。
- SUMMARY 为 UTF-8 无 BOM + CRLF + 4 空格 + 无制表符;正文明确写出「不做浏览器 E2E」。
- 全程未执行 git 写命令,0 次提交;除 SUMMARY 外未写任何其它文件。
</acceptance_criteria>
<done>写前范围闸门 `addedIn` 恰为 Task 2–4 的 4 个新文件加 ` M packages/render-anim/src/index.ts`、`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 为空;哈希闸门确认只有 `index.ts` 变化;`09-54-SUMMARY.md` 已写入并包含范围(逐字写出 `files_modified` 与 6 个路径)、v2 布局与解析结果、帧公式与算例、动画器行为、Task 1 基线、各门禁真实结果(含类型门禁哨兵与运行状态)、未做项与已知限制(OI-9 sprite 尺寸交叉比对、OI-10 范围闸门基线脏条目盲区)、待确认项与未校准估算;写后范围闸门 `addedIn` 恰为这 4 个文件、`index.ts` 修改行与 SUMMARY、`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 为空;0 次提交。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 动画二进制 → 解析器 | `.animate` 文件是不可信输入,头部 / 长度 / sprite 表 / JSON / 对象索引全部在解析器内被校验 |
| 解析数据 → 动画器 | 解析器输出的 `IAnimationParsedData` 在动画器内被当作已校验数据使用;动画器不重复校验,但不会访问越界 bitmap 索引 |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-54-01 | Tampering | `parse.ts` 头部 / 长度读取 | high | mitigate | 严格校验 `ANIM` 签名、version 2、总长度恒等式、`imageDataSize` / `metaDataSize` 最小值;任何不符立即抛出,不继续读取 |
| T-54-02 | Tampering | `parse.ts` sprite / bitmap / 帧对象 | high | mitigate | `spriteCount` 受 `imageDataSize` 约束;bitmap 数量必须等于 sprite 数;解码后按 `image.width/height` 校验越界;对象索引必须在 `[0, bitmaps.length)`;失败先 `image.close()` |
| T-54-03 | Denial of Service | `parse.ts` 元数据 JSON / 帧数组 | medium | accept | 元数据由本地受信资源提供;`JSON.parse` 与数组遍历是唯一解压点,帧 / 对象数量直接受文件大小约束;不在本计划引入额外配额系统 |
| T-54-04 | Information Disclosure | `parse.ts` / `animater.ts` | low | accept | 只处理本地动画资源与画布像素,不读取网络 / 存储 / 用户输入,不写日志中的敏感数据 |
| T-54-05 | Tampering | `animater.ts` 画布清理 | low | mitigate | 下次 `.next()` 恢复后对上一帧 `clear()` 并把物理宽高设为 0,正常完成时释放最后一帧;不使用 `try/finally`;提前 `.return()` 交给 GC,测试如实覆盖该行为 |
| T-54-SC | Tampering | npm / pnpm 安装 | high | mitigate | 本计划禁止任何包管理安装命令;不新增依赖,锁文件不变;测试使用根 `vitest` 与现有工具链 |
</threat_model>
<verification>
- **解析器**:`parse.ts` 按 v2 布局读取;`node node_modules/vitest/vitest.mjs run packages/render-anim` 中解析测试覆盖正常、blend、ratio、帧数学、音效、逐项列出的全部失败路径与不自动 close。
- **动画器**:`animater.ts` 实现 `ITextureAnimater<IAnimationParsedData>`;测试覆盖 `once` / `cycled`、下次 `.next()` 清理上一帧与正常完成释放最后一帧、提前 `.return()` 交给 GC(不承诺清理)、空帧 1×1、绘制参数、`frames` 为空与不 dispose 源纹理。
- **格式**:`node node_modules/prettier/bin/prettier.cjs --check` 对 5 个源码 / 测试文件退出码 0,输出 `All matched files use Prettier code style!`。
- **lint**:`node node_modules/eslint/bin/eslint.js` 对 5 个源码 / 测试文件退出码 0、无输出。
- **换行 / BOM / 缩进**:5 个源码 / 测试文件与 SUMMARY 全部 CRLF、无制表符、无 BOM。
- **静态内容**:`parse.ts` 含公开入口 / 浏览器 API / 帧数学 / 常量,无 Node / 原生依赖 / 类型专用导入 / `any` / `export default` / 顶层变量;`animater.ts` 含类 / `once` / `cycled` / HD / AA / `canvas.canvas` / 绘制顺序 / `clear`(且无 `finally`),无纹理 dispose / 计时 API;`parse.ts` 与 `animater.ts` 的公开 API 均带 jsDoc;`index.ts` 恰有三行导出。
- **类型**:node 先跑 `vue-tsc --version` 哨兵、并确认 `--noEmit` 进程正常结束(`status` 非 `null`),再过滤 `packages/render-anim` 诊断,结果为 0 行;全仓既有错误与退出码不参与判定(或 SUMMARY 明确写「类型检查未运行」)。
- **范围**:Task 5 写前 `addedIn` 恰为 4 个新源码 / 测试文件加 ` M packages/render-anim/src/index.ts`、`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 为空;写后 `addedIn` 恰为这 4 个文件、`index.ts` 修改行与 `09-54-SUMMARY.md`,`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 为空。`addedOut` / `removedOut` 为空保留「不越界写包外文件」的保证;基线中已存在的包外脏条目内容漂移不可见(OI-10)。
- **已知限制**:sprite 尺寸表不与元数据 `bitmaps` 或解码图尺寸交叉比对(OI-9),SUMMARY 如实记录。
- **哈希**:8 条基线中只有 `index.ts` 变化;`types.ts`、`package.json`、09-52 / 09-53 的计划与摘要、`09-54-PLAN.md` 哈希不变。
- **明确不做**:不运行游戏 / 浏览器 / dev server;不使用真实 WebP 素材做 E2E;不运行 `pnpm install`;不执行任何 git 写命令,0 次提交。
</verification>
<success_criteria>
- [ ] Task 0 已完整汇报 v2 布局、解析顺序、帧公式与算例、动画器画布策略、命名表、已定取舍与待批准项、180k 估算接受项、影响范围与验证形态,并等待用户针对本计划回复「可以执行」后才继续。
- [ ] `packages/render-anim/src/parse.ts` 已实现 `parseRenderAnimation(buffer: ArrayBuffer): Promise<IAnimationParsedData>`:v2 头部 / sprite 表 / 单 WebP / UTF-8 JSON;完整校验;帧包围盒 / 原点公式;`ratio` 折入 `object.scale`;`blend` 映射;无 Node / 原生依赖;公开入口带 jsDoc。
- [ ] `packages/render-anim/src/animater.ts` 已实现 `RenderAnimater implements ITextureAnimater<IAnimationParsedData>`:惰性 `MotaOffscreenCanvas2D`、`setHD(false)`、`setAntiAliasing(false)`、`size`、`translate → mirror → rotate → globalAlpha → drawImage`、`canvas.canvas` + 帧矩形、下次 `.next()` 清理上一帧与正常完成释放最后一帧(提前 `.return()` 交给 GC,不使用 `try/finally`)、空帧 1×1、不 dispose 源纹理、无帧计时;类与 `once` / `cycled` 带 jsDoc。
- [ ] `packages/render-anim/src/index.ts` 恰有三行星号导出:`./types`、`./parse`、`./animater`。
- [ ] `parse.test.ts` 与 `animater.test.ts` 在 Node 环境使用 fake DOM / fake canvas / mock `createImageBitmap`,覆盖解析、校验、帧数学、生成器序列、下次 `.next()` 清理与正常完成释放、提前 `.return()` 交给 GC、不 dispose 纹理;targeted vitest 全部通过。
- [ ] prettier、eslint、CRLF / BOM / 制表符、静态内容 / jsDoc / 禁止项门禁通过;`vue-tsc` 经 `--version` 哨兵确认可启动且 `--noEmit` 进程正常结束后,过滤 `packages/render-anim` 诊断为 0 行(或 SUMMARY 明确写「类型检查未运行」)。
- [ ] `types.ts`、`package.json` 与 09-52 / 09-53 的计划 / 摘要哈希不变;`09-54-PLAN.md` 未被改写;未修改其它包或配置;未新增依赖。
- [ ] `09-54-SUMMARY.md` 已写入(UTF-8 无 BOM + CRLF),包含范围、v2 布局与解析结果、帧公式与算例、动画器行为、Task 1 基线、各门禁真实结果、未做项与已知限制(OI-9 sprite 尺寸交叉比对、OI-10 范围闸门基线脏条目盲区)、待确认项与未校准估算(含 180k 超出 100k 智能区间预算、用户接受不拆分的记录)。
- [ ] 范围闸门与哈希闸门通过;0 次提交;未运行游戏 / 浏览器 / dev server / `pnpm install`。
</success_criteria>
<output>
Create `.planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md` when done
</output>
@@ -0,0 +1,176 @@
---
phase: 09-minimum-browser-runnable
plan: 54
subsystem: render-anim
tags:
- render-anim
- animation
- binary-parser
- canvas2d
- vitest
requires:
- 09-52 render-anim package skeleton
- 09-53 IAnimationParsedData / IAnimationAnimater contract
provides:
- parseRenderAnimation v2 binary parser
- RenderAnimater lazy frame compositor
- render-anim package root exports
affects:
- packages/render-anim/src/index.ts
actuals:
tokens: 10816
tasks: 6
commits: 0
tech-stack:
added: []
patterns:
- DataView / Uint8Array / TextDecoder / Blob / createImageBitmap
- MotaOffscreenCanvas2D lazy per-frame composition
- vi.mock module boundary for render barrel in Node tests
key-files:
created:
- packages/render-anim/src/parse.ts
- packages/render-anim/src/animater.ts
- packages/render-anim/src/__test__/parse.test.ts
- packages/render-anim/src/__test__/animater.test.ts
modified:
- packages/render-anim/src/index.ts
- .planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md
key-decisions:
- ratio 折入 IAnimationObject.scale(rawScale * ratio),解析数据不含 ratio 成员
- 清理策略采用用户决定的 1B:不使用 try/finally,下次 next 恢复后清理上一帧,正常完成释放最后一帧,提前 return 交给 GC
- 测试用 vi.mock 替换 @motajs/render 边界,规避渲染包根在 Vitest 下的既有循环依赖
patterns-established:
- 浏览器专用解析器只使用 Web 平台 API,不引入 Node / 原生图像依赖
- 帧包围盒按旋转后轴对齐包围盒计算,mirror 不参与包围盒
duration: 约 12 分钟
completed: 2026-11-08T15:39:55+08:00
status: complete
---
# Phase 09 Plan 54: 浏览器动画运行时(v2 解析器 + 动画合成器)Summary
用 v2 二进制解析器 `parseRenderAnimation` 与惰性逐帧合成的 `RenderAnimater`,让 `@motajs/render-anim` 从类型骨架变成可运行的浏览器动画运行时。
## 本计划范围
`files_modified` 逐字如下(共 6 个路径):
- `packages/render-anim/src/parse.ts`
- `packages/render-anim/src/animater.ts`
- `packages/render-anim/src/index.ts`
- `packages/render-anim/src/__test__/parse.test.ts`
- `packages/render-anim/src/__test__/animater.test.ts`
- `.planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md`
本计划编号为 09-54(09-01..09-53 已占用),波次 3,`depends_on: 09-52, 09-53`。只实现 v2 解析器、`RenderAnimater`、包根导出与测试;不改 `types.ts`、`package.json`、其它包、配置或既有计划 / 摘要;不新增依赖;不跑游戏 / 浏览器 / dev server;不执行 git 写命令,**0 次提交**。
Task 0 汇报关卡已按 AGENTS.md / D-03 完整汇报 v2 布局、解析顺序、帧公式与算例、动画器画布策略、命名表、已定取舍、180k 估算接受项、影响范围与验证形态,用户回复「可以执行」后进入 Task 1–5;命名按「导出与命名」表获得批准,未新增表外公开名称。
## v2 布局与解析结果
`parseRenderAnimation(buffer: ArrayBuffer): Promise<IAnimationParsedData>` 按下列布局读取:
- 头部 16 字节:`ANIM`(大端 `0x414e494d`)、UInt32LE version `2`、UInt32LE `imageDataSize`、UInt32LE `metaDataSize`。
- 偏移 16 起:UInt32LE `spriteCount`,随后 `spriteCount × 8` 字节的 sprite 宽高表,然后是单个 WebP。
- 偏移 `16 + imageDataSize` 起:`metaDataSize` 字节 UTF-8 JSON。
- 总长度恒等式:`16 + imageDataSize + metaDataSize === buffer.byteLength`。
解析顺序为先字节 / JSON 校验、再解码、再越界校验、最后构造纹理与帧:
1. 头部与总长度校验;`imageDataSize >= 4`、`metaDataSize >= 1`。
2. `spriteCount >= 1`,`spriteCount * 8 + 4 < imageDataSize`,每个 sprite 宽高 `>= 1`。
3. 切出 WebP 与元数据字节,`TextDecoder('utf-8')` 解码后 `JSON.parse`。
4. 校验 `ratio`、`blend`、`bitmaps`、`frame`、对象元组与音效字段。
5. `createImageBitmap(new Blob([webpBytes], { type: 'image/webp' }))`。
6. 按解码尺寸校验位图越界,失败先 `image.close()` 再抛出。
7. `new Texture(image)`,逐帧转换并返回 `{ texture, bitmaps, frames, blend }`。
`blend` 映射 `0 → AnimationBlendMode.Normal`、`1 → AnimationBlendMode.Add`。公开类型没有 ratio 成员,因此 `ratio` 折入 `IAnimationObject.scale`(保存 `rawScale * ratio`,仍是百分数),动画器用 `/ 100` 计算真实尺寸。
畸形输入覆盖:签名、版本、总长度、`imageDataSize` / `metaDataSize`、sprite 数量与尺寸、bitmap 数量、bitmap 坐标 / 尺寸 / 越界、帧对象索引、ratio、blend、opacity、mirror、音效字段。错误消息均为明确中文;不使用 `try-catch`,`JSON.parse` 与 `createImageBitmap` 的错误自然抛出。
## 帧包围盒 / 原点公式
对帧内每个对象:
- `eff = rawScale * ratio`(解析后即 `object.scale`)
- `w = bitmap.width * eff / 100`、`h = bitmap.height * eff / 100`
- `a = rotate * PI / 180`
- `hx = (w / 2) * |cos a| + (h / 2) * |sin a|`
- `hy = (w / 2) * |sin a| + (h / 2) * |cos a|`
- `minX = min(x - hx)`、`maxX = max(x + hx)`、`minY = min(y - hy)`、`maxY = max(y + hy)`
- `width = max(1, ceil(maxX - minX))`、`height = max(1, ceil(maxY - minY))`
- `originX = -minX`、`originY = -minY`
空帧为 1x1、原点 `0, 0`;`mirror` 不进入包围盒公式。
算例:
1. 单个 32×32、`ratio = 1`、`scale = 100`、`x = y = 0`、`rotate = 0`:`width = height = 32`,`originX = originY = 16`。
2. 同上但 `rotate = 45`:`hx = hy ≈ 22.627`,`width = height = 46`,`originX = originY ≈ 22.627`。
3. 空帧:`width = height = 1`,`originX = originY = 0`,动画器产出透明 1x1。
## 动画器行为
`RenderAnimater implements ITextureAnimater<IAnimationParsedData>`,`once` / `cycled` 委托私有生成器 `sequence`:
- 每帧 `new MotaOffscreenCanvas2D()`,`setHD(false)`、`setAntiAliasing(false)`、`size(frame.width, frame.height)`。
- 绘制顺序:`save` → `translate(frame.originX + object.x, frame.originY + object.y)` → `scale(-1, 1)`(mirror)→ `rotate(-object.rotate * Math.PI / 180)` → `globalAlpha = object.opacity / 255` → `drawImage(source, bitmap.x, bitmap.y, bitmap.width, bitmap.height, -realWidth / 2, -realHeight / 2, realWidth, realHeight)` → `restore`。
- yield `{ source: canvas.canvas, rect: { x: 0, y: 0, w: frame.width, h: frame.height } }`,`source` 是 `HTMLCanvasElement`。
- 清理策略(用户决定 1B,不使用 `try/finally`):下次 `.next()` 恢复后对上一帧 `clear()` 并把物理宽高设为 `0`;`once` 正常完成时释放最后一帧;提前 `.return()` 跳过正常结束路径,最后一帧交给 GC,本计划不承诺 `.return()` 清理。
- 空帧创建 1x1 画布且不调用 `drawImage`;`frames` 为空时不 yield;不 dispose 源纹理;不实现帧计时 / 定时器 / 请求动画帧。
## Task 1 基线
- 8 条哈希基线(`types.ts`、`package.json`、`index.ts`、09-52 / 09-53 计划与摘要、`09-54-PLAN.md`)已写入 `process.env.TEMP/gsd-09-54-hashes.txt`;范围基线写入 `process.env.TEMP/gsd-09-54-status.txt`。
- `packages/render-anim` 工作树在 Task 1 时干净,`package.json` / `src/index.ts` / `src/types.ts` 已在 HEAD `7bf9fe9` 中跟踪。
- 工具链实测:`node v24.21.0`;`node_modules/vitest/vitest.mjs`、`prettier.cjs`、`eslint.js`、`vue-tsc.js` 均存在;`vite.config.ts` 的 `@motajs/*` 别名映射到 `packages/*/src`;`tsconfig.json` 的 `include` 覆盖 `packages/**/*.ts`。
## 门禁真实结果
- `node node_modules/vitest/vitest.mjs run packages/render-anim`:`Test Files 2 passed (2)`、`Tests 30 passed (30)`。
- `node node_modules/prettier/bin/prettier.cjs --check <5 files>`:`All matched files use Prettier code style!`。
- `node node_modules/eslint/bin/eslint.js <5 files>`:无输出,退出码 0。
- CRLF / BOM / 制表符门禁:`OK: all 5 files are CRLF, no tabs, no BOM`。
- 静态内容门禁:解析器关键 token、`parseRenderAnimation` jsDoc、浏览器专用 / 无副作用检查均 `OK`;`parse.ts exports only parseRenderAnimation`;动画器 shape / jsDoc / `animater.ts exports only RenderAnimater` 均 `OK`;`index.ts has exactly the 3 exports in order`。
- 类型门禁:已运行。`sentinel: vue-tsc Version 6.0.3 | type check exit 2`(仓库既有错误导致全仓退出码 2),过滤后 `OK: no render-anim diagnostics`。
- 哈希闸门:`changed: packages/render-anim/src/index.ts ...`,`OK: only index.ts changed among baseline`。
- 写前范围闸门:`addedIn` 恰为 4 个新文件加 ` M packages/render-anim/src/index.ts`,`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 均空,输出 `OK: pre-write range matches the 5 expected entries`。
- 写后范围闸门:`addedIn` 恰为 4 个新文件、` M packages/render-anim/src/index.ts` 与 `?? .planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md`,`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 均空。
## 未做 / 跳过项与已知限制
- **不做浏览器 E2E**:不运行游戏 / 浏览器 / dev server,不使用真实 WebP 素材;运行时浏览器行为不做主张。测试只在 Node 环境以 mock `createImageBitmap` 与假画布验证纯逻辑与绘制调用参数。
- 不运行 `pnpm install`;不执行 git 写命令,0 次提交。
- **OI-9**:sprite 尺寸表只校验 `>= 1` 与用于计算 WebP 偏移,不与元数据 `bitmaps` 或解码后的 `image.width` / `image.height` 交叉比对;裁剪矩形以 `bitmaps` 为准。
- **OI-10**:范围闸门以 Task 1 的 porcelain 路径集合为基线,相关根之外的新增 / 删除条目必须为空;基线中已存在的包外脏条目若被外部改动,其内容漂移在路径集合中不可见。本计划执行期间未并发修改工作树,`packages/render-anim` 在 Task 1 已断言干净。
## 偏差与执行说明
1. **[Rule 3 - 阻塞] 测试改为 mock `@motajs/render` 模块边界**:真实渲染包根在 Vitest 的模块转换下暴露既有循环依赖(`core/index.ts` 先导出 `graphics.ts`,而 `graphics.ts` 从 `'.'` 取 `RenderItem`,此时 `./item` 尚未导出,导致 `Class extends value undefined`)。测试改为在 `vi.hoisted` 中定义假 `Texture` / `MotaOffscreenCanvas2D` 并 `vi.mock('@motajs/render')`,仍以假画布、假 2D context 与 mock `createImageBitmap` 验证解析、帧数学、生成器序列、清理与不 dispose 纹理。未修改 `packages/render` 或任何配置。
2. **[格式] 旋转表达式保留计划字面量**:Prettier 会把 `-object.rotate * Math.PI / 180` 改写成 `(-object.rotate * Math.PI) / 180`,为同时满足计划门禁的字面量与 `prettier --check`,在该行前使用 `// prettier-ignore`;语义不变。
3. 为满足计划门禁的 `canvas.clear()` 字面量,`sequence` 的上一帧变量命名为 `canvas`,行为与设计一致。
## 待确认项 / 已定项
- **OI-1**:`parseRenderAnimation`、`RenderAnimater` 与内部名称按「导出与命名」表经 Task 0 批准。
- **OI-2**:公开类型无 ratio 成员,`ratio` 折入 `IAnimationObject.scale`。
- **OI-3**:清理策略已由用户决定为 1B(不使用 `try/finally`;不承诺 `.return()` 清理)。
- **OI-4**:raw 帧对象元组接受 5–7 个元素,缺省 `mirror` / `rotate` 为 0。
- **OI-5**:解析器不修改 `Texture.isBitmap`;`data.texture` 由调用方拥有并负责 `dispose()`。
- **OI-6**:运行时浏览器行为不做 E2E 测试(可见跳过)。
- **OI-7**:`estimate` 为 180k、`confidence: low`,未校准,超出 100k 智能区间预算;用户已明确接受保持单个组合计划、不拆分为 09-54 / 09-55,本计划不声称符合智能区间预算。
- **OI-8**:09-52 / 09-53 产物已提交(HEAD `7bf9fe9`);本计划 0 次提交,改动留在工作树供审阅。
## 估算与实际
- 估算:`tokens: 180000`、`tasks: 6`、`confidence: low`(未校准,超出 100k 智能区间预算,用户已接受不拆分)。
- 实际(按最终文件 chars/4 测量,仅 5 个源码 / 测试文件):约 `tokens: 10816`;`tasks: 6`;`commits: 0`。
- 最终行数:`parse.ts` 430 行、`animater.ts` 129 行、`index.ts` 4 行、`parse.test.ts` 493 行、`animater.test.ts` 377 行。
## Self-Check
- 5 个源码 / 测试文件与 SUMMARY 均存在且为 CRLF、无 BOM、无制表符。
- targeted vitest 30 个测试全部通过;prettier / eslint / 静态内容 / 哈希 / 范围门禁通过;过滤类型门禁为 0 行 render-anim 诊断。
- 0 次提交,未越界写包外文件。
@@ -0,0 +1,743 @@
---
phase: 09-minimum-browser-runnable
plan: 55
type: execute
# 编号说明:09-01..09-54 均已占用,本计划使用下一个空闲编号 09-55。
# depends_on 09-54:本计划只改 09-54 已实现的 parse.ts 与 parse.test.ts。
wave: 4
depends_on:
- 09-54
files_modified:
- packages/render-anim/src/parse.ts
- packages/render-anim/src/__test__/parse.test.ts
- packages/render-anim/package.json
- packages/common/src/logger.json
- .planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md
autonomous: false
requirements: []
estimate:
# 未校准估算(confidence: low),SUMMARY 须声明;6 个任务 / 90k 仅为建议值(advisory,不触发拆分),不因此再切分。
# 成本主要在 parse.ts 全量改写(429 行 + 末尾换行 = 430 行 → 无 throw 的 null 返回路径)、测试全量改写(21 个用例 + 新增 94 / 95 用例 + 5 个非对象元数据用例(`42` / `null` / `0` / `false` / `""`))、
# logger.json 追加 14 条错误码,以及 vitest / prettier / eslint / 过滤 vue-tsc 的往返。
tokens: 90000
raw_tokens: 90000
tasks: 6
confidence: low
must_haves:
truths:
- "**第一个 block 点是 Task 0 的 `blocking-human` 汇报关卡(AGENTS.md / D-03)**:汇报可空签名、82–95 错误码表、`@motajs/common` 依赖、`try/catch` 作用域、唯一被改写的 jsDoc、测试形态与影响范围;然后停下等待用户恰好回复「可以执行」。"
- "**公开签名可空(用户决定 1)**:`export async function parseRenderAnimation(buffer: ArrayBuffer): Promise<IAnimationParsedData | null>`;成功返回 `IAnimationParsedData`,任一步失败返回 `null`,由调用方判空。"
- "**错误码 82–95(用户决定 2)**:`packages/common/src/logger.json` 的 `error` 段按 82–95 顺序追加 14 条英文消息,参数用 `$1` / `$2` 等占位;不使用 `1000+` 码段;`warn` 段(含并发新增的 `213`)逐字保留。"
- "**无 throw(用户决定 5)**:`packages/render-anim/src/parse.ts` 全文不出现 `throw`;所有校验失败先 `logger.error(<code>, ...)` 再 `return null`;`parse.ts` 的 jsDoc 与注释也不出现 `throw` / `@throws`。"
- "**try/catch 只包裹天然会抛的外部调用(用户决定 4)**:恰好 3 处 `try {`,块体内分别只有 `meta = JSON.parse(text);`(94)、`image = await createImageBitmap(webpBlob);`(95)、`texture = new Texture(image);`(95)这三个外部调用表达式;`new Blob([webpBytes], { type: 'image/webp' })` 在 `try` 之前构造,`!isRecord(meta)` 守卫与 `return meta` 在 `try` 之后;不出现 `finally`;不包裹其它逻辑。"
- "**资源不泄漏**:解码后位图越界时先在 `image.close()` 之前捕获 `image.width` / `image.height`,再 `close()`,再用捕获到的尺寸记录 87 并返回 `null`;`new Texture(image)` 失败时同样先 `image.close()` 再返回 `null`(错误码 95)。"
- "**依赖(用户决定 3)**:`packages/render-anim/package.json` 新增 `\"@motajs/common\": \"workspace:*\"`(排在 `@motajs/render` 之前),不改动其它字段。"
- "**测试断言空返回与错误码**:`parse.test.ts` mock `@motajs/common` 的 `logger`,每个失败用例断言返回 `null` 且 `logger.error` 首个实参等于期望错误码;成功用例全部保留;另加 `parse.ts` 不含 `throw` 的静态闸门。"
- "**范围受控、0 提交**:只写 `files_modified` 的 5 个路径;`types.ts` / `animater.ts` / `index.ts` / 其它包 / 配置 / 既有计划与摘要均不改;不跑游戏 / 浏览器 / dev server;不提交。"
artifacts:
- path: packages/render-anim/src/parse.ts
provides: "可空签名的 `parseRenderAnimation`、`logger.error` + `return null` 失败路径、3 处仅包裹外部调用表达式的最小 `try/catch`"
- path: packages/render-anim/src/__test__/parse.test.ts
provides: "mock logger 的空返回 / 错误码断言、成功路径测试、无 `throw` 静态闸门"
- path: packages/render-anim/package.json
provides: "`@motajs/common: workspace:*` 工作区依赖"
- path: packages/common/src/logger.json
provides: "error 段 82–95 共 14 条英文消息,warn 段(含 213)不变"
- path: .planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md
provides: "改写结果、错误码表、测试与门禁真实输出、已知限制、未校准估算、0 次提交"
key_links:
- "`parse.ts` → `import { logger } from '@motajs/common'` → `logger.error(code, ...)`;`logger.error` 的 `...params: string[]` 只接受字符串,数字必须显式 `.toString()` 或走模板字符串"
- "`logger.json` error 82–95 ↔ `parse.ts` 的 `logger.error` 调用点;新增码必须落在 82–95,`1000+` 属于独立系统包,禁止使用"
- "`parseRenderAnimation` 返回 `null` ↔ 调用方判空;`parse.test.ts` 用 `expect(data).toBeNull()` + `loggerMock.error.mock.calls[0][0]` 断言"
- "`packages/render-anim/package.json` 的 `@motajs/common` ↔ `vite.config.ts` 的 `@motajs/*` 别名与 `tsconfig.json` 的 `paths`,测试 / 类型检查按源码解析,无需 `pnpm install`"
- "`vi.mock('@motajs/common')` ↔ `vi.mock('@motajs/render')`:两者都必须在导入 `../index` 之前声明,否则模块加载期就会取到真实实现"
assumptions:
- "**工作树基线(规划日实测,2026-11-08)**:HEAD `7bf9fe9`;`packages/render-anim/src/parse.ts`(429 行 + 末尾换行 = 430 行)与 `src/__test__/parse.test.ts`(492 行)均为未跟踪新文件;`git hash-object` 分别为 `db9f4e4e974d6ff03c32d2e452a1144202da986e` / `ba8e365ab80e9b2ed7de383685ff2ce3eed7053c`。"
- "**logger.json 并发改动(规划日实测)**:`packages/common/src/logger.json` 为 ` M` 状态,相对 HEAD 只多一行 `\"213\": \"Setting item '$1' has existed in group '$2'. The item will be moved to new group '$3'.\"`;error 段当前为 1..81 + 2001..2008,warn 段为 1..213 + 1001。该并发改动必须逐字保留,不得回退。"
- "**当前测试通过(规划日实测)**:`node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts` → 21 passed;`prettier --check` 对 `logger.json` / `package.json` / `parse.ts` / `parse.test.ts` 全部通过;`eslint` 对 `parse.ts` / `parse.test.ts` 退出码 0。"
- "**logger 运行环境(规划日实测)**:`packages/common/src/logger.ts` 的顶层 DOM 探测以 `typeof document !== 'undefined' && typeof main !== 'undefined'` 为条件,Node / vitest 下不触碰 DOM;`logger.error(code: number, ...params: string[])` 未命中码时会转调 `logger.error(16, ...)`。"
- "**依赖解析(规划日实测)**:`packages/render-anim/node_modules/@motajs` 只有 `render`,加入 `@motajs/common` 后不跑 `pnpm install`;`vite.config.ts` 把 `@motajs/*` 映射到 `packages/*/src`,`tsconfig.json` 的 `paths` 同样映射,故 vitest / `vue-tsc` 仍可按源码解析。锁文件 `pnpm-lock.yaml` 已是脏状态,本计划不更新它。"
- "**本 run 无 RESEARCH / 无 VALIDATION**:本阶段无 requirement ID(`requirements: []`),Nyquist 不适用;spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip)。"
prohibitions:
- "不得在用户恰好回复「可以执行」之前执行任何任务或派发执行子代理(AGENTS.md / D-03)。"
- "不得修改 `packages/render-anim/src/types.ts`、`animater.ts`、`index.ts`、其它包、根配置、锁文件或任何既有计划 / 摘要;不得新增 `@motajs/common` 之外的依赖。"
- "不得改写 `parse.ts` 中 `parseRenderAnimation` 以外任何已有注释 / jsDoc;唯一允许的注释改写是 Task 0 逐字批准的那一段 jsDoc。"
- "不得使用 `1000+` 错误码;不得改动 `logger.json` 的 `warn` 段(含并发新增的 `213`);不得重排既有码。"
- "不得把 `try/catch` 扩大到 `meta = JSON.parse(text)` / `image = await createImageBitmap(webpBlob)` / `texture = new Texture(image)` 这三个调用表达式之外——`try` 块体内不得出现 `isRecord`、`return meta`、`new Blob` 或任何其它语句;不得写 `finally`;不得靠 `catch` 吞掉非预期的编程错误后继续执行。"
- "不得运行游戏、浏览器、dev server、`pnpm install` 或任何 git 写命令;本计划全程 0 次提交。"
- "不得新增公开 / 受保护 / 私有方法、字段或导出命名;函数内局部变量不属于此列(本计划新增 `webpBlob` / `imageWidth` / `imageHeight` / `reason`,仅存在于 `parse.ts` 函数体内,已在 Task 0 报备);内部函数名沿用 09-54 的「导出与命名」表(`readHeader` / `readSpriteDimensions` / `readRawMeta` / `validateMeta` / `validateBitmapBounds` / `toFrame` / `toObject` / `computeFrameBox` / `toBlendMode` / `isRecord` / `isNumber` / `isInteger` / `ANIMATION_*`)。"
open_items:
- "**OI-1(Task 0 批准)**:公开签名由 `Promise<IAnimationParsedData>` 改为 `Promise<IAnimationParsedData | null>`;`parseRenderAnimation` 的 jsDoc 同步改写(删除 `@throws` 行,`@returns` 末尾改为「任一步校验或解码失败时输出日志并返回 null」)。该 jsDoc 是本计划唯一被改写的既有注释,需在 Task 0 逐字批准。"
- "**OI-2(Task 0 批准)**:`logger.json` error 段新增 14 条英文消息(82–95),文本见本计划「错误码映射」表;插入位置为 `\"81\"` 行之后、`\"2001\"` 行之前。"
- "**OI-3(Task 0 批准)**:`packages/render-anim/package.json` 新增 `\"@motajs/common\": \"workspace:*\"`。"
- "**OI-4(Task 0 批准)**:`try/catch` 是本计划对 `dev.md`「不建议写 try-catch」的显式例外——`JSON.parse` / `createImageBitmap` / `new Texture` 是外部 API 的天然抛错点,畸形动画文件属于运行时数据条件而非编程错误,用户已决定「记录日志后返回 null」;作用域严格限制在这三处。"
- "**OI-5(Task 0 报备)**:测试文件新增的局部名称 `loggerMock` / `renderState` / `parseOk` / `expectFailure` / `buildRawAnimation` 仅存在于 `__test__/parse.test.ts`,不进入生产代码。"
- "**OI-6(只记录)**:不运行 `pnpm install`,`pnpm-lock.yaml` 不更新;`packages/render-anim/node_modules` 不会出现 `@motajs/common` 链接。测试与类型检查依赖 `vite.config.ts` / `tsconfig.json` 的路径别名;若后续要独立构建该包,需由用户自行执行 `pnpm install`。"
- "**OI-7(只记录)**:`logger.error` 的引用页编号为 `Math.floor(code / 50) + 1`(82–95 落在 `error2.html`),本计划不生成 / 不修改文档页面,仅写入 `logger.json`。"
- "**OI-8(只记录,可见跳过)**:运行时浏览器行为不做 E2E;测试只在 Node 环境用 mock 的 `createImageBitmap` / fake `Texture` / mocked `logger` 验证纯逻辑。"
---
<!-- planner-discipline-allow: throw -->
<!-- planner-discipline-allow: @throws -->
<!-- planner-discipline-allow: try -->
<!-- planner-discipline-allow: catch -->
<!-- planner-discipline-allow: finally -->
<!-- planner-discipline-allow: forEach -->
<!-- planner-discipline-allow: parseRenderAnimation -->
<!-- planner-discipline-allow: IAnimationParsedData -->
<!-- planner-discipline-allow: any -->
<!-- planner-discipline-allow: import type -->
<!-- planner-discipline-allow: Buffer -->
<objective>
Phase 9 · 第 55 个计划(09-54 的修复增量)—— 把 `@motajs/render-anim` 的解析器从「抛异常」改为「记录日志 + 返回 null」,并接入项目统一 logger。
**要解决的问题:** 09-54 实现的 `packages/render-anim/src/parse.ts` 用 `throw new Error(...)` 表达全部失败路径,公开签名是 `Promise<IAnimationParsedData>`。这与项目统一的 `@motajs/common` logger 体系不一致:动画文件是运行时数据,畸形输入应当被记录成带错误码的日志并由调用方判空,而不是把异常抛给上层。同时 `packages/render-anim` 目前只依赖 `@motajs/render`,没有 logger 可用。
**做法(用户决定,锁定):**
- 公开签名改为 `Promise<IAnimationParsedData | null>`;失败一律 `logger.error(code, ...)` 后 `return null`,由调用方判空(用户决定 1 / 5)。
- `packages/common/src/logger.json` 的 `error` 段按 82–95 追加 14 条英文消息(用户决定 2);不使用 `1000+` 码段;`warn` 段的并发改动 `213` 逐字保留。
- `packages/render-anim/package.json` 新增 `@motajs/common: workspace:*`(用户决定 3)。
- 仅对天然会抛的外部调用使用最小 `try/catch`:块体内分别只有 `meta = JSON.parse(text)`(94)、`image = await createImageBitmap(webpBlob)`(95)、`texture = new Texture(image)`(95);`new Blob(...)` 在 `try` 前构造、`!isRecord` 守卫在 `try` 后;解码后位图越界先用 `close()` 前捕获的尺寸记 87,再 `image.close()` 并返回 `null`(用户决定 4)。
- `parse.test.ts` mock `@motajs/common` 的 `logger`,逐条断言「返回 null + 精确错误码」;成功用例保留;并加静态闸门证明 `parse.ts` 无 `throw`。
**约束:** 只写 `files_modified` 的 5 个路径;不改 `types.ts` / `animater.ts` / `index.ts` / 其它包 / 配置 / 既有计划;唯一允许改写的既有注释是 Task 0 批准的 `parseRenderAnimation` jsDoc;不跑游戏 / 浏览器 / dev server / `pnpm install`;0 次提交。(D-01 增量派发 / D-02 计划累积追加 / D-03 执行前汇报 / D-04 命名先反馈 / D-05 默认不逐阶段验证 / D-06 范围由用户界定。)
**修改方式声明(AGENTS.md):** 执行期间的全部源码、测试与 `09-55-SUMMARY.md` 写入均由**派发子代理(`gsd-executor`)执行**,非内联执行;本计划文件自身由规划流程(`gsd-planner`)创建。除 `files_modified` 外无任何写入。
**可见跳过:** spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip)。本阶段无 requirement ID,不创建 RESEARCH.md / VALIDATION.md,Nyquist 验证不适用。
</objective>
## 本计划产出物(Artifacts this plan produces)
| 类型 | 名称 / 路径 | 说明 |
|------|-------------|------|
| 改写(解析器) | `packages/render-anim/src/parse.ts` | 可空签名、`logger.error` + `return null`、3 处最小 `try/catch` |
| 改写(测试) | `packages/render-anim/src/__test__/parse.test.ts` | mock logger、空返回 / 错误码断言、成功用例、无 `throw` 闸门 |
| 修改(依赖) | `packages/render-anim/package.json` | 新增 `@motajs/common: workspace:*` |
| 修改(日志表) | `packages/common/src/logger.json` | error 段追加 82–95(14 条),warn 段不动 |
| 交付 | `.planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md` | 改写结果、错误码表、门禁真实输出、已知限制、未校准估算、0 次提交 |
| 只验证不修改 | `packages/render-anim/src/types.ts` / `animater.ts` / `index.ts` | 哈希与 Task 1 基线一致 |
| 只验证不修改 | `logger.json` 的 `warn` 段(含 `213`) | 与 Task 1 快照深比较一致 |
## 错误码映射(82–95,唯一依据)
`logger.error(code, ...params)` 的 `params` 类型是 `string[]`:所有数字实参必须先 `.toString()`,或在模板字符串里拼接。下表 message 为 `logger.json` 中的最终文本(`$n` 为占位符)。
| code | 类别 | message |
|------|------|---------|
| 82 | 缓冲区过短 | `Cannot parse animation: buffer is too short, got $1 bytes while the $2 byte header is required.` |
| 83 | 签名无效 | `Cannot parse animation: invalid signature 0x$1, expected 0x$2.` |
| 84 | 版本不支持 | `Cannot parse animation: unsupported version $1, expected version $2.` |
| 85 | 长度字段 / 总长度不符 | `Cannot parse animation: data length mismatch, imageDataSize: $1, metaDataSize: $2, buffer length: $3.` |
| 86 | sprite 数量 / 尺寸 | `Cannot parse animation: $1.` |
| 87 | 位图数量 / 字段 / 越界 | `Cannot parse animation: $1.` |
| 88 | 帧结构(非数组 / 非对象 / 元组元数 5–7) | `Cannot parse animation: $1.` |
| 89 | 对象索引 | `Cannot parse animation: invalid object index $1 at frame $2, expected an integer in [0, $3).` |
| 90 | 对象字段(x / y / scale / opacity / mirror / rotate) | `Cannot parse animation: $1.` |
| 91 | ratio | `Cannot parse animation: invalid ratio $1, expected a positive finite number.` |
| 92 | blend | `Cannot parse animation: invalid blend mode $1, expected 0 (normal) or 1 (add).` |
| 93 | 音效字段 | `Cannot parse animation: $1.` |
| 94 | 元数据 JSON 解析失败 | `Cannot parse animation: cannot parse metadata JSON. $1` |
| 95 | 图像解码 / 纹理创建失败 | `Cannot parse animation: cannot decode image or create texture. $1` |
**`$1` 明细串(86 / 87 / 88 / 90 / 93)的固定写法(同一错误码覆盖同类多项检查,明细由调用点用模板字符串给出):**
| code | 明细串示例 |
|------|-----------|
| 86 | `sprite count 0 is not allowed` / `sprite 1 has invalid size 0 x 32` / `sprite table of 3 sprites exceeds imageDataSize 12` |
| 87 | `bitmap list is not an array` / `bitmap count 2 does not match sprite count 1` / `bitmap 0 is not an object` / `bitmap 0 has invalid x -1` / `bitmap 0 (x: 0, y: 0, width: 32, height: 32) exceeds the decoded image 16 x 16` |
| 88 | `frame list is not an array` / `frame 0 is not an object` / `objects of frame 0 is not an array` / `object 0 of frame 0 is not a tuple` / `object 0 of frame 0 has 4 fields, expected 5 to 7` / `sound of frame 0 is not an array` |
| 90 | `object 0 of frame 0 has invalid x: NaN` / `object 0 of frame 0 has invalid scale: 0, expected a positive number` / `object 0 of frame 0 has invalid opacity: 300, expected a number in [0, 255]` |
| 93 | `sound 0 of frame 0 is not an object` / `sound 0 of frame 0 has invalid name` / `sound 0 of frame 0 has invalid volume: NaN` / `sound 0 of frame 0 has invalid pitch: NaN` |
**94 / 95 的 `$1` 来源:** 94 的 `$1` 固定为 `metadata is not valid JSON`(脱敏常量,**不读取 `error.message`**,避免 `JSON.parse` 的异常文本回显元数据内容);95 的 `$1` 为解码 / 纹理异常的 `error.message`(`error instanceof Error ? error.message : String(error)`)。
**码段边界:** error 段现有 `1..81` 与 `2001..2008`;本计划只新增 `82..95`。`1000+`(含 `1001` / `2001..2008`)属于独立系统包,禁止使用或修改。
## `parse.ts` 改写规格(逐函数)
**导入与分区:** 在第 1 行新增 `import { logger } from '@motajs/common';`,其后保持现有 `./types` 与 `@motajs/render` 两行顺序不变;所有 import 连续、中间不夹注释或空行。现有 `//#region 常量与内部类型` / `//#region 读取与校验` / `//#region 帧转换与帧数学` / `//#region 导出解析器` 分区保持不变。
**`readHeader(data: DataView): IAnimationHeader | null`**
- `data.byteLength < ANIMATION_HEADER_SIZE` → `logger.error(82, data.byteLength.toString(), ANIMATION_HEADER_SIZE.toString())`,`return null`。
- `data.getUint32(0) !== ANIMATION_SIGNATURE` → `logger.error(83, signature.toString(16), ANIMATION_SIGNATURE.toString(16))`,`return null`。
- `data.getUint32(4, true) !== ANIMATION_VERSION` → `logger.error(84, version.toString(), ANIMATION_VERSION.toString())`,`return null`。
- `imageDataSize < 4 || metaDataSize < 1 || ANIMATION_HEADER_SIZE + imageDataSize + metaDataSize !== data.byteLength` → `logger.error(85, imageDataSize.toString(), metaDataSize.toString(), data.byteLength.toString())`,`return null`。
- 其余情况返回 `{ imageDataSize, metaDataSize }`。
**`readSpriteDimensions(data: DataView, count: number): ISpriteDimension[] | null`**
- 每个 sprite 的 `width < 1 || height < 1` → `logger.error(86, \`sprite ${i} has invalid size ${width} x ${height}\`)`,`return null`。
- 全部合法时返回尺寸数组。
**`readRawMeta(buffer: ArrayBuffer, offset: number, size: number): IRawAnimationMeta | null`**
- 保留 `new Uint8Array(buffer, offset, size)` 与 `new TextDecoder('utf-8').decode(bytes)`。
- **唯一 `try {` 之一(作用域必须最小):** 先声明 `let meta: IRawAnimationMeta;`,然后 `try { meta = JSON.parse(text); } catch { logger.error(94, 'metadata is not valid JSON'); return null; }`。`try` 块体内**只有** `meta = JSON.parse(text);` 这一条语句;`catch` 使用无绑定形式 `catch {`(不需要异常对象,94 只输出脱敏常量,**不得传 `error.message`**)。
- **非对象守卫在 `try` 之外:** `try/catch` 之后写 `if (!isRecord(meta)) { logger.error(88, 'metadata is not an object'); return null; }`,最后 `return meta;`。`!isRecord` 守卫与 `return meta` 都**不得**放进 `try`。
- **必须拒绝非对象 JSON(BLOCKER 修复):** `JSON.parse` 对 `null` / `0` / `false` / `""` / `42` 返回同名原语,若直接 `return meta`,`parseRenderAnimation` 的 `if (!meta) return null;` 会在 `validateMeta` 之前静默短路,既不记 88 也不记 94。因此解析后用 `!isRecord(meta)` 守卫(`isRecord` 已排除 `null` 与数组):非对象 → `logger.error(88, 'metadata is not an object')` + `return null`。`readRawMeta` 返回 `null` 当且仅当失败,绝不会返回 falsy 的合法解析结果。
- `catch` 变量按 `unknown` 语义处理(`strict` 默认 `useUnknownInCatchVariables`),不得写 `any`,不得写 `as` 断言;94 使用无绑定 `catch {`,95 使用 `error instanceof Error ? error.message : String(error)`。
**`validateMeta(meta: IRawAnimationMeta, spriteCount: number): boolean`**
- **循环必须可提前退出(WARNING 修复,必须显式遵守):** 一律用 `for (let i = 0; i < list.length; i++)` / `for (const item of list)` 这类可 `return` 的循环,**禁止用 `forEach`**:`forEach` 回调里的 `return false` 只退出当前回调,校验会继续执行,可能在记录失败日志后仍走到 `return true`。每个失败检查写成「`logger.error(<code>, <明细或参数>)` 后立刻 `return false`」,保证一次失败只记录一次并立即结束;全部通过时 `return true`。
- `!isRecord(meta)` → 88(`metadata is not an object`)。`readRawMeta` 已在解析后用同一守卫拒绝非对象 JSON,因此本守卫是纵深防御(正常路径不可达);命中时同样 `logger.error(88, ...)` + `return false`。
- `!isNumber(meta.ratio) || meta.ratio <= 0` → 91(`meta.ratio.toString()`)。
- `!isNumber(meta.blend) || (meta.blend !== 0 && meta.blend !== 1)` → 92(`meta.blend.toString()`)。
- `!Array.isArray(meta.bitmaps)` → 87(`bitmap list is not an array`)。
- `meta.bitmaps.length !== spriteCount` → 87(`bitmap count ${meta.bitmaps.length} does not match sprite count ${spriteCount}`)。
- 用带下标的 `for` 循环遍历 `meta.bitmaps`(不得用 `forEach`):非对象 → 87(`bitmap ${i} is not an object`);`x` 非有限或 `< 0` → 87(`bitmap ${i} has invalid x ${bitmap.x}`);`y` 同理;`width` / `height` 非有限或 `< 1` 同理(逐字段单独报,便于定位)。
- `!Array.isArray(meta.frame)` → 88(`frame list is not an array`)。
- 用带下标的 `for` 循环遍历 `meta.frame`(不得用 `forEach`):非对象 → 88(`frame ${frameIndex} is not an object`);`objects` 存在但非数组 → 88(`objects of frame ${frameIndex} is not an array`)。
- 用带下标的 `for` 循环遍历帧内对象(不得用 `forEach`):非数组 → 88(`object ${objectIndex} of frame ${frameIndex} is not a tuple`);`length < 5 || length > 7` → 88(`object ${objectIndex} of frame ${frameIndex} has ${length} fields, expected 5 to 7`)。
- `index = object[0]`:`!isInteger(index) || index < 0 || index >= meta.bitmaps.length` → 89(`index.toString()`、`frameIndex.toString()`、`meta.bitmaps.length.toString()`)。
- 对象字段:`object[1]` / `object[2]` 非有限 → 90(`object ${objectIndex} of frame ${frameIndex} has invalid x/y: ${value}`);`object[3]` 非有限或 `<= 0` → 90(`... invalid scale: ${value}, expected a positive number`);`object[4]` 非有限或越出 `[0, 255]` → 90(`... invalid opacity: ${value}, expected a number in [0, 255]`);`object[5] !== undefined && !isNumber(object[5])` → 90(`... invalid mirror: ${value}`);`object[6]` 同理(`rotate`)。
- `sound` 存在但非数组 → 88(`sound of frame ${frameIndex} is not an array`)。
- 用带下标的 `for` 循环遍历 `sound`(不得用 `forEach`):非对象 → 93(`sound ${i} of frame ${frameIndex} is not an object`);`typeof name !== 'string' || name.length === 0` → 93(`... has invalid name`);`volume` 存在但非有限 → 93(`... has invalid volume: ${value}`);`pitch` 同理。
**`validateBitmapBounds(bitmaps: readonly IRawAnimationBitmap[], image: ImageBitmap): boolean`**
- 进入函数后、循环之前先捕获尺寸:`const imageWidth = image.width; const imageHeight = image.height;`(必须在 `image.close()` 之前取,`close()` 之后 `ImageBitmap` 的宽高不可靠)。
- 用带下标的 `for` 循环遍历(不得用 `forEach`,理由同 `validateMeta`:`forEach` 回调里的 `return false` 不会结束整个函数);越界条件与 09-54 完全一致(`x < 0 || y < 0 || width < 1 || height < 1 || x + width > imageWidth || y + height > imageHeight`)。
- 越界时先 `image.close()`,再 `logger.error(87, \`bitmap ${i} (x: ${bitmap.x}, y: ${bitmap.y}, width: ${bitmap.width}, height: ${bitmap.height}) exceeds the decoded image ${imageWidth} x ${imageHeight}\`)`,`return false`;全部通过 `return true`。日志**不得**在 `close()` 之后读取 `image.width` / `image.height`,只能用捕获的 `imageWidth` / `imageHeight`。
- 保持函数原有 jsDoc 不修改(「失败时释放纹理避免泄漏」仍成立)。
**`toObject` / `toFrame` / `computeFrameBox` / `toBlendMode`:逻辑与签名全部不变**,只是不再有异常来源(`index` 已在校验阶段保证落在 `[0, bitmaps.length)`)。
**`parseRenderAnimation(buffer: ArrayBuffer): Promise<IAnimationParsedData | null>`(导出)**
1. `const data = new DataView(buffer);` → `const header = readHeader(data); if (!header) return null;`。
2. `const spriteCount = data.getUint32(ANIMATION_HEADER_SIZE, true);`;`spriteCount < 1` → `logger.error(86, \`sprite count ${spriteCount} is not allowed\`)`,`return null`;`spriteCount * 8 + 4 >= header.imageDataSize` → `logger.error(86, \`sprite table of ${spriteCount} sprites exceeds imageDataSize ${header.imageDataSize}\`)`,`return null`。
3. `const sprites = readSpriteDimensions(data, spriteCount); if (!sprites) return null;`,随后计算 `webpOffset` / `webpSize` / `metaOffset`(与 09-54 相同的表达式)。
4. `const meta = readRawMeta(buffer, metaOffset, header.metaDataSize); if (!meta) return null;`(`readRawMeta` 已把非对象 JSON 记成 88 并返回 `null`,所以这里的 `!meta` 只表示失败,不存在「合法但 falsy 的元数据」被静默跳过的情况);`if (!validateMeta(meta, spriteCount)) return null;`。
5. **唯一 `try {` 之二**(解码):先在 `try` 之前构造 `const webpBlob = new Blob([webpBytes], { type: 'image/webp' });`,再 `let image: ImageBitmap;` + `try { image = await createImageBitmap(webpBlob); } catch (error) { const reason = error instanceof Error ? error.message : String(error); logger.error(95, reason); return null; }`。`try` 块体内**只有** `image = await createImageBitmap(webpBlob);` 这一条语句,`new Blob(...)` 不得放进 `try`;因 `catch` 一定 `return null`,`try/catch` 之后 `image` 已确定赋值,不再需要 `if (!image) return null;`(避免出现未记录日志的空返回)。
6. `if (!validateBitmapBounds(meta.bitmaps, image)) return null;`(该函数内部已 `close()`)。
7. **唯一 `try {` 之三**(纹理):`let texture: Texture;` + `try { texture = new Texture(image); } catch (error) { const reason = error instanceof Error ? error.message : String(error); image.close(); logger.error(95, reason); return null; }`。`try` 块体内**只有** `texture = new Texture(image);` 这一条语句;同样依赖返回的 `catch` 完成确定赋值,删去 `if (!texture) return null;`(失败路径已在 `catch` 内记录 95 后返回)。
8. 帧转换与返回值与 09-54 完全一致:`{ texture, bitmaps, frames, blend: toBlendMode(meta.blend) }`。
**jsDoc(唯一被改写的既有注释,须 Task 0 逐字批准):**
改写前:
```
/**
* 将 v2 格式的动画二进制解析为动画数据。
* @param buffer 动画二进制数据
* @returns 解析后的动画数据,包含纹理、位图、帧与混合模式
* @throws 当数据结构、长度、索引或字段不合法,或图像解码失败时抛出错误
*/
```
改写后:
```
/**
* 将 v2 格式的动画二进制解析为动画数据。
* @param buffer 动画二进制数据
* @returns 解析后的动画数据,包含纹理、位图、帧与混合模式;任一步校验或解码失败时输出日志并返回 null
*/
```
## `parse.test.ts` 改写规格
**mock 声明顺序(必须在 `import ... from '../index'` 之前):**
- `const loggerMock = vi.hoisted(() => ({ error: vi.fn(), warn: vi.fn() }));`
- `const renderState = vi.hoisted(() => ({ failTexture: false }));`
- `vi.mock('@motajs/common', () => ({ logger: loggerMock }));`
- `vi.mock('@motajs/render', () => ({ Texture: renderMock.FakeTexture, MotaOffscreenCanvas2D: renderMock.FakeCanvas2D }));`(沿用 09-54 的 hoisted fake 类;`FakeTexture` 构造器在 `renderState.failTexture` 为 `true` 时抛错,用于触发 95 号纹理路径)。
- `import { AnimationBlendMode, IAnimationParsedData, parseRenderAnimation } from '../index';`
**`beforeEach`:** `loggerMock.error.mockClear(); loggerMock.warn.mockClear(); renderState.failTexture = false; mockBitmap(32, 32);`。`afterAll`:`vi.unstubAllGlobals();`。
**两个局部辅助(仅测试文件):**
- `async function parseOk(buffer: ArrayBuffer): Promise<IAnimationParsedData>`:断言 `not.toBeNull()`,再 `if (!data) throw new Error('parseRenderAnimation returned null');` 后返回非空结果(用于全部成功用例的类型收窄)。
- `async function expectFailure(buffer: ArrayBuffer, code: number): Promise<void>`:`expect(data).toBeNull(); expect(loggerMock.error).toHaveBeenCalledTimes(1); expect(loggerMock.error.mock.calls[0][0]).toBe(code);`。
**成功用例:** 09-54 的 11 个成功用例全部保留,只把 `await parseRenderAnimation(...)` 换成 `await parseOk(...)`,断言内容不变(解析结果、blend 映射、ratio 折入、无旋转 / 45°/多对象 / 空帧 / 镜像包围盒、音效保留、5 元组缺省、成功不关闭位图)。
**失败用例(每个子用例断言返回 null 与精确错误码):**
| 用例分组 | 覆盖码 |
|----------|--------|
| 头部:短缓冲 / 签名 / 版本 / 总长度 / imageDataSize<4 / metaDataSize=0 | 82 / 83 / 84 / 85 ×3 |
| sprite:count=0 / width=0 / height=0 / 尺寸表越界(`spriteCount` 调大到超出 `imageDataSize`) | 86 ×4 |
| 位图(逐分支覆盖 87):`bitmaps` 非数组 / 数量与 sprite 数不匹配 / 位图项非对象(`!isRecord(bitmap)`)/ `x` 非数字(NaN)/ `y` 非数字 / `width` 非数字 / `height` 非数字 / `x` 为负 / `y` 为负 / `width` 为 0 / `height` 为 0 / 解码后越界(`createImageBitmap` 返回 16×16 假位图、位图 32×32;断言 87 明细串含 `exceeds the decoded image 16 x 16`,且 `close` 被调用) | 87 ×12 |
| 元数据为 JSON 原语(`42` / `null` / `0` / `false` / `""`,全部由 `readRawMeta` 的 `!isRecord` 守卫捕获,断言 `null` + 88) | 88 ×5 |
| 帧结构(逐分支覆盖 88):`frame` 非数组 / 帧项非对象 / `objects` 非数组 / 对象项非数组(元组非数组)/ 元组 4 元 / 元组 8 元 / `sound` 非数组 | 88 ×7 |
| 对象索引:越界 / 非整数 | 89 ×2 |
| 对象字段:x NaN / y NaN / scale 0 / scale NaN / opacity 300 / opacity NaN / mirror NaN / rotate NaN | 90 ×8 |
| ratio:0 / -1 / NaN | 91 ×3 |
| blend:2 / -1 / NaN | 92 ×3 |
| 音效字段:`name` 空 / `name` 非字符串 / `volume` NaN / `pitch` NaN / 音效项非对象 | 93 ×5 |
| 元数据 JSON:`{` 之类的非法 JSON | 94 ×1 |
| 解码失败:`createImageBitmap` 抛错 | 95 ×1 |
| 纹理失败:`renderState.failTexture = true`(同时断言 `close` 被调用) | 95 ×1 |
**非法 JSON 构造:** 现有 `buildAnimation` 用 `JSON.stringify(meta)`,无法产出非法 JSON;新增 `function buildRawAnimation(rawMeta: string, sprites: ISprite[] = DEFAULT_SPRITES): ArrayBuffer`(与 `buildAnimation` 同一字节布局,只把元数据字节换成 `new TextEncoder().encode(rawMeta)`),供 94 号用。**同一函数也用于非对象元数据**:`buildRawAnimation('null')` / `buildRawAnimation('0')` / `buildRawAnimation('false')` / `buildRawAnimation('""')` / `buildRawAnimation('42')` 都能通过 `JSON.parse`,由 `readRawMeta` 的 `!isRecord` 守卫记 88 并返回 `null`。
**新增静态闸门用例(测试内):** 读取 `packages/render-anim/src/parse.ts`(`node:fs` 的 `readFileSync`),断言:`!/\bthrow\b/.test(source)`、`!/@throws/.test(source)`、恰好 3 处 `try {`、无 `finally`,且 `validateMeta` / `validateBitmapBounds` 体内无 `forEach`。该用例的注释需说明「解析器不得出现 throw,失败一律记录日志并返回 null」。
**测试注释规则:** 每个 `it` 前保留 / 新增一行中文单行注释说明覆盖内容(`dev.md` 强制)。测试文件不受「不得修改既有注释」约束,可整体重写。
## 覆盖审计(Multi-Source Coverage Audit)
| 源 | 条目 | 覆盖位置 |
|----|------|----------|
| GOAL(ROADMAP §Phase 9) | 「可在浏览器中运行并验证的最小版本」 | 解析失败不再中断渲染主流程,改为可判空的运行时行为 |
| REQ | 本阶段无 requirement ID(`requirements: []`) | Nyquist 不适用(可见跳过) |
| RESEARCH | 本 run 无 RESEARCH.md | 依据 `logger.ts` / `logger.json` / 现有调用点实测 |
| CONTEXT D-01 | 增量派发,一个任务一个计划 | 本计划即该派发的唯一计划 |
| CONTEXT D-02 | 计划可累积追加 | plan 55,排在 09-01..09-54 之后(编号说明见 frontmatter) |
| CONTEXT D-03 | 执行前必须先汇报并等待「可以执行」 | Task 0(`blocking-human`),`autonomous: false` |
| CONTEXT D-04 | 新命名必须先反馈获批 | 「命名与注释批准清单」+ Task 0;本计划不新增生产方法 / 字段 / 导出命名,仅报备函数内局部变量 |
| CONTEXT D-05 | 默认不逐阶段验证 | 仍做 targeted vitest / 静态门禁;不做浏览器 E2E |
| CONTEXT D-06 | 范围由用户界定 | `files_modified` 5 项 + Task 5 范围 / 哈希门禁 |
| 用户决定 1 | 解析失败返回 `null`,签名为 `Promise<IAnimationParsedData \| null>` | 「`parse.ts` 改写规格」+ Task 3 + Task 4 |
| 用户决定 2 | 追加 82–95 错误码,不使用 `1000+` | 「错误码映射」+ Task 2 + Task 5 码段门禁 |
| 用户决定 3 | 新增 `@motajs/common: workspace:*` | Task 2 + Task 5 哈希 / 内容门禁 |
| 用户决定 4 | 仅对 `JSON.parse` / `createImageBitmap` / `new Texture` 用 `try/catch`,返回 null | 「`parse.ts` 改写规格」第 5 / 7 步 + Task 3 静态门禁 |
| 用户决定 5 | `parse.ts` 无 `throw`,校验失败记录日志并返回 null | Task 3 / Task 4 静态闸门 |
| 用户要求 | 保留并发 `213` warn 改动 | Task 1 快照 + Task 2 / Task 5 深比较门禁 |
| 用户要求 | 只改 5 个路径、0 提交、不跑游戏 / 浏览器 | Task 1 基线 + Task 5 范围 / 哈希闸门 |
## 命名与注释批准清单(Task 0 逐项确认)
| 类别 | 名称 | 说明 |
|------|------|------|
| 公开签名(修改) | `parseRenderAnimation` | `(buffer: ArrayBuffer) => Promise<IAnimationParsedData \| null>` |
| 新增生产命名 | **无方法 / 字段 / 导出** | 内部函数 / 接口 / 常量全部沿用 09-54,不新增 |
| 生产局部变量(报备) | `webpBlob` / `imageWidth` / `imageHeight` / `reason` | 只存在于 `parse.ts` 函数体内(`reason` 仅用于 95 的 `error.message`),非方法 / 字段 / 导出 |
| 既有注释改写 | `parseRenderAnimation` 的 jsDoc | 删除 `@throws` 行、`@returns` 末尾追加「失败时输出日志并返回 null」;其余注释一律不动 |
| 日志表新增 | error `82`–`95` | 文本见「错误码映射」表 |
| 测试局部命名(报备) | `loggerMock` / `renderState` / `parseOk` / `expectFailure` / `buildRawAnimation` | 只存在于 `__test__/parse.test.ts` |
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/09-minimum-browser-runnable/09-CONTEXT.md
@AGENTS.md
@dev.md
@packages/render-anim/src/parse.ts
@packages/render-anim/src/__test__/parse.test.ts
@packages/render-anim/src/types.ts
@packages/render-anim/src/index.ts
@packages/render-anim/package.json
@packages/common/src/logger.ts
@packages/common/src/logger.json
@packages/common/src/index.ts
@.planning/phases/09-minimum-browser-runnable/09-54-PLAN.md
@.planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md
@vite.config.ts
@tsconfig.json
@.prettierrc
@eslint.config.js
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 预执行汇报关卡 —— 汇报可空签名、82–95 错误码、logger 依赖、try/catch 作用域、jsDoc 改动、测试与影响,等待恰好「可以执行」</name>
<precondition>`packages/render-anim/src/parse.ts` 仍是 09-54 的抛错实现(含 `throw new Error`,签名为 `Promise<IAnimationParsedData>`);`packages/common/src/logger.json` 的 error 段为 1..81 + 2001..2008,warn 段含并发新增的 `213`;`packages/render-anim/package.json` 只依赖 `@motajs/render`;`node_modules` 内 vitest / prettier / eslint / vue-tsc 均存在。</precondition>
<files>无(本任务只读,不写任何文件;汇报后停下等待「可以执行」)</files>
<read_first>
- `.planning/phases/09-minimum-browser-runnable/09-CONTEXT.md`(D-01 增量派发、D-03 汇报关卡、D-04 命名批准、D-06 范围界定)
- `AGENTS.md`(执行前须获批、既有注释不得擅自修改、最小修改也走 GSD、GSD 流程豁免范围)
- `dev.md`(CRLF、4 空格、首行 import、无类型专用导入、无必要 `any`、不建议 `try-catch`、「不建议」视为「不得」)
- `packages/render-anim/src/parse.ts`(09-54 的抛错实现,429 行 + 末尾换行 = 430 行;`readHeader` 有 6 处 `throw`,全文共 36 处)
- `packages/render-anim/src/__test__/parse.test.ts`(09-54 的 21 个用例)
- `packages/common/src/logger.ts`(`logger.error(code: number, ...params: string[])`、未命中码转调 16)
- `packages/common/src/logger.json`(error 1..81 + 2001..2008;warn 1..213 + 1001,其中 213 为并发未提交改动)
- `packages/render-anim/package.json`、`packages/render-anim/src/types.ts`、`packages/render-anim/src/index.ts`
- 本计划的「错误码映射」「`parse.ts` 改写规格」「`parse.test.ts` 改写规格」「命名与注释批准清单」四节
</read_first>
<what-built>
一份待批准的重构计划(`09-55-PLAN.md`):把 `@motajs/render-anim` 的 `parse.ts` 从「抛异常」改为「`logger.error` + 返回 null」,公开签名可空,新增 `@motajs/common` 依赖与 82–95 错误码,并重写测试以断言空返回与精确错误码。只改 5 个路径、0 提交。
</what-built>
<action>
**停下并向用户汇报,等待其恰好回复「可以执行」后才继续;本任务不写任何文件、不建目录、不派发执行子代理。**
① **要做什么 / 为什么:** 09-54 的 `parse.ts` 用 `throw new Error(...)` 表达全部失败路径,公开签名是 `Promise<IAnimationParsedData>`。动画文件是运行时数据,畸形输入应记录成带错误码的日志并由调用方判空,而不是把异常抛给上层;`packages/render-anim` 目前也没有 logger 依赖。本计划做这三件事:可空签名 + 统一 logger + 错误码表。
② **公开签名(用户决定 1):** `parseRenderAnimation(buffer: ArrayBuffer): Promise<IAnimationParsedData | null>`;成功返回解析数据,任一步失败 `return null`,调用方判空。
③ **错误码 82–95(用户决定 2):** `packages/common/src/logger.json` 的 `error` 段在 `"81"` 之后、`"2001"` 之前追加 14 条英文消息:82 缓冲过短、83 签名、84 版本、85 长度字段 / 总长度、86 sprite 数量 / 尺寸、87 位图数量 / 字段 / 越界、88 帧结构(非数组 / 非对象 / 元组 5–7)、89 对象索引、90 对象字段(x/y/scale/opacity/mirror/rotate)、91 ratio、92 blend、93 音效字段、94 元数据 JSON、95 解码 / 纹理。多检查项共用一码时用 `$1` 明细串(如 87 的 `bitmap 0 (x: 0, y: 0, width: 32, height: 32) exceeds the decoded image 16 x 16`)。**不使用 `1000+` 码段**,`warn` 段(含并发新增的 `213`)逐字保留。逐条文本见「错误码映射」表。
④ **依赖(用户决定 3):** `packages/render-anim/package.json` 新增 `"@motajs/common": "workspace:*"`,排在 `@motajs/render` 之前;不改其它字段。不跑 `pnpm install`、不更新锁文件;测试与类型检查靠 `vite.config.ts` / `tsconfig.json` 的 `@motajs/*` 路径映射解析到源码。
⑤ **`try/catch` 作用域(用户决定 4 + dev.md 例外说明):** 只允许 3 处,块体内分别**只有** `meta = JSON.parse(text);`(94)、`image = await createImageBitmap(webpBlob);`(95)、`texture = new Texture(image);`(95)这三个外部调用表达式;`new Blob(...)` 在 `try` 前构造,`!isRecord(meta)` 守卫与 `return meta` 在 `try` 后;不写 `finally`,不扩大作用域。这是对 `dev.md`「不建议写 `try-catch`」的显式例外:这三处是外部 API 的天然抛错点,畸形动画文件属于运行时数据条件而非应由用户修复的编程错误,用户已决定「记录日志后返回 null」。
⑥ **无 `throw`(用户决定 5):** `parse.ts` 全文不出现 `throw` / `@throws`;所有校验(头部、sprite、元数据、位图、帧对象、音效)一律先 `logger.error(code, ...)` 再 `return null`;解码后位图越界先在 `image.close()` 之前捕获 `image.width` / `image.height`,再 `close()`,再用捕获值记 87 并返回 `null`;`new Texture` 失败同样先 `close()` 再返回 `null`(95)。
⑦ **唯一被改写的注释:** `parseRenderAnimation` 的 jsDoc 删除 `@throws 当数据结构、长度、索引或字段不合法,或图像解码失败时抛出错误`,`@returns` 改为「解析后的动画数据,包含纹理、位图、帧与混合模式;任一步校验或解码失败时输出日志并返回 null」。其余既有 jsDoc / 注释一律不动(含 `validateBitmapBounds` 的「失败时释放纹理避免泄漏」)。本计划**不新增生产方法 / 字段 / 导出命名**,内部函数名沿用 09-54;函数内局部变量 `webpBlob` / `imageWidth` / `imageHeight` / `reason` 仅存在于 `parse.ts`(报备);测试文件新增局部名称 `loggerMock` / `renderState` / `parseOk` / `expectFailure` / `buildRawAnimation`(仅测试,报备)。
⑧ **测试与验证形态:** `parse.test.ts` 先 `vi.hoisted` + `vi.mock('@motajs/common')`(`logger.error` 为 `vi.fn()`)与 `vi.mock('@motajs/render')`,再导入 `../index`;成功用例全部保留(改为经 `parseOk` 收窄类型);失败用例逐条断言 `null` + `logger.error.mock.calls[0][0] === 期望码`,覆盖 82–95 全部码(含新增的非法 JSON 94、解码失败 95、纹理失败 95);另加一个读取 `parse.ts` 源码的静态用例,断言无 `throw` / `@throws`、恰 3 处 `try {`、无 `finally`。门禁为 targeted vitest、prettier `--check`、eslint、CRLF / BOM / 制表符与内容闸门,以及过滤 `packages/render-anim` 的 `vue-tsc --noEmit`。**不做浏览器 E2E,不跑游戏 / dev server / 真实 WebP 素材。**
⑨ **影响范围:** 只写 `packages/render-anim/src/parse.ts`、`packages/render-anim/src/__test__/parse.test.ts`、`packages/render-anim/package.json`、`packages/common/src/logger.json` 与 `09-55-SUMMARY.md`;不改 `types.ts` / `animater.ts` / `index.ts` / 其它包 / 根配置 / 锁文件 / 既有计划与摘要;不执行 git 写命令,**0 次提交**。
⑩ **等待批准:** 请确认以上内容后,回复恰好四个字「可以执行」。任何修改意见(尤其错误码文本、jsDoc 改法、`try/catch` 例外)请直接说明;未收到「可以执行」之前不开始 Task 1–5 的任何一步。
</action>
<verify>用户针对本计划恰好回复「可以执行」后才进入 Task 1–5;在此之前不执行 Task 1 / Task 2 / Task 3 / Task 4 / Task 5 的任何一步,也不派发执行子代理。</verify>
<fails_when>在用户回复「可以执行」之前执行了 Task 1–5 的任何一步、写入了任何文件,或派发了执行子代理;或汇报遗漏了 ①–⑩ 中任一项(签名、错误码表、依赖、`try/catch` 作用域、无 `throw`、jsDoc 改动、测试形态、范围、0 提交)。</fails_when>
<how-to-verify>
逐条核对 ①–⑩ 是否与你的意图一致,重点是:② 的可空签名;③ 的 82–95 码表与 `$1` 明细串(尤其 86 / 87 / 88 / 90 / 93 的多检查项共用一码)、不使用 `1000+`、`warn` 段 213 保留;④ 依赖只加 `@motajs/common` 且排在 `@motajs/render` 之前;⑤ `try/catch` 仅 3 处、块体内只有三个外部调用表达式与 dev.md 例外理由;⑥ 失败一律 `logger.error` + `return null`、越界在 `close()` 前捕获尺寸再记录 87;⑦ 唯一被改写的 jsDoc 文本;⑧ 测试与门禁口径(不做浏览器 E2E);⑨ 5 个写入路径与 0 提交。
</how-to-verify>
<resume-signal>请在确认本计划(尤其是 ③ 的错误码文本、⑤ 的 `try/catch` 例外、⑦ 的 jsDoc 改法)后,回复恰好四个字「可以执行」。任何修改意见请直接说明。</resume-signal>
<done>已完整汇报 ①–⑩(可空签名、82–95 错误码表与 `$1` 明细串、`@motajs/common` 依赖及其排序、`try/catch` 三处仅包裹外部调用表达式的作用域与 dev.md 例外理由、无 `throw` 与「close 前捕获尺寸再记 87」的资源关闭、jsDoc 唯一改动、测试与门禁形态、影响范围与 0 提交、等待批准),并收到用户针对本计划的「可以执行」回复。</done>
<acceptance_criteria>
- 已向用户逐条汇报 ①–⑩,包含完整 82–95 错误码表(不是只说「加 14 个错误码」)。
- 已明确说明 `try/catch` 只包裹 `meta = JSON.parse(text)` / `image = await createImageBitmap(webpBlob)` / `texture = new Texture(image)` 这三个调用表达式(`new Blob` 在 `try` 前、`!isRecord` 守卫与 `return meta` 在 `try` 后),并说明这是 dev.md「不建议 `try-catch`」的显式例外及理由。
- 已明确说明 `parseRenderAnimation` 的 jsDoc 是本计划唯一被改写的既有注释,并给出改前 / 改后文本。
- 已明确说明 `logger.error` 的 `...params: string[]` 约束(数字需 `.toString()` / 模板字符串)。
- 已明确说明 `warn` 段(含并发 `213`)逐字保留、不使用 `1000+` 码段。
- 已明确说明影响范围(5 个写入路径、`types.ts` / `animater.ts` / `index.ts` 只验证、不跑 `pnpm install`、0 提交)与测试 / 门禁形态。
- 用户针对本计划明确回复「可以执行」后才进入 Task 1–5;在此之前未执行任何任务、未派发执行子代理。
</acceptance_criteria>
</task>
<task type="auto">
<name>Task 1: 读取当前实现与 logger 契约,采集状态 / 哈希 / logger 快照基线(只读,临时文件仅写 TEMP)</name>
<files>无(本任务只读仓库文件;只在 `process.env.TEMP` 目录写基线临时文件,不写仓库内任何文件)</files>
<read_first>
- `AGENTS.md`、`dev.md`(执行前获批、既有注释不得擅自修改、CRLF、4 空格、首行 import、无类型专用导入、无必要 `any`、不建议 `try-catch`)
- `packages/render-anim/src/parse.ts`(当前 429 行 + 末尾换行 = 430 行抛错实现:`readHeader` / `readSpriteDimensions` / `readRawMeta` / `validateMeta` / `validateBitmapBounds` / `toObject` / `toFrame` / `computeFrameBox` / `toBlendMode` / `parseRenderAnimation`)
- `packages/render-anim/src/__test__/parse.test.ts`(当前 21 个用例,失败用例用 `rejects.toThrow`)
- `packages/common/src/logger.ts`(`Logger.error(code: number, ...params: string[])`、未命中码转调 `logger.error(16, ...)`、顶层 DOM 探测条件)
- `packages/common/src/logger.json`(error `1..81` + `2001..2008`;warn `1..213` + `1001`,`213` 为并发未提交改动)
- `packages/render-anim/package.json`、`packages/render-anim/src/index.ts`、`packages/render-anim/src/types.ts`、`packages/render-anim/src/animater.ts`
- `vite.config.ts`(`@motajs/*` → `packages/*/src` 别名)、`tsconfig.json`(`paths` 同名映射)
- 本计划的「错误码映射」「`parse.ts` 改写规格」「`parse.test.ts` 改写规格」
</read_first>
<action>
仅在收到用户恰好回复「可以执行」之后执行。本任务不写仓库内文件,只读取并记录。
1. 读取并记录:`logger.error` 的签名是 `(code: number, ...params: string[])`,所有数字实参必须字符串化;`logger.warn` 同理。`logger.ts` 顶层 DOM 探测以 `typeof document !== 'undefined' && typeof main !== 'undefined'` 为条件,Node 下安全。
2. 记录 `parse.ts` 现状(逐函数,合计 36 处 `throw`):`readHeader` 6 处(第 114 / 117 / 120 / 125 / 128 / 134 行)、`readSpriteDimensions` 1 处(第 150 行)、`readRawMeta` 0 处(`JSON.parse` 直接抛)、`validateMeta` 26 处(第 172–263 行;其中第 188 行起位于 `forEach` 回调内)、`validateBitmapBounds` 1 处(第 285 行,先 `image.close()` 再抛)、`parseRenderAnimation` 2 处(第 399 / 402 行:sprite 数量、尺寸表越界);公开签名 `Promise<IAnimationParsedData>`。记录**全部** `throw new Error('…')` 的消息文本,供 Task 3 建立「旧消息 → 新错误码」对照,防止漏改或改错码。
3. 记录 `parse.test.ts` 现状:21 个用例(11 成功 + 10 失败组),失败组用 `rejects.toThrow(...)`;`renderMock` 用 `vi.hoisted` 提供 `FakeTexture` / `FakeCanvas2D`;`buildAnimation(meta, sprites)` 用 `JSON.stringify` 拼字节。
4. 采集**范围基线**:用 `node` 把当前 `git status --porcelain -uall` 完整输出(先统一为 LF)写入 `(process.env.TEMP||'.') + '/gsd-09-55-status.txt'`(UTF-8 无 BOM),回显绝对路径;写入后立刻断言与当前输出完全一致(见 `<verify>` 第 1 条)。基线必须包含 `?? packages/render-anim/src/parse.ts`、`?? packages/render-anim/src/__test__/parse.test.ts`、` M packages/common/src/logger.json`、`?? .planning/phases/09-minimum-browser-runnable/09-55-PLAN.md` 这四条。
5. 采集**哈希基线**:对以下 10 个路径逐个 `git hash-object`,把「无空格路径 + 空格 + 40 位哈希」写入 `(process.env.TEMP||'.') + '/gsd-09-55-hashes.txt'`(UTF-8 无 BOM):`packages/render-anim/src/parse.ts`、`packages/render-anim/src/__test__/parse.test.ts`、`packages/render-anim/package.json`、`packages/render-anim/src/types.ts`、`packages/render-anim/src/index.ts`、`packages/render-anim/src/animater.ts`、`packages/common/src/logger.json`、`.planning/phases/09-minimum-browser-runnable/09-54-PLAN.md`、`.planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md`、`.planning/phases/09-minimum-browser-runnable/09-55-PLAN.md`。
6. 采集 **logger 快照基线**:把 `packages/common/src/logger.json` 原文复制为 `(process.env.TEMP||'.') + '/gsd-09-55-logger-baseline.json'`(UTF-8 无 BOM;仅复制,不解析重排)。该快照用于 Task 5 证明「error 既有码与 warn 全段(含 213)逐字未变」。
7. 断言现状(任一不符,停下上报,不得继续 Task 2):
- `parse.ts` 含 `throw new Error`,且含 `Promise<IAnimationParsedData>`(无可空);含 `@throws`。
- `parse.test.ts` 含 `rejects.toThrow`。
- `logger.json` 的 `error['82']` 不存在、`error['81']` 与 `error['2001']` 存在、`warn['213']` 为非空字符串。
- `packages/render-anim/package.json` **不含** `@motajs/common`。
- `packages/render-anim/src/types.ts` / `animater.ts` / `index.ts` 存在且未被本任务改动。
8. 记录工具链事实:`node --version`;`node_modules/vitest/vitest.mjs`、`prettier/bin/prettier.cjs`、`eslint/bin/eslint.js`、`vue-tsc/bin/vue-tsc.js` 均存在;并记录 `node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts` 的基线结果(规划日为 21 passed;browserslist 的 stderr 提示属正常,按退出码判定)。
</action>
<verify>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const p=(process.env.TEMP||'.')+'/gsd-09-55-status.txt';const base=fs.readFileSync(p,'utf8').replace(/\r\n/g,'\n').trim();const now=execSync('git status --porcelain -uall',{encoding:'utf8'}).replace(/\r\n/g,'\n').trim();if(base!==now){console.error('baseline drift');process.exit(1);}console.log('OK: status baseline matches current tree');"</automated>
<fails_when>基线文件与当前 `git status --porcelain -uall` 不一致(打印 `baseline drift`,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const s=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-55-hashes.txt','utf8').replace(/\r\n/g,'\n').trim().split('\n').filter(Boolean);const ok=s.length===10&&s.every(l=>{const a=l.split(' ');return a.length===2&&a[1].length===40&&!/[^0-9a-f]/.test(a[1]);});if(!ok){console.error(s.join('\n'));process.exit(1);}console.log('OK: 10 hash baselines');"</automated>
<fails_when>哈希基线不是 10 行,或任一行不是「无空格路径 + 40 位小写十六进制」(打印内容,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const p=(process.env.TEMP||'.')+'/gsd-09-55-logger-baseline.json';const j=JSON.parse(fs.readFileSync(p,'utf8'));const fail=[];if(!j.error||!j.warn){fail.push('missing error/warn section');}if(j.error){if(j.error['81']===undefined)fail.push('error 81 missing');if(j.error['82']!==undefined)fail.push('error 82 already exists');if(j.error['2001']===undefined||j.error['2008']===undefined)fail.push('system error codes missing');}if(j.warn){if(typeof j.warn['213']!=='string'||j.warn['213'].length<10)fail.push('warn 213 missing or empty');if(j.warn['1001']===undefined)fail.push('warn 1001 missing');}if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: logger snapshot keeps error 1..81 + 2001..2008 and warn 213 / 1001');"</automated>
<fails_when>快照缺少 error 81 / 2001 / 2008、已含 error 82、或缺少 warn 213 / 1001(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const p=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const t=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8');const pkg=fs.readFileSync('packages/render-anim/package.json','utf8');const fail=[];const throws=(p.match(/\bthrow\b/g)||[]).length;if(!/\bthrow new Error\(/.test(p))fail.push('parse.ts no longer throws');if(throws!==36)fail.push('parse.ts has '+throws+' throw occurrences, expected 36');if(p.indexOf('Promise<IAnimationParsedData>')===-1)fail.push('parse.ts signature not the old one');if(p.indexOf('@throws')===-1)fail.push('parse.ts jsDoc has no @throws');if(t.indexOf('rejects.toThrow')===-1)fail.push('test no longer uses rejects.toThrow');if(pkg.indexOf('@motajs/common')!==-1)fail.push('package.json already depends on @motajs/common');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: pre-change state matches assumptions');"</automated>
<fails_when>`parse.ts` 已无 `throw new Error`、`throw` 总数不是 36、签名已是可空、已无 `@throws`、测试已不用 `rejects.toThrow`,或 `package.json` 已含 `@motajs/common`(打印原因,退出码 1)——说明状态与计划不符,须停下上报。</fails_when>
<automated>node -e "const fs=require('fs');const need=['packages/render-anim/src/types.ts','packages/render-anim/src/animater.ts','packages/render-anim/src/index.ts','node_modules/vitest/vitest.mjs','node_modules/prettier/bin/prettier.cjs','node_modules/eslint/bin/eslint.js','node_modules/vue-tsc/bin/vue-tsc.js'];const miss=need.filter(f=>!fs.existsSync(f));if(miss.length){console.error('missing: '+miss.join(', '));process.exit(1);}console.log('OK: files and toolchain present');"</automated>
<fails_when>只读参考文件或工具链缺失(打印缺失列表,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- 已读取并记录 `logger.error` 的字符串参数约束、`logger.ts` 的 Node 安全性、`parse.ts` 全部 36 处 `throw`(`readHeader` 6 处)及其消息与所在函数、`parse.test.ts` 的 21 个用例结构。
- `(process.env.TEMP||'.')/gsd-09-55-status.txt` 已生成,且 Task 1 结束时与当前 `git status --porcelain -uall` 完全一致;基线包含本计划的 4 个关键条目。
- `(process.env.TEMP||'.')/gsd-09-55-hashes.txt` 恰有 10 行,覆盖 4 个待改文件、3 个只验证文件、09-54 计划 / 摘要与 `09-55-PLAN.md`。
- `(process.env.TEMP||'.')/gsd-09-55-logger-baseline.json` 已原样复制,含 error `1..81` + `2001..2008` 且不含 `82`,含 warn `213` 与 `1001`。
- 已确认改动前状态(`parse.ts` 抛错、测试用 `rejects.toThrow`、`package.json` 无 `@motajs/common`)与工具链基线;任一不符已停下上报。
</acceptance_criteria>
<done>已记录 `logger` 契约与现状、`parse.ts` 全部抛错点与消息、测试结构;`process.env.TEMP` 下的状态基线、10 行哈希基线、logger 快照基线均已生成并通过门禁;已确认改动前状态与计划假设一致,或已停下上报差异。</done>
</task>
<task type="auto">
<name>Task 2: 追加 error 82–95 到 `logger.json`(保留 warn 段含 213)并新增 `@motajs/common` 依赖</name>
<files>packages/common/src/logger.json, packages/render-anim/package.json</files>
<read_first>
- 本计划的「错误码映射」表(消息文本与 `$1` 明细串的唯一依据)
- `packages/common/src/logger.json`(当前 error 段结尾 `"81"` 后紧跟 `"2001"`;warn 段含并发新增 `"213"`)
- `packages/render-anim/package.json`(当前仅 `name` + `@motajs/render`)
- `packages/common/src/logger.ts`(`parseInfo` 把 `$n` 替换为参数;未命中码转调 16)
- `dev.md`(CRLF、4 空格、JSON 不得引入注释)
</read_first>
<action>
仅在 Task 1 完成且收到「可以执行」之后执行。本任务只改这两个文件。
1. `packages/common/src/logger.json`:在 `error` 段的 `"81": "..."` 行之后、`"2001"` 行之前,按 82→95 顺序插入 14 条,文本严格使用「错误码映射」表,缩进 8 个空格、键值行尾逗号与现有风格一致。不得改动 `warn` 段的任何一行(尤其是 `"213"` 与 `"1001"`),不得改动 error 段既有 `1..81` / `2001..2008`。
2. `$n` 占位符与 `parse.ts` 的实参数目必须一一对应:82 两个、83 两个、84 两个、85 三个、86 一个(明细串)、87 一个(明细串)、88 一个(明细串)、89 三个、90 一个(明细串)、91 一个、92 一个、93 一个(明细串)、94 一个、95 一个。消息中不得出现未使用的 `$n`,也不得出现超出实参数目的占位。
3. `packages/render-anim/package.json`:在 `dependencies` 中新增 `"@motajs/common": "workspace:*"`,排在 `"@motajs/render"` 之前;保持 4 空格缩进与 CRLF;不改 `name` 或其它字段。不运行 `pnpm install`,不修改 `pnpm-lock.yaml`。
4. 只做上述两处编辑;不碰 `parse.ts` / 测试 / SUMMARY / 其它包或配置。
</action>
<verify>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const fail=[];for(let c=82;c<=95;c++){if(typeof j.error[c]!=='string'||j.error[c].length<10)fail.push('missing or short error '+c);}if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: error 82..95 present');console.log(Object.keys(j.error).filter(k=>+k>=82&&+k<=95).join(','));"</automated>
<fails_when>`logger.json` 不是合法 JSON,或 82–95 中任一码缺失 / 为空 / 过短(打印缺失列表,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const p=(process.env.TEMP||'.')+'/gsd-09-55-logger-baseline.json';const base=JSON.parse(fs.readFileSync(p,'utf8'));const fail=[];Object.keys(base.error).forEach(k=>{if(j.error[k]!==base.error[k])fail.push('error '+k+' changed');});if(JSON.stringify(j.warn)!==JSON.stringify(base.warn))fail.push('warn section changed');Object.keys(j.error).forEach(k=>{if(base.error[k]===undefined&&(+k<82||+k>95))fail.push('unexpected new error code '+k);});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: existing error codes and whole warn section unchanged; only 82..95 added');"</automated>
<fails_when>既有 error 码被改动、`warn` 段(含 213)任一字符变化,或在 82–95 之外新增 / 删除错误码(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const counts={82:2,83:2,84:2,85:3,86:1,87:1,88:1,89:3,90:1,91:1,92:1,93:1,94:1,95:1};const D=String.fromCharCode(36);const re=new RegExp('['+D+'][0-9]+','g');const fail=[];Object.keys(counts).forEach(k=>{const msg=j.error[k]||'';const used=new Set();(msg.match(re)||[]).forEach(m=>used.add(+m.slice(1)));const nums=[...used].sort((a,b)=>a-b);const max=nums.length?nums[nums.length-1]:0;if(nums.length!==counts[k]||max!==counts[k])fail.push('code '+k+' uses '+nums.length+' params (max '+max+'), expected '+counts[k]);});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: placeholder counts match the parser call sites');"</automated>
<fails_when>任一错误码的 `$n` 占位数量与「错误码映射」表不符(打印实际与期望,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const BT=String.fromCharCode(96);const plan=fs.readFileSync('.planning/phases/09-minimum-browser-runnable/09-55-PLAN.md','utf8').replace(/\r\n/g,'\n');const log=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const digits=s=>s.length>0&&s.split('').every(ch=>ch>='0'&&ch<='9');const rows=plan.split('\n').map(l=>l.trim()).filter(l=>l.indexOf('|')===0).map(l=>l.split('|').map(s=>s.trim()));const expected={};rows.forEach(c=>{if(c.length!==5||!digits(c[1]))return;const n=+c[1];if(n<82||n>95)return;const cell=c[3];if(cell.length>2&&cell.slice(0,1)===BT&&cell.slice(-1)===BT)expected[n]=cell.slice(1,-1);});const fail=[];for(let n=82;n<=95;n++){if(!expected[n])fail.push('plan table row missing for '+n);else if(log.error[n]!==expected[n])fail.push('message mismatch for '+n+' (json='+JSON.stringify(log.error[n])+' plan='+JSON.stringify(expected[n])+')');}if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: logger.json error 82..95 messages match the plan mapping table verbatim');"</automated>
<fails_when>`logger.json` 的任一 82–95 消息与「错误码映射」表不是逐字一致(含标点、空格与 `$n`),或计划表格行缺失(打印差异,退出码 1)——只比对占位数量不够,必须比对整段文本。</fails_when>
<automated>node -e "const fs=require('fs');const pkg=JSON.parse(fs.readFileSync('packages/render-anim/package.json','utf8'));const d=pkg.dependencies||{};const keys=Object.keys(d);const iCommon=keys.indexOf('@motajs/common');const iRender=keys.indexOf('@motajs/render');const fail=[];if(d['@motajs/common']!=='workspace:*')fail.push('@motajs/common workspace dep missing');if(d['@motajs/render']!=='workspace:*')fail.push('@motajs/render dep changed');if(keys.length!==2)fail.push('dependencies has '+keys.length+' keys, expected 2');if(iCommon===-1||iRender===-1||iCommon>=iRender)fail.push('@motajs/common must appear before @motajs/render in dependencies (order: '+keys.join(',')+')');if(pkg.name!=='@motajs/render-anim')fail.push('package name changed');if(Object.keys(pkg).length!==2)fail.push('unexpected top-level fields');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: @motajs/common declared before @motajs/render, both workspace:*');"</automated>
<fails_when>`package.json` 缺少 `@motajs/common: workspace:*`、`@motajs/render` 被改、`@motajs/common` 未排在 `@motajs/render` 之前(键序断言)、包名变化或多出顶层字段(打印原因,退出码 1)。</fails_when>
<automated>node node_modules/prettier/bin/prettier.cjs --check packages/common/src/logger.json packages/render-anim/package.json</automated>
<fails_when>prettier 报告任一文件待格式化,或退出码非 0。</fails_when>
<automated>node -e "const fs=require('fs');const files=['packages/common/src/logger.json','packages/render-anim/package.json'];const fail=[];files.forEach(f=>{const b=fs.readFileSync(f);const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;if(lf!==crlf||tabs||bom)fail.push(f+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: CRLF, no tabs, no BOM');"</automated>
<fails_when>任一文件出现非 CRLF 换行、制表符或 BOM(打印实际值,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- `logger.json` 的 `error` 段在 82–95 之间恰有 14 条英文消息,文本与「错误码映射」表**逐字一致**(Task 2 门禁直接解析计划表格做全文本比对,不只是占位数量);`$n` 数量与对应调用点实参一致。
- `warn` 段与 Task 1 快照深比较完全一致(含并发新增的 `213`),既有 `1..81` / `2001..2008` 未被修改。
- 未在 82–95 之外新增或删除任何错误码;未使用 `1000+` 码段。
- `packages/render-anim/package.json` 恰含 `name` 与 `dependencies`(`@motajs/common`、`@motajs/render` 均为 `workspace:*`,且 `@motajs/common` 的键序在 `@motajs/render` 之前),prettier 与 CRLF / BOM 门禁通过。
</acceptance_criteria>
<done>`logger.json` 已按 82–95 顺序追加 14 条英文错误消息,`$n` 与调用点对齐,`warn` 段(含 213)与既有 error 码逐字未变;`packages/render-anim/package.json` 已新增 `@motajs/common: workspace:*`;prettier、CRLF / BOM / 缩进门禁通过。</done>
</task>
<task type="auto">
<name>Task 3: 改写 `parse.ts` —— 移除全部 throw,改为 `logger.error` + 返回 null,签名可空,3 处最小 `try/catch`</name>
<files>packages/render-anim/src/parse.ts</files>
<read_first>
- 本计划的「错误码映射」「`parse.ts` 改写规格」(唯一内容依据)
- `packages/render-anim/src/parse.ts`(当前抛错实现,逐函数对照改写)
- `packages/render-anim/src/types.ts`(`IAnimationParsedData` / `IAnimationFrame` / `IAnimationObject` / `IAnimationBitmap` / `IAnimationSound` / `AnimationBlendMode`)
- `packages/common/src/logger.ts`(`logger.error(code: number, ...params: string[])`)
- `packages/common/src/logger.json`(Task 2 新增的 82–95 文本,确认占位与实参一致)
- `dev.md`(CRLF、4 空格、首行 import、无类型专用导入、无必要 `any`、对象类型单独 `interface`、无副作用模块)
</read_first>
<action>
仅在 Task 2 完成且收到「可以执行」之后执行。本任务只改 `packages/render-anim/src/parse.ts`。
1. 在第 1 行新增 `import { logger } from '@motajs/common';`,保留现有 `./types` 与 `@motajs/render` 两行顺序;import 连续、中间不夹注释或空行。
2. 按「`parse.ts` 改写规格」逐函数改写:
- `readHeader` → 返回 `IAnimationHeader | null`,82 / 83 / 84 / 85。
- `readSpriteDimensions` → 返回 `ISpriteDimension[] | null`,86。
- `readRawMeta` → 返回 `IRawAnimationMeta | null`;`try { meta = JSON.parse(text); } catch { logger.error(94, 'metadata is not valid JSON'); return null; }` 只包裹 `JSON.parse`(94,脱敏常量、不读 `error.message`);`try` 之后立即 `if (!isRecord(meta))` → `logger.error(88, 'metadata is not an object')` + `return null`,拒绝 `null` / `0` / `false` / `""` / `42` 等非对象 JSON,再 `return meta`。
- `validateMeta` → 返回 `boolean`,88 / 91 / 92 / 87 / 89 / 90 / 93,全部先 `logger.error` 再 `return false`;**必须用可提前退出的 `for` 循环,禁止 `forEach`**。
- `validateBitmapBounds` → 返回 `boolean`,用可提前退出的 `for` 循环(禁止 `forEach`);进入函数先捕获 `const imageWidth = image.width; const imageHeight = image.height;`,越界时先 `image.close()`,再用捕获的 `imageWidth` / `imageHeight` 记录 87、`return false`(日志不得在 `close()` 后读 `image.width` / `image.height`)。
- `parseRenderAnimation` → 签名改 `Promise<IAnimationParsedData | null>`;用 `if (!header) return null;` / `if (!sprites) return null;` / `if (!meta) return null;` / `if (!validateMeta(...)) return null;` / `if (!validateBitmapBounds(...)) return null;` 串联;`new Blob(...)` 在 `try` 前构造,解码与 `new Texture` 各包一层 `try/catch`(95,块体内只有对应调用表达式),纹理失败时先 `image.close()`。
3. 删除 `parse.ts` 中所有 `throw` 与 `@throws`;按 Task 0 批准文本改写 `parseRenderAnimation` 的 jsDoc(其余注释一律不动)。不得把 `throw` 写进注释、jsDoc 或日志消息。
4. 保持 `toObject` / `toFrame` / `computeFrameBox` / `toBlendMode` 逻辑与签名不变;保持 `//#region` 分区不变;不在函数内定义局部函数;不新增生产方法 / 字段 / 导出命名(`webpBlob` / `imageWidth` / `imageHeight` / `reason` 仅为函数内局部变量,已报备)。
5. 数字实参一律 `.toString()` 或走模板字符串,不传裸 number;catch 变量用 `unknown` 语义,不写 `any` / `as`:94 用无绑定 `catch {` 并输出脱敏常量(**不读 `error.message`**),95 用 `error instanceof Error ? error.message : String(error)`。
</action>
<verify>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const fail=[];if(/\bthrow\b/.test(t))fail.push('throw present');if(/@throws/.test(t))fail.push('@throws present');const tries=(t.match(/try\s*\{/g)||[]).length;if(tries!==3)fail.push('try blocks = '+tries+', expected 3');if(/\bfinally\b/.test(t))fail.push('finally present');if(t.indexOf('Promise<IAnimationParsedData | null>')===-1)fail.push('nullable signature missing');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: no throw, 3 try blocks, nullable signature');"</automated>
<fails_when>`parse.ts` 仍出现 `throw` / `@throws` / `finally`、`try {` 数量不是 3,或签名不是 `Promise<IAnimationParsedData | null>`(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const norm=s=>s.replace(/\s+/g,'');const bodies=[];let i=0;while((i=t.indexOf('try {',i))!==-1){const s=i+5;const e=t.indexOf('}',s);if(e<0)break;bodies.push(norm(t.slice(s,e)));i=s;}const want=['meta=JSON.parse(text);','image=awaitcreateImageBitmap(webpBlob);','texture=newTexture(image);'];const fail=[];if(bodies.length!==3)fail.push('try bodies = '+bodies.length+', expected 3');else want.forEach((w,k)=>{if(bodies[k]!==w)fail.push('try#'+(k+1)+' body is '+JSON.stringify(bodies[k])+', expected '+JSON.stringify(w));});if(!/const\s+webpBlob\s*=\s*new\s+Blob\(\[webpBytes\],\s*\{\s*type:\s*'image\/webp'\s*\}\);/.test(t))fail.push('new Blob is not constructed outside try');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 3 try blocks wrap only JSON.parse / createImageBitmap / new Texture');"</automated>
<fails_when>3 处 `try` 块体不是恰好 `meta = JSON.parse(text);` / `image = await createImageBitmap(webpBlob);` / `texture = new Texture(image);`,或 `new Blob(...)` 没有在 `try` 之前构造(打印实际块体与期望,退出码 1)——`try` 只允许包裹外部调用表达式本身。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const seg=t.slice(t.indexOf('function validateBitmapBounds'),t.indexOf('export async function parseRenderAnimation'));const norm=s=>s.replace(/\s+/g,'');const close=seg.indexOf('image.close()');const fail=[];if(close<0)fail.push('image.close() not found');else{const before=norm(seg.slice(0,close));const after=seg.slice(close);if(before.indexOf('imageWidth=image.width')===-1)fail.push('imageWidth not captured before close');if(before.indexOf('imageHeight=image.height')===-1)fail.push('imageHeight not captured before close');if(after.indexOf('logger.error(87')===-1)fail.push('87 log not emitted after close');if(/image\.(width|height)/.test(after))fail.push('87 log reads image dimensions after close');}if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 87 log uses dimensions captured before image.close()');"</automated>
<fails_when>`validateBitmapBounds` 未在 `image.close()` 之前捕获 `imageWidth` / `imageHeight`,或 87 日志在 `close()` 之后读取 `image.width` / `image.height`(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const codes=[];for(let c=82;c<=95;c++){codes.push(c);}const s=t.replace(/\s+/g,'');const miss=codes.filter(c=>s.indexOf('logger.error('+c+',')===-1);if(miss.length){console.error('missing logger.error for: '+miss.join(','));process.exit(1);}console.log('OK: all 82..95 error codes referenced');"</automated>
<fails_when>82–95 中任一错误码未在 `parse.ts` 的 `logger.error` 调用点出现(打印缺失列表,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const seg=(a,b)=>{const i=t.indexOf(a);if(i<0)return '';const j=t.indexOf(b,i+1);return j<0?'':t.slice(i,j);};const parts=[['validateMeta',seg('function validateMeta','function validateBitmapBounds')],['validateBitmapBounds',seg('function validateBitmapBounds','export async function parseRenderAnimation')]];const fail=[];parts.forEach(p=>{const name=p[0],body=p[1];if(!body){fail.push(name+' body not found');return;}if(/\bforEach\b/.test(body))fail.push(name+' uses forEach (must be an early-exit loop)');if(body.indexOf('return false')===-1)fail.push(name+' has no return false');if(!/\bfor\s*\(/.test(body))fail.push(name+' has no for loop');});const raw=t.slice(t.indexOf('function readRawMeta'),t.indexOf('function validateMeta')).replace(/\s+/g,'');if(raw.indexOf('isRecord')===-1)fail.push('readRawMeta does not reject non-object JSON');if(raw.indexOf('logger.error(88,')===-1)fail.push('readRawMeta does not log 88');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: readRawMeta rejects non-object JSON (88); validators use early-exit for loops and return false');"</automated>
<fails_when>`readRawMeta` 未用 `isRecord` 拒绝非对象 JSON / 未记录 88;或 `validateMeta` / `validateBitmapBounds` 体内出现 `forEach`、缺少 `return false`、缺少 `for` 循环(打印原因,退出码 1)——`forEach` 里的 `return false` 不会结束整个函数,必须改成可提前退出的循环。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const raw=t.slice(t.indexOf('function readRawMeta'),t.indexOf('function validateMeta'));const fail=[];if(raw.indexOf('metadata is not valid JSON')===-1)fail.push('94 reason is not the sanitized constant');if(raw.indexOf('error.message')!==-1)fail.push('94 reads error.message (may echo metadata content)');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 94 logs the sanitized reason only');"</automated>
<fails_when>`readRawMeta` 的 94 日志不是固定脱敏串 `metadata is not valid JSON`,或读取了 `error.message`(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const need=['import { logger } from '+String.fromCharCode(39)+'@motajs/common'+String.fromCharCode(39)+';','createImageBitmap','new Texture','image.close()','readHeader','readSpriteDimensions','readRawMeta','validateMeta','validateBitmapBounds','toFrame','toObject','computeFrameBox','toBlendMode'];const miss=need.filter(n=>t.indexOf(n)===-1);if(miss.length){console.error('missing: '+miss.join(', '));process.exit(1);}console.log('OK: imports, external calls and internal names present');"</automated>
<fails_when>缺少 logger 导入、任一外部调用 / `image.close()`、或内部函数名被意外改名(打印缺失列表,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8').replace(/\r\n/g,'\n');const hits=[];if(/^\s*import\s+type\b/m.test(t))hits.push('import type');if(/:\s*any\b|<any>/.test(t))hits.push('any');if(/export default/.test(t))hits.push('export default');if(/\bBuffer\b/.test(t))hits.push('Buffer');if(/require\s*\(/.test(t))hits.push('require(');if(/node:/.test(t))hits.push('node:');const top=t.split('\n').filter(l=>/^(let|var)\s/.test(l)||/^export\s+(const|let|var)\s/.test(l));const first=t.split('\n')[0]||'';const fail=[];if(hits.length)fail.push('forbidden: '+hits.join(', '));if(top.length)fail.push('top-level variable: '+top.join(' | '));if(!/^import\b/.test(first))fail.push('first line is not an import');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: module rules respected');"</automated>
<fails_when>出现类型专用导入、`any`、`export default`、Node 依赖、顶层变量声明,或首行不是普通 `import`(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const ex=t.split('\n').filter(l=>/^export\s/.test(l));const ok=ex.length===1&&ex[0].indexOf('export async function parseRenderAnimation')===0;if(!ok){console.error(ex.join('\n'));process.exit(1);}console.log('OK: exports only parseRenderAnimation');"</automated>
<fails_when>`parse.ts` 的 `export` 行不是恰好一条 `export async function parseRenderAnimation...`(打印实际行,退出码 1)。</fails_when>
<automated>node node_modules/prettier/bin/prettier.cjs --check packages/render-anim/src/parse.ts</automated>
<fails_when>prettier 报告该文件待格式化,或退出码非 0。</fails_when>
<automated>node node_modules/eslint/bin/eslint.js packages/render-anim/src/parse.ts</automated>
<fails_when>eslint 打印任一 error / warning,或退出码非 0。</fails_when>
<automated>node -e "const fs=require('fs');const b=fs.readFileSync('packages/render-anim/src/parse.ts');const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;const ok=lf===crlf&&tabs===0&&!bom;console.log((ok?'OK':'FAIL')+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);process.exit(ok?0:1);"</automated>
<fails_when>出现非 CRLF 换行、制表符或 BOM(打印 `FAIL`,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- `parse.ts` 全文无 `throw` / `@throws` / `finally`;失败路径一律 `logger.error(code, ...)` 后 `return null` / `return false`。
- `readRawMeta` 在 `try/catch` 之后用 `!isRecord(meta)` 拒绝非对象 JSON(`42` / `null` / `0` / `false` / `""` 等)并记录 88;`parseRenderAnimation` 的 `if (!meta) return null;` 只表示失败。
- `validateMeta` 与 `validateBitmapBounds` 使用可提前退出的 `for` 循环,体内无 `forEach`;每次失败只记录一次并立即 `return false`。
- `export async function parseRenderAnimation(buffer: ArrayBuffer): Promise<IAnimationParsedData | null>`;`parseRenderAnimation` 是本文件唯一导出。
- 恰有 3 处 `try {`,块体内分别只有 `meta = JSON.parse(text)`、`image = await createImageBitmap(webpBlob)`、`texture = new Texture(image)`;`new Blob(...)` 在 `try` 前构造,`!isRecord` 守卫与 `return meta` 在 `try` 后;解码后位图越界时先用 `close()` 前捕获的 `imageWidth` / `imageHeight` 记录 87,再 `image.close()`;纹理创建失败先 `image.close()` 再记 95。
- 82–95 全部在 `logger.error` 调用点出现;实参与 `$n` 数量一致;数字实参已字符串化;94 输出脱敏常量 `metadata is not valid JSON`,不传 `error.message`。
- 第 1 行为 `import { logger } from '@motajs/common';`;模块规则(无类型专用导入 / 无 `any` / 无顶层变量 / 无 Node 依赖)与 prettier / eslint / CRLF / BOM 门禁通过。
- 除 Task 0 批准的 `parseRenderAnimation` jsDoc 外,未改动任何既有注释。
</acceptance_criteria>
<done>`parse.ts` 已改为可空签名 + `logger.error` + `return null` 的实现:无 `throw` / `@throws`;3 处最小 `try/catch` 块体内只有 `JSON.parse`(94,脱敏常量)、`createImageBitmap`(95)、`new Texture`(95)三个调用表达式,`new Blob(...)` 在 `try` 前、`!isRecord` 守卫与 `return meta` 在 `try` 后;`readRawMeta` 用 `!isRecord` 拒绝非对象 JSON(88);`validateMeta` / `validateBitmapBounds` 用可提前退出的 `for` 循环、体内无 `forEach`;位图越界时先用 `close()` 前捕获的尺寸记 87 再 `close()`,纹理失败先 `close()`;82–95 全部接入且参数对齐;prettier、eslint、CRLF / BOM、模块规则门禁通过。</done>
</task>
<task type="auto">
<name>Task 4: 改写 `parse.test.ts` —— mock logger、断言空返回与精确错误码、保留成功用例、加无 `throw` 静态用例</name>
<files>packages/render-anim/src/__test__/parse.test.ts</files>
<read_first>
- 本计划的「`parse.test.ts` 改写规格」「错误码映射」(唯一内容依据)
- `packages/render-anim/src/__test__/parse.test.ts`(当前 21 个用例、`renderMock`、`buildAnimation`)
- `packages/render-anim/src/parse.ts`(Task 3 后的实现:错误码、失败顺序、返回 null)
- `packages/common/src/logger.ts`(`logger.error` 为 `(code, ...params) => void`,mock 只需 `error` / `warn`)
- `dev.md`(测试文件:每个 `it` 前一行注释;CRLF;无 `any`)
</read_first>
<action>
仅在 Task 3 完成且收到「可以执行」之后执行。本任务只改 `packages/render-anim/src/__test__/parse.test.ts`。
1. 重写 mock 段:`vi.hoisted` 定义 `loggerMock = { error: vi.fn(), warn: vi.fn() }` 与 `renderState = { failTexture: false }`;`vi.mock('@motajs/common', () => ({ logger: loggerMock }))`;`vi.mock('@motajs/render', ...)` 的 `FakeTexture` 构造器在 `renderState.failTexture` 为 `true` 时抛错(用于 95 纹理路径)。两个 `vi.mock` 必须位于 `import ... from '../index'` 之前。
2. 新增局部辅助 `parseOk`(断言非空并返回 `IAnimationParsedData`,用于成功用例类型收窄)与 `expectFailure`(断言 `null` + `logger.error` 恰好调用一次且首个实参等于期望码);`buildRawAnimation(rawMeta: string, sprites?)` 用于 94 号非法 JSON。
3. 保留 09-54 的 11 个成功用例与断言内容,仅把解析调用换成 `parseOk`;每个 `it` 前保留或新写一行中文注释说明覆盖内容。
4. 重写失败用例为「返回 null + 精确错误码」断言,按「`parse.test.ts` 改写规格」的表格覆盖 82–95 全部码(含 95 的解码失败与纹理失败两条、94 的非法 JSON 一条、元数据为非对象 JSON 的 5 条(`42` / `null` / `0` / `false` / `""`,断言 `null` + 88))。越界用例额外断言 `close` 被调用且 `loggerMock.error.mock.calls[0][1]` 含 `exceeds the decoded image 16 x 16`(尺寸在 `close()` 前捕获);纹理失败用例额外断言 `close` 被调用。
5. 新增静态闸门用例:`readFileSync('packages/render-anim/src/parse.ts', 'utf8')`(`node:fs`),断言无 `throw` / `@throws`、`try {` 恰 3 处、无 `finally`,三处 `try` 块体内分别只有 `meta = JSON.parse(text)` / `image = await createImageBitmap(webpBlob)` / `texture = new Texture(image)`(`new Blob` 在 `try` 外、`!isRecord` 守卫在 `try` 后),并断言 `validateMeta` / `validateBitmapBounds` 体内无 `forEach`(`forEach` 的 `return false` 不会结束整个函数);用例前一行注释说明「解析器不得出现 throw」。
6. `beforeEach` 清理 `loggerMock.error` / `loggerMock.warn`、重置 `renderState.failTexture` 并重建 32×32 假位图;`afterAll` 调用 `vi.unstubAllGlobals()`。不修改 `parse.ts`、不改其它测试文件。
</action>
<verify>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8');const codes=[];for(let c=82;c<=95;c++)codes.push(c);const nums=new Set((t.match(/\b\d+\b/g)||[]).map(Number));const miss=codes.filter(c=>!nums.has(c));const fail=[];const SQ=String.fromCharCode(39),DQ=String.fromCharCode(34);const prims=['42','null','0','false',DQ+DQ].map(v=>'buildRawAnimation('+SQ+v+SQ);const primMiss=prims.filter(p=>t.indexOf(p)===-1);if(primMiss.length)fail.push('missing non-object metadata cases: '+primMiss.join(','));if(t.indexOf('vi.mock('+String.fromCharCode(39)+'@motajs/common'+String.fromCharCode(39))===-1)fail.push('missing @motajs/common mock');if(t.indexOf('toBeNull()')===-1)fail.push('no toBeNull assertion');if(miss.length)fail.push('missing codes: '+miss.join(','));if(t.indexOf('rejects.toThrow')!==-1)fail.push('still uses rejects.toThrow');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: logger mock, null assertions, all 82..95 codes covered');"</automated>
<fails_when>测试未 mock `@motajs/common`、未断言 `toBeNull()`、缺少任一 82–95 码、缺少 `42` / `null` / `0` / `false` / `""` 的非对象元数据用例,或仍保留 `rejects.toThrow`(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8');const fail=[];if(t.indexOf('exceeds the decoded image 16 x 16')===-1)fail.push('87 out-of-bounds test does not assert the captured dimensions');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 87 test asserts the close-time captured dimensions');"</automated>
<fails_when>越界用例未断言 87 明细串包含 `exceeds the decoded image 16 x 16`(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const lines=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8').replace(/\r\n/g,'\n').split('\n');const bad=[];for(let i=0;i<lines.length;i++){const tr=lines[i].trim();if(tr.startsWith('//')||tr.startsWith('*')||tr.startsWith('/*'))continue;if(!/\bit\s*\(/.test(lines[i]))continue;let j=i-1;while(j>=0&&lines[j].trim()==='')j--;if(j<0||!lines[j].trim().startsWith('//'))bad.push(i+1);}if(bad.length){console.error('it without // comment on the preceding non-empty line: '+bad.join(','));process.exit(1);}console.log('OK: every it has a // comment on the preceding non-empty line');"</automated>
<fails_when>存在 `it` 调用前没有单行注释(打印缺失数量,退出码 1)。</fails_when>
<automated>node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts</automated>
<fails_when>退出码非 0,或输出出现 `failed`;browserslist 的 stderr 提示属正常,不作为失败依据。</fails_when>
<automated>node node_modules/prettier/bin/prettier.cjs --check packages/render-anim/src/__test__/parse.test.ts</automated>
<fails_when>prettier 报告该文件待格式化,或退出码非 0。</fails_when>
<automated>node node_modules/eslint/bin/eslint.js packages/render-anim/src/__test__/parse.test.ts</automated>
<fails_when>eslint 打印任一 error / warning,或退出码非 0。</fails_when>
<automated>node -e "const fs=require('fs');const b=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts');const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;const ok=lf===crlf&&tabs===0&&!bom;console.log((ok?'OK':'FAIL')+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);process.exit(ok?0:1);"</automated>
<fails_when>出现非 CRLF 换行、制表符或 BOM(打印 `FAIL`,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- 测试在导入 `../index` 之前 mock 了 `@motajs/common`(`logger.error` / `logger.warn` 为 `vi.fn()`)与 `@motajs/render`。
- 全部失败用例断言返回 `null` 与精确错误码;82–95 每个码至少被一个用例断言;元数据为 `42` / `null` / `0` / `false` / `""` 的 5 条非对象 JSON 用例断言 `null` + 88;越界用例额外断言 `close` 被调用且 87 明细串含 `exceeds the decoded image 16 x 16`(尺寸在 `close()` 前捕获),纹理失败用例额外断言 `close` 被调用。
- 09-54 的 11 个成功用例与断言内容保留(仅改用 `parseOk` 收窄类型),且每个 `it` 前有一行中文注释。
- 新增静态用例断言 `parse.ts` 无 `throw` / `@throws`、`try {` 恰 3 处、无 `finally`,三处 `try` 块体内分别只有 `meta = JSON.parse(text)` / `image = await createImageBitmap(webpBlob)` / `texture = new Texture(image)`(`new Blob` 在 `try` 外、`!isRecord` 守卫在 `try` 后),且 `validateMeta` / `validateBitmapBounds` 体内无 `forEach`。
- `node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts` 全部通过;prettier / eslint / CRLF / BOM 门禁通过。
</acceptance_criteria>
<done>`parse.test.ts` 已改为 mock logger 的空返回 / 错误码断言套件:成功用例保留、82–95 全覆盖(含 94 非法 JSON、95 解码与纹理失败、5 条非对象 JSON 88 用例)、87 越界用例断言日志含 `close()` 前捕获的 `16 x 16` 且 `close` 被调用、纹理失败断言 `close`、每个 `it` 有注释、新增无 `throw` 静态用例;targeted vitest 与格式 / lint / CRLF 门禁全部通过。</done>
</task>
<task type="auto">
<name>Task 5: 静态门禁、范围 / 哈希复核,写 `09-55-SUMMARY.md`</name>
<files>.planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md</files>
<read_first>
- 本计划的 `<success_criteria>` 与「覆盖审计」(SUMMARY 必须覆盖的条目)
- `(process.env.TEMP||'.')/gsd-09-55-status.txt`、`gsd-09-55-hashes.txt`、`gsd-09-55-logger-baseline.json`(Task 1 基线)
- `packages/render-anim/src/parse.ts`、`packages/render-anim/src/__test__/parse.test.ts`、`packages/render-anim/package.json`、`packages/common/src/logger.json`(Task 2–4 产物)
- `.planning/phases/09-minimum-browser-runnable/09-54-SUMMARY.md`(SUMMARY 结构与 frontmatter 风格参考)
- `AGENTS.md` / `dev.md`(CRLF、无 BOM)
</read_first>
<action>
仅在 Task 4 完成且收到「可以执行」之后执行。本任务只写 `09-55-SUMMARY.md`,不改任何代码文件。
1. **写 SUMMARY 前的范围闸门(SUMMARY 必须尚不存在;必须在写文件之前内联执行)**:在第 3 步写 SUMMARY 之前运行下面这条显式 `node` 命令(与 09-54 相同的做法),要求 `addedIn` 恰为 ` M packages/render-anim/package.json`、`addedOut` / `removedIn` / `removedOut` 为空,且 `addedIn` / 当前工作树中都**没有** `09-55-SUMMARY.md`。`<verify>` 里的范围门禁在写之后运行,届时 SUMMARY 必须存在,两者分工不同(预写闸门只在这里跑)。`parse.ts` / `parse.test.ts` / `logger.json` 在基线中已是脏 / 未跟踪条目,其内容变化由哈希闸门覆盖。任一不符,停下上报,不写 SUMMARY。命令:`node -e "const{execSync}=require('child_process'),fs=require('fs');const SUMMARY='?? .planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md';const ALLOW=' M packages/render-anim/package.json';const base=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-55-status.txt','utf8').split(/\r?\n/).filter(l=>l.length>0);const cur=execSync('git status --porcelain -uall',{encoding:'utf8'}).split(/\r?\n/).filter(l=>l.length>0);const inScope=l=>{const p=l.slice(3);return p.indexOf('packages/render-anim/')===0||p.indexOf('packages/common/src/logger.json')===0||p.indexOf('.planning/phases/09-minimum-browser-runnable/')===0;};const added=cur.filter(l=>base.indexOf(l)===-1);const removed=base.filter(l=>cur.indexOf(l)===-1);const addedIn=added.filter(inScope);const addedOut=added.filter(l=>!inScope(l));const removedIn=removed.filter(inScope);const removedOut=removed.filter(l=>!inScope(l));const extra=addedIn.filter(l=>l!==ALLOW);const missing=addedIn.indexOf(ALLOW)===-1?[ALLOW]:[];const summaryPresent=addedIn.indexOf(SUMMARY)!==-1||cur.indexOf(SUMMARY)!==-1;console.log('addedIn:\n'+addedIn.join('\n'));console.log('extra:\n'+extra.join('\n'));console.log('missing:\n'+missing.join('\n'));console.log('summaryPresent:'+summaryPresent);if(extra.length||missing.length||removedIn.length||addedOut.length||removedOut.length||summaryPresent){console.error('pre-write range drift');process.exit(1);}console.log('OK: pre-write range is exactly package.json change and 09-55-SUMMARY.md is absent');"`。
2. **写 SUMMARY 前的哈希闸门**:10 条基线中,只有 `parse.ts`、`parse.test.ts`、`package.json`、`logger.json` 的哈希变化;`types.ts` / `animater.ts` / `index.ts` / 09-54 计划与摘要 / `09-55-PLAN.md` 哈希不变。哈希闸门通过后、写 SUMMARY 之前,先跑类型检查(`node node_modules/vue-tsc/bin/vue-tsc.js --version` 哨兵,再跑 `node node_modules/vue-tsc/bin/vue-tsc.js --noEmit` 并过滤 `packages/render-anim`),把真实结果写入 SUMMARY;哨兵无法启动或过滤出诊断则停下上报。
3. **写 `09-55-SUMMARY.md`**:UTF-8 无 BOM、CRLF、4 空格缩进的 Markdown。frontmatter 至少包含 `phase: 09-minimum-browser-runnable`、`plan: 55`、`subsystem: render-anim`、`tags`、`requires`、`provides`、`affects`、`actuals`(tokens / tasks / commits: 0)、`tech-stack`、`key-files`(modified)、`key-decisions`、`patterns-established`、`duration`、`completed`、`status: complete`。正文至少包含:
- **本次范围**:只改 4 个代码 / 配置文件 + 本 SUMMARY;`types.ts` / `animater.ts` / `index.ts` 未动;不跑游戏 / 浏览器 / dev server;0 提交;09-55 / 波次 4 / `depends_on: 09-54` 的编号说明。
- **签名变更**:`Promise<IAnimationParsedData | null>`;调用方判空的语义。
- **错误码表**:82–95 一行一码 + 文本 + 触发位置(含 87 同时用于越界、88 同时用于 `readRawMeta` 的非对象 JSON 守卫与帧结构、94 使用脱敏常量、95 同时用于解码与纹理);并说明 `42` / `null` / `0` / `false` / `""` 元数据由 `readRawMeta` 记 88 后返回 `null`,不会静默短路。
- **`try/catch` 例外说明**:仅 3 处、块体内只有三个外部调用表达式(`new Blob` 与 `!isRecord` 守卫在 `try` 外),及 `dev.md` 理由与用户决定。
- **测试结果**:targeted vitest 的用例数与通过情况、prettier / eslint / CRLF / BOM 的真实输出摘要。
- **门禁结果**:范围、哈希、`logger.json` 深比较(warn 含 213 未变)、`$n` 占位一致、`parse.ts` 无 `throw`。
- **类型检查**:先跑 `node node_modules/vue-tsc/bin/vue-tsc.js --version` 哨兵,再跑 `node node_modules/vue-tsc/bin/vue-tsc.js --noEmit`,只统计含 `packages/render-anim` 的诊断行;在正文记录哨兵输出、过滤结果与全仓退出码(既有其它包的诊断不参与判定)。
- **已知限制**:未跑 `pnpm install`、`pnpm-lock.yaml` 未更新、`node_modules` 无 `@motajs/common` 链接(OI-6);未做浏览器 E2E(OI-8);`logger.error` 的文档页面未生成(OI-7)。
- **未校准估算**:`confidence: low`、`tokens: 90000` 未校准(6 个任务 / 90k 仅为 advisory 建议值,不作为拆分依据,不做再切分),须如实声明。
4. **写后的范围闸门**:`added` 恰为 ` M packages/render-anim/package.json` 与 `?? .planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md`;`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 为空。
5. 不写 `09-55-RESEARCH.md` / `09-55-VALIDATION.md`;不改 `STATE.md` / `ROADMAP.md` / `09-CONTEXT.md` / 09-54 计划与摘要;不执行任何 git 写命令。
</action>
<verify>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const SUMMARY='?? .planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md';const ALLOW=' M packages/render-anim/package.json';const base=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-55-status.txt','utf8').split(/\r?\n/).filter(l=>l.length>0);const cur=execSync('git status --porcelain -uall',{encoding:'utf8'}).split(/\r?\n/).filter(l=>l.length>0);const inScope=l=>{const p=l.slice(3);return p.indexOf('packages/render-anim/')===0||p.indexOf('packages/common/src/logger.json')===0||p.indexOf('.planning/phases/09-minimum-browser-runnable/')===0;};const added=cur.filter(l=>base.indexOf(l)===-1);const removed=base.filter(l=>cur.indexOf(l)===-1);const addedIn=added.filter(inScope);const addedOut=added.filter(l=>!inScope(l));const removedIn=removed.filter(inScope);const removedOut=removed.filter(l=>!inScope(l));const rest=addedIn.filter(l=>l!==SUMMARY);const extra=rest.filter(l=>l!==ALLOW);const missing=rest.indexOf(ALLOW)===-1?[ALLOW]:[];const summaryEntry=addedIn.filter(l=>l.indexOf('09-55-SUMMARY.md')!==-1);console.log('addedIn:\n'+addedIn.join('\n'));console.log('extra:\n'+extra.join('\n'));console.log('missing:\n'+missing.join('\n'));console.log('summaryEntry:\n'+summaryEntry.join('\n'));if(extra.length||missing.length||removedIn.length||addedOut.length||removedOut.length||summaryEntry.some(l=>l!==SUMMARY)){console.error('range drift: expected package.json only, plus exactly '+SUMMARY+' after the write');process.exit(1);}console.log('OK: range is package.json change plus, once written, exactly '+SUMMARY);"</automated>
<fails_when>除 ` M packages/render-anim/package.json` 外出现新增条目,或 `09-55-SUMMARY.md` 出现时不是恰好 `?? .planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md`,或范围外 / 删除条目非空(打印分组,退出码 1)。该门禁在写 SUMMARY 前后都成立:写前 SUMMARY 缺席,写后必须恰好是这一条。</fails_when>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const p=(process.env.TEMP||'.')+'/gsd-09-55-hashes.txt';const base=fs.readFileSync(p,'utf8').replace(/\r\n/g,'\n').trim().split('\n').filter(Boolean);const now=base.map(l=>{const f=l.split(' ')[0];return f+' '+execSync('git hash-object '+f,{encoding:'utf8'}).trim();});const changed=now.filter(l=>base.indexOf(l)===-1);const expected=['packages/render-anim/src/parse.ts','packages/render-anim/src/__test__/parse.test.ts','packages/render-anim/package.json','packages/common/src/logger.json'];const names=changed.map(l=>l.split(' ')[0]);const missing=expected.filter(f=>names.indexOf(f)===-1);const extra=names.filter(n=>expected.indexOf(n)===-1);console.log('changed:\n'+changed.join('\n'));if(base.length!==10||missing.length||extra.length){console.error('unexpected changed set; missing='+missing.join(',')+' extra='+extra.join(','));process.exit(1);}console.log('OK: only the 4 intended files changed among the 10 baselines');"</automated>
<fails_when>变化的文件不是恰好 `parse.ts` / `parse.test.ts` / `package.json` / `logger.json`(含 `types.ts` / `animater.ts` / `index.ts` / 09-54 计划或摘要 / `09-55-PLAN.md` 被改动),或基线行数不是 10(打印差异,退出码 1)。</fails_when>
<automated>node -e "const{spawnSync}=require('child_process');const r=spawnSync(process.execPath,['node_modules/vue-tsc/bin/vue-tsc.js','--version'],{encoding:'utf8'});if(r.status!==0){console.error('vue-tsc sentinel failed: '+(r.stderr||r.stdout));process.exit(1);}console.log('OK: vue-tsc sentinel '+String(r.stdout).trim());"</automated>
<fails_when>`vue-tsc --version` 哨兵无法启动(退出码非 0),说明类型检查工具链不可用(打印 stderr / stdout,退出码 1)。</fails_when>
<automated>node -e "const{spawnSync}=require('child_process');const r=spawnSync(process.execPath,['node_modules/vue-tsc/bin/vue-tsc.js','--noEmit'],{encoding:'utf8',maxBuffer:1e8});const out=((r.stdout||'')+(r.stderr||'')).split(/\r?\n/);const hits=out.filter(l=>l.indexOf('packages/render-anim')!==-1);if(hits.length){console.error('render-anim diagnostics:\n'+hits.join('\n'));process.exit(1);}console.log('OK: 0 ts diagnostics under packages/render-anim (vue-tsc exit '+r.status+')');"</automated>
<fails_when>`vue-tsc --noEmit` 输出中出现任何含 `packages/render-anim` 的诊断行(打印这些行,退出码 1);全仓其它包的既有诊断与总退出码不参与判定。</fails_when>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const base=JSON.parse(fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-55-logger-baseline.json','utf8'));const fail=[];Object.keys(base.error).forEach(k=>{if(j.error[k]!==base.error[k])fail.push('error '+k+' changed');});if(JSON.stringify(j.warn)!==JSON.stringify(base.warn))fail.push('warn changed (213 must be preserved)');const newCodes=Object.keys(j.error).filter(k=>base.error[k]===undefined);const want=[];for(let c=82;c<=95;c++)want.push(String(c));if(newCodes.length!==14||want.some(c=>newCodes.indexOf(c)===-1))fail.push('new codes are not exactly 82..95: '+newCodes.join(','));if(Object.keys(j.error).some(k=>+k>=1000&&base.error[k]===undefined))fail.push('used a 1000+ code');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: only 82..95 added; warn (incl. 213) intact');"</automated>
<fails_when>`warn` 段有任何变化、既有 error 码被改、新增码不是恰好 82–95,或使用了 `1000+` 码(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const f='.planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md';const s=fs.readFileSync(f,'utf8');const need=['09-55','parseRenderAnimation','Promise<IAnimationParsedData | null>','@motajs/common','82','95','try','vitest','prettier','eslint','vue-tsc','render-anim','213','0 次提交','files_modified','未校准'];const miss=need.filter(n=>s.indexOf(n)===-1);if(miss.length){console.error('missing '+miss.join(','));process.exit(1);}console.log('OK: summary present');"</automated>
<fails_when>SUMMARY 缺少范围 / 签名 / 错误码 / 依赖 / 测试 / 门禁 / 213 未变 / 0 提交 / 未校准估算等关键内容(打印缺失项,退出码 1)。</fails_when>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const base=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-55-status.txt','utf8').split(/\r?\n/).filter(l=>l.length>0);const cur=execSync('git status --porcelain -uall',{encoding:'utf8'}).split(/\r?\n/).filter(l=>l.length>0);const summary='?? .planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md';const allow=[' M packages/render-anim/package.json',summary];const added=cur.filter(l=>base.indexOf(l)===-1);const removed=base.filter(l=>cur.indexOf(l)===-1);const inScope=l=>{const p=l.slice(3);return p.indexOf('packages/render-anim/')===0||p.indexOf('packages/common/src/logger.json')===0||p.indexOf('.planning/phases/09-minimum-browser-runnable/')===0;};const addedIn=added.filter(inScope);const addedOut=added.filter(l=>!inScope(l));const removedIn=removed.filter(inScope);const removedOut=removed.filter(l=>!inScope(l));const extra=addedIn.filter(l=>allow.indexOf(l)===-1);const missing=allow.filter(l=>addedIn.indexOf(l)===-1);console.log('addedIn:\n'+addedIn.join('\n'));console.log('extra:\n'+extra.join('\n'));console.log('missing:\n'+missing.join('\n'));process.exit(extra.length+missing.length+removedIn.length+addedOut.length+removedOut.length?1:0);"</automated>
<fails_when>写后 `addedIn` 不是恰好 `package.json` 修改 + `09-55-SUMMARY.md`,或出现 `extra` / `missing` / `removedIn` / `addedOut` / `removedOut`(退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const b=fs.readFileSync('.planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md');const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;const ok=lf===crlf&&tabs===0&&!bom;console.log((ok?'OK':'FAIL')+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);process.exit(ok?0:1);"</automated>
<fails_when>SUMMARY 出现非 CRLF 换行、制表符或 BOM(打印 `FAIL`,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- 写 SUMMARY 前的严格范围闸门已在 `<action>` 第 1 步内联执行:`addedIn` 恰为 ` M packages/render-anim/package.json`,且 `09-55-SUMMARY.md` 尚不存在,`removedIn` / `addedOut` / `removedOut` / `extra` / `missing` 为空;`<verify>` 的范围门禁在写后运行,允许且要求恰好出现 `?? .planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md`(写前缺席也通过)。
- 写 SUMMARY 前的哈希闸门:10 条基线中只有 `parse.ts` / `parse.test.ts` / `package.json` / `logger.json` 变化。
- `logger.json` 深比较:`warn` 段(含 `213`)与既有 error 码逐字未变;新增码恰为 82–95;未使用 `1000+`。
- 类型检查门禁:`vue-tsc --version` 哨兵通过,`--noEmit` 输出中 `packages/render-anim` 诊断为 0 行(全仓其它既有诊断与总退出码不参与判定),且 SUMMARY 记录了哨兵与过滤结果。
- `09-55-SUMMARY.md` 已写入(UTF-8 无 BOM + CRLF),覆盖范围、签名变更、错误码表、`try/catch` 例外、测试与门禁真实结果、类型检查结果、已知限制(OI-6 / OI-7 / OI-8)与未校准估算。
- 写后范围闸门:`addedIn` 恰为 `package.json` 修改与 `09-55-SUMMARY.md`;0 次提交;未运行游戏 / 浏览器 / dev server / `pnpm install`。
</acceptance_criteria>
<done>写前范围闸门在 `<action>` 第 1 步内联执行并通过(SUMMARY 尚不存在,`addedIn` 恰为 `package.json`),哈希闸门通过(只有 4 个目标文件变化);`logger.json` 深比较证明 warn(含 213)与既有 error 码未变、新增恰为 82–95;`09-55-SUMMARY.md` 已写入并通过内容与 CRLF / BOM 门禁;写后范围闸门通过;0 次提交。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 动画二进制 → 解析器 | `.animate` 文件是不可信输入;头部 / 长度 / sprite 表 / JSON / 位图 / 对象索引全部在解析器内校验,失败只记日志并返回 `null` |
| 解析器 → 日志系统 | 解析器把失败原因编码成 82–95 的固定消息;日志参数只包含数字、尺寸与字段名,不包含文件内容或环境信息 |
| 包依赖 → 工作区 | `packages/render-anim` 新增 `@motajs/common` 只用 `workspace:*` 本地链接,不触达 npm registry |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|----------|----------|-------------|-----------------|
| T-55-01 | Tampering | `parse.ts` 头部 / 长度读取 | high | mitigate | 保留 09-54 的全部校验条件,只把抛错改为 `logger.error(82..85)` + `return null`;校验不通过绝不继续解码或构造纹理 |
| T-55-02 | Tampering | `parse.ts` sprite / bitmap / 帧对象 | high | mitigate | 保留 sprite 表边界、bitmap 数量 / 字段、解码后越界、对象索引、ratio / blend / opacity / mirror 校验(86–93);越界时先用 `close()` 前捕获的 `imageWidth` / `imageHeight` 记 87,再 `image.close()` |
| T-55-03 | Denial of Service | `parse.ts` 元数据 JSON / 帧数组 | medium | accept | 元数据来自本地受信资源;`JSON.parse` 失败被 94 捕获、非对象 JSON(`42` / `null` / `0` / `false` / `""`)被 `readRawMeta` 的 `!isRecord` 守卫按 88 拒绝,两者都立即返回 `null`;帧 / 对象数量仍受文件大小约束,不引入额外配额系统 |
| T-55-04 | Information Disclosure | `parse.ts` 日志参数 | low | mitigate | 日志只输出数字、尺寸、字段名;94 使用固定脱敏串 `metadata is not valid JSON`(不读 `error.message`,避免 JSON 内容回显),95 仅输出解码 / 纹理异常的 `message`;不输出原始字节、文件路径或用户数据;`logger.error` 会用固定消息模板替换参数 |
| T-55-05 | Denial of Service | `try/catch` 过度捕获 | medium | mitigate | 严格 3 处 `try`,块体内分别只有 `JSON.parse` / `createImageBitmap` / `new Texture` 三个调用表达式(`new Blob` 与 `!isRecord` 守卫在 `try` 外),不写 `finally`,捕获后立即 `return null`,不得在 catch 中继续执行后续解析步骤 |
| T-55-06 | Tampering | `logger.json` 码段污染 | medium | mitigate | Task 2 / Task 5 用 Task 1 快照深比较:既有 error 码与整个 `warn` 段(含并发 `213`)必须逐字不变,新增码必须恰为 82–95,禁止 `1000+` |
| T-55-SC | Tampering | 依赖安装 | high | mitigate | 只新增 `workspace:*` 本地依赖,不执行 `pnpm install`、不访问 registry、不改锁文件;不引入任何第三方包 |
</threat_model>
<verification>
- **无 throw(核心)**:`parse.ts` 全文 `\bthrow\b` / `@throws` / `finally` 均为 0;`try {` 恰 3 处且块体内分别只有 `meta = JSON.parse(text)` / `image = await createImageBitmap(webpBlob)` / `texture = new Texture(image)`;签名为 `Promise<IAnimationParsedData | null>`;82–95 全部出现在 `logger.error` 调用点;`readRawMeta` 在 `try` 之后用 `!isRecord` 拒绝 `42` / `null` / `0` / `false` / `""` 等非对象(88),`if (!meta) return null;` 只表示失败;`validateMeta` / `validateBitmapBounds` 用可提前退出的 `for` 循环、体内无 `forEach`;87 越界日志使用 `close()` 前捕获的 `imageWidth` / `imageHeight`。
- **错误码表**:`logger.json` 的 error 段新增恰为 82–95(14 条),每条消息与「错误码映射」表逐字一致(Task 2 门禁解析计划表格做全文本比较,不仅比对占位数量),`$n` 数量与调用点一致;既有 `1..81` / `2001..2008` 与整个 `warn` 段(含 `213`)与 Task 1 快照深比较不变。
- **依赖**:`packages/render-anim/package.json` 含 `@motajs/common: workspace:*` 与 `@motajs/render: workspace:*`,且 `@motajs/common` 的键序在 `@motajs/render` 之前,无其它字段变化。
- **测试**:`node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts` 全部通过;失败用例断言 `null` + 精确错误码;越界用例断言 87 明细串含 `exceeds the decoded image 16 x 16` 且 `close` 被调用,纹理失败断言 `close`;成功用例全部保留;每个 `it` 有一行中文注释。
- **格式 / lint**:`prettier --check` 对 4 个改动文件(`parse.ts` / `parse.test.ts` / `package.json` / `logger.json`)通过;`eslint` 对 `parse.ts` / `parse.test.ts` 通过;全部文件(含 SUMMARY)CRLF、无制表符、无 BOM。SUMMARY 只做 CRLF / BOM / 内容门禁,不纳入 prettier(避免 Markdown 表格重排与内容逐字门禁冲突)。
- **类型**:先跑 `node node_modules/vue-tsc/bin/vue-tsc.js --version` 哨兵,再跑 `--noEmit`,过滤 `packages/render-anim` 诊断为 0 行;全仓既有错误与总退出码不参与判定;SUMMARY 记录哨兵与过滤结果(Task 5 门禁强制)。
- **范围**:写 SUMMARY 前(Task 5 `<action>` 第 1 步内联)`addedIn` 恰为 ` M packages/render-anim/package.json` 且 SUMMARY 不存在;`<verify>` 门禁在写后按「package.json + 恰好 `?? .../09-55-SUMMARY.md`」判定,写前缺席同样通过;`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 为空。
- **哈希**:10 条基线中只有 `parse.ts` / `parse.test.ts` / `package.json` / `logger.json` 变化;`types.ts` / `animater.ts` / `index.ts` / 09-54 计划与摘要 / `09-55-PLAN.md` 不变。
- **明确不做**:不运行游戏 / 浏览器 / dev server / `pnpm install`;不使用真实 WebP 素材做 E2E;不执行任何 git 写命令,0 次提交。
</verification>
<success_criteria>
- [ ] Task 0 已向用户完整汇报可空签名、82–95 错误码表与 `$1` 明细串、`@motajs/common` 依赖及其排序、`try/catch` 三处仅包裹外部调用表达式的作用域与 dev.md 例外理由、唯一被改写的 jsDoc、测试与影响范围,并等待用户针对本计划回复「可以执行」后才继续。
- [ ] `parse.ts` 已改为 `parseRenderAnimation(buffer: ArrayBuffer): Promise<IAnimationParsedData | null>`:无 `throw` / `@throws`,全部失败路径 `logger.error(82..95)` + `return null`,3 处最小 `try/catch` 块体内分别只有 `meta = JSON.parse(text)`(94,脱敏常量)、`image = await createImageBitmap(webpBlob)`(95)、`texture = new Texture(image)`(95),`new Blob(...)` 在 `try` 前、`!isRecord` 守卫与 `return meta` 在 `try` 后;越界时先用 `close()` 前捕获的 `imageWidth` / `imageHeight` 记 87 再 `close()`,纹理失败先 `image.close()`;`readRawMeta` 用 `!isRecord` 拒绝非对象 JSON(88);`validateMeta` / `validateBitmapBounds` 用可提前退出的 `for` 循环、无 `forEach`。
- [ ] `logger.json` 的 error 段已按 82–95 追加 14 条英文消息,`$n` 与调用点一致;既有 error 码与整个 `warn` 段(含并发 `213`)逐字未变;未使用 `1000+`。
- [ ] `packages/render-anim/package.json` 已新增 `@motajs/common: workspace:*`(键序在 `@motajs/render` 之前),且未改其它字段。
- [ ] `parse.test.ts` 已 mock `@motajs/common`,断言 `null` 返回与精确错误码(82–95 全覆盖,含元数据为 `42` / `null` / `0` / `false` / `""` 的五条非对象 JSON 用例),87 越界用例断言日志含 `close()` 前捕获的 `16 x 16` 且 `close` 被调用,保留全部成功用例,新增 `parse.ts` 无 `throw` 静态用例;targeted vitest 全部通过。
- [ ] prettier、eslint、CRLF / BOM、静态内容门禁通过;`vue-tsc` 经哨兵确认可启动后过滤 `packages/render-anim` 诊断为 0 行,且 SUMMARY 记录该结果。
- [ ] `types.ts` / `animater.ts` / `index.ts` 与 09-54 计划 / 摘要哈希不变;`09-55-PLAN.md` 未被改写;未修改其它包或配置;未新增 `@motajs/common` 之外的依赖。
- [ ] `09-55-SUMMARY.md` 已写入(UTF-8 无 BOM + CRLF),包含范围、签名变更、错误码表、`try/catch` 例外、测试与门禁真实结果、类型检查结果、已知限制(OI-6 / OI-7 / OI-8)与未校准估算(`confidence: low`、`tokens: 90000`,6 个任务 / 90k 仅为建议值)。
- [ ] 范围闸门与哈希闸门通过;0 次提交;未运行游戏 / 浏览器 / dev server / `pnpm install`。
</success_criteria>
<output>
Create `.planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md` when done
</output>
@@ -0,0 +1,164 @@
---
phase: 09-minimum-browser-runnable
plan: 55
subsystem: render-anim
tags:
- render-anim
- animation
- binary-parser
- logger
- error-codes
- vitest
requires:
- 09-54 parseRenderAnimation v2 binary parser
provides:
- parseRenderAnimation nullable return with logger.error code paths
- common logger error codes 82..95 for animation parsing
- @motajs/common workspace dependency for render-anim
affects:
- packages/render-anim/src/parse.ts
- packages/common/src/logger.json
actuals:
tokens: 18950
tasks: 6
commits: 0
tech-stack:
added:
- '@motajs/common workspace:* dependency'
patterns:
- logger.error(code, ...params) then return null for invalid runtime data
- minimal try/catch around JSON.parse / createImageBitmap / new Texture only
- vi.mock @motajs/common logger plus @motajs/render fakes in Node tests
key-files:
modified:
- packages/render-anim/src/parse.ts
- packages/render-anim/src/__test__/parse.test.ts
- packages/render-anim/package.json
- packages/common/src/logger.json
- .planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md
key-decisions:
- parseRenderAnimation now returns Promise<IAnimationParsedData | null>; callers check for null
- animation parsing failures use logger.error 82..95 and return null instead of throwing
- try/catch is limited to JSON.parse (94), createImageBitmap (95) and new Texture (95)
- bitmap overflow captures imageWidth / imageHeight before image.close() and logs 87 with captured sizes
- readRawMeta rejects non-object JSON (42 / null / 0 / false / "") with code 88
- logger.json keeps the concurrent warn 213 entry verbatim and only appends error 82..95
patterns-established:
- external throwing calls are wrapped individually; Blob construction and object guards stay outside try
- validators use early-exit for loops instead of forEach so return false ends the function
duration: 约 18 分钟
completed: 2026-11-08T19:08:00+08:00
status: complete
---
# Phase 09 Plan 55: 动画解析器日志化(可空返回 + 82–95 错误码)Summary
把 `parseRenderAnimation` 从抛异常改为 `logger.error` + 返回 null,并接入 `@motajs/common` 与 82–95 错误码。
## 本计划范围
`files_modified` 逐字如下(共 5 个路径):
- `packages/render-anim/src/parse.ts`
- `packages/render-anim/src/__test__/parse.test.ts`
- `packages/render-anim/package.json`
- `packages/common/src/logger.json`
- `.planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md`
本计划编号为 09-55(09-01..09-54 已占用),波次 4,`depends_on: 09-54`。只改上述 4 个代码 / 配置文件与本 SUMMARY;`types.ts` / `animater.ts` / `index.ts` 未动(哈希基线一致);不改其它包、根配置或既有计划 / 摘要;不跑游戏 / 浏览器 / dev server / `pnpm install`;不执行 git 写命令,**0 次提交**。
## Task 0 批准记录
Task 0 的 `checkpoint:human-verify gate="blocking-human"` 已向用户完整汇报可空签名、82–95 错误码表与 `$1` 明细串、`@motajs/common` 依赖及排序、`try/catch` 三处作用域与 dev.md 例外理由、唯一被改写的 `parseRenderAnimation` jsDoc、测试与影响范围、0 次提交;用户回复「可以执行」后进入 Task 1–5。
## 签名变更
`parseRenderAnimation(buffer: ArrayBuffer): Promise<IAnimationParsedData | null>`。
成功返回 `IAnimationParsedData`;任一步校验或解码失败时先 `logger.error(code, ...)` 再返回 `null`,由调用方判空。解析器全文不出现 `throw` / `@throws` / `finally`。
## 错误码表(82–95)
| code | 文本 | 触发位置 |
|------|------|----------|
| 82 | `Cannot parse animation: buffer is too short, got $1 bytes while the $2 byte header is required.` | `readHeader` 缓冲区短于 16 字节 |
| 83 | `Cannot parse animation: invalid signature 0x$1, expected 0x$2.` | `readHeader` 签名不匹配 |
| 84 | `Cannot parse animation: unsupported version $1, expected version $2.` | `readHeader` 版本不支持 |
| 85 | `Cannot parse animation: data length mismatch, imageDataSize: $1, metaDataSize: $2, buffer length: $3.` | `readHeader` 长度字段 / 总长度不符 |
| 86 | `Cannot parse animation: $1.` | sprite 数量、尺寸与尺寸表越界(`sprite count ...` / `sprite N has invalid size ...` / `sprite table ... exceeds ...`) |
| 87 | `Cannot parse animation: $1.` | 位图列表 / 数量 / 字段 / 解码后越界(越界明细含 `exceeds the decoded image 16 x 16`) |
| 88 | `Cannot parse animation: $1.` | `readRawMeta` 的非对象 JSON 守卫,以及帧 / 元组 / sound 结构 |
| 89 | `Cannot parse animation: invalid object index $1 at frame $2, expected an integer in [0, $3).` | 对象位图索引越界或非整数 |
| 90 | `Cannot parse animation: $1.` | x / y / scale / opacity / mirror / rotate 字段 |
| 91 | `Cannot parse animation: invalid ratio $1, expected a positive finite number.` | ratio 非正或非数字 |
| 92 | `Cannot parse animation: invalid blend mode $1, expected 0 (normal) or 1 (add).` | blend 非 0 / 1 |
| 93 | `Cannot parse animation: $1.` | 音效名称 / 音量 / 音高 / 音效项 |
| 94 | `Cannot parse animation: cannot parse metadata JSON. $1` | `JSON.parse` 失败,`$1` 固定为脱敏常量 `metadata is not valid JSON` |
| 95 | `Cannot parse animation: cannot decode image or create texture. $1` | `createImageBitmap` 或 `new Texture` 抛错,`$1` 为异常 message |
`logger.json` 的 `error` 段在 `"81"` 之后、`"2001"` 之前追加这 14 条;`warn` 段(含并发新增的 `213`)与既有 error `1..81` / `2001..2008` 逐字未变,未使用 `1000+` 码段。
元数据为 JSON 原语 `42` / `null` / `0` / `false` / `""` 时,`JSON.parse` 会成功返回同名原语;`readRawMeta` 在 `try` 之后用 `!isRecord(meta)` 守卫记 88 并返回 `null`,不会让 `if (!meta) return null;` 在 `validateMeta` 之前静默短路。
## `try/catch` 例外说明
全文件恰有 3 处 `try {`,块体内分别只有:
1. `meta = JSON.parse(text);`(失败记 94,脱敏常量,不读 `error.message`)
2. `image = await createImageBitmap(webpBlob);`(失败记 95)
3. `texture = new Texture(image);`(失败先 `image.close()`,再记 95)
`const webpBlob = new Blob([webpBytes], { type: 'image/webp' });` 在 `try` 之前构造;`!isRecord(meta)` 守卫与 `return meta` 在 `try` 之后;不写 `finally`。这是对 dev.md「不建议写 `try-catch-finally`」的显式例外:这三处是外部 API 的天然抛错点,畸形动画文件属于运行时数据条件,用户已决定「记录日志后返回 null」。
位图越界时先捕获 `imageWidth` / `imageHeight`(在 `image.close()` 之前),再 `image.close()`,再用捕获值记录 87 并返回 `false`;日志不得在 `close()` 之后读取 `image.width` / `image.height`。
## 测试结果
- `packages/render-anim/src/__test__/parse.test.ts`:`Test Files 1 passed (1)`、`Tests 70 passed (70)`。
- 11 个 09-54 成功用例全部保留(改用 `parseOk` 收窄类型),断言内容不变。
- 失败用例逐条断言 `null` + 精确 `logger.error` 首个实参,覆盖 82–95 全部码;含 5 条非对象 JSON(`42` / `null` / `0` / `false` / `""`,88)、非法 JSON(94)、解码失败(95)、纹理失败(95)。
- 越界用例额外断言 `close` 被调用,且 `logger.error.mock.calls[0][1]` 含 `exceeds the decoded image 16 x 16`;纹理失败用例额外断言 `close` 被调用。
- 新增静态闸门用例:读取 `packages/render-anim/src/parse.ts`,断言无 `throw` / `@throws`、恰 3 处 `try {`、无 `finally`、三处 `try` 块体只有三个外部调用、`new Blob` 在 `try` 外、`!isRecord` 守卫在 `try` 后,并断言 `validateMeta` / `validateBitmapBounds` 体内无 `forEach`。
- 每个 `it` 前均有一行中文注释。
## 门禁真实结果
- `prettier --check`:对 `parse.ts` / `parse.test.ts` / `package.json` / `logger.json` 全部 `All matched files use Prettier code style!`。
- `eslint`:对 `parse.ts` / `parse.test.ts` 无输出,退出码 0。
- CRLF / BOM / 制表符:4 个改动文件与 SUMMARY 均 `lf===crlf`、`tabs=0`、`bom=false`。
- 范围闸门:写前 `addedIn` 恰为 ` M packages/render-anim/package.json` 且 SUMMARY 不存在;写后恰为 ` M packages/render-anim/package.json` 与 `?? .planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md`,`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 为空。
- 哈希闸门:10 条基线中只有 `parse.ts` / `parse.test.ts` / `package.json` / `logger.json` 变化;`types.ts` / `animater.ts` / `index.ts` / 09-54 计划与摘要 / `09-55-PLAN.md` 哈希不变。
- `logger.json` 深比较:既有 error 码与整个 `warn` 段(含 `213`)逐字未变;新增码恰为 82–95;未使用 `1000+`。
- `$n` 占位数量与调用点一致;82–95 消息与计划「错误码映射」表逐字一致。
- `parse.ts` 静态门禁:无 `throw` / `@throws` / `finally`,恰 3 处 `try {`,签名 `Promise<IAnimationParsedData | null>`,全部 82–95 出现在 `logger.error` 调用点。
## 类型检查
- 哨兵:`vue-tsc Version 6.0.3`。
- `vue-tsc --noEmit`:全仓退出码 2(既有其它包诊断导致),过滤 `packages/render-anim` 后诊断行数为 **0**。
- 全仓既有诊断与总退出码不参与本计划判定。
## 偏差与执行说明
1. **[Rule 1 - Bug] 非数字 ratio / blend / index 的 `.toString()` 会抛错**:`JSON.stringify(NaN)` 产出 `null`,`meta.ratio.toString()` / `meta.blend.toString()` / `index.toString()` 在值为 `null` 时会抛 `TypeError`,违反「解析器无 throw」。改为 `String(meta.ratio)` / `String(meta.blend)` / `String(index)`,其余实参仍为数字,已字符串化。真机 vitest 曾以 2 个失败暴露该问题,修复后 70 个用例全过。
2. **[格式] `// prettier-ignore` 保留 87 日志单行**:计划门禁要求 `image.close()` 之后出现连续的 `logger.error(87`,而 Prettier 因模板串过长会拆分实参列表。仅在该语句前添加 `// prettier-ignore`(与 09-54 的同类做法一致),语义不变。
3. **[类型门禁] `node:fs` 需要 `@ts-expect-error`**:`vue-tsc` 根程序未加载 Node 类型(实测 `import ... from 'fs'` 同样报 TS2591),静态闸门用例需要 `readFileSync` 读取源码。按 dev.md「无法避免类型错误时使用 `// @ts-expect-error` 并说明原因」添加带说明的指令,过滤后 `packages/render-anim` 诊断为 0。
4. **[已知误报,未削弱门禁] Task 3 的 `validateBitmapBounds` 切片门禁**:计划里的 `seg('function validateBitmapBounds', 'export async function parseRenderAnimation')` 会连带包含 `computeFrameBox` 的合法 `forEach`(该函数按计划保持 09-54 原样),因此该门禁必然报 `validateBitmapBounds uses forEach`。未修改门禁、也未改动 `computeFrameBox`;另用花括号匹配提取 `validateMeta` / `validateBitmapBounds` 自身函数体,确认二者均无 `forEach`、均有 `for` 与 `return false`,与计划意图一致。
## 已知限制
- **OI-6**:未运行 `pnpm install`,`pnpm-lock.yaml` 未更新,`packages/render-anim/node_modules` 无 `@motajs/common` 链接;测试与类型检查依赖 `vite.config.ts` / `tsconfig.json` 的 `@motajs/*` 路径映射解析到源码。
- **OI-7**:`logger.error` 的引用页(`error2.html`)未生成 / 未修改,仅写入 `logger.json`。
- **OI-8**:不做浏览器 E2E,不跑游戏 / dev server,不使用真实 WebP 素材;测试只在 Node 环境以 mock `createImageBitmap`、假 `Texture` 与 mocked `logger` 验证纯逻辑。
## 未校准估算
- `confidence: low`、`tokens: 90000` 为**未校准**建议值(6 个任务 / 90k 仅为 advisory,不作为拆分依据,也未再切分)。
- 实际(按最终文件 chars/4 测量,4 个改动文件):约 `tokens: 18950`;`tasks: 6`;`commits: 0`。
## Self-Check
- 4 个代码 / 配置文件与 SUMMARY 均存在且为 CRLF、无 BOM、无制表符。
- targeted vitest 70 个测试全部通过;prettier / eslint / 静态内容 / 哈希 / 范围 / `logger.json` 深比较门禁通过。
- 过滤类型门禁为 0 行 `packages/render-anim` 诊断。
- 0 次提交;未越界写包外文件。
@@ -0,0 +1,917 @@
---
phase: 09-minimum-browser-runnable
plan: 56
type: execute
# 编号说明:09-01..09-55 均已占用,本计划使用下一个空闲编号 09-56。
# depends_on 09-55:本计划只改 09-55 已实现的 parse.ts / parse.test.ts,并新增 animater.ts / animater.test.ts 的整理与单画布重构。
wave: 5
depends_on:
- 09-55
files_modified:
- packages/render-anim/src/parse.ts
- packages/render-anim/src/animater.ts
- packages/render-anim/src/__test__/parse.test.ts
- packages/render-anim/src/__test__/animater.test.ts
- packages/common/src/logger.json
- .planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md
autonomous: false
requirements: []
estimate:
# 未校准估算(confidence: low),SUMMARY 须声明;7 个任务 / 110k 仅为建议值(advisory,不触发拆分),不因此再切分。
# plan-checker 已指出 110k / 7 任务可能超出 smart-zone;按用户要求保持单计划、不拆分,估算仅作 advisory(不阻断、不触发拆分),
# 执行时以 Task 边界为粒度,任一 Task 超预算即停下上报,不得静默压缩内容。
# 成本主要在 parse.ts 的 12 个顶层函数 jsDoc 重写 + 全部 logger 调用点改参数 + 注释补充,
# logger.json 的 82–95 → 82–91 合并,animater.ts 的单画布重构与注释 / jsDoc / region 整理,
# 以及两个测试文件的同步改写与 vitest / prettier / eslint / 过滤 vue-tsc 的往返。
tokens: 110000
raw_tokens: 110000
tasks: 7
confidence: low
must_haves:
truths:
- "**第一个 block 点是 Task 0 的 `blocking-human` 汇报关卡(AGENTS.md / D-03)**:逐字汇报注释 / jsDoc 改写清单、82–91 logger 表、单画布改动、测试更新预期,并明确声明「不改类级 jsDoc、不改 early return、不改 validateMeta 嵌套」;然后停下等待用户恰好回复「可以执行」。"
- "**单画布复用(核心行为修复)**:`sequence` 在 `frames.length === 0` 判断之后只创建一个 `MotaOffscreenCanvas2D`,`setHD(false)` / `setAntiAliasing(false)` 各调用一次;`composeFrame(canvas, texture, data, frame): void` 每帧调用 `canvas.size(frame.width, frame.height)` 后绘制,不再构造画布;每帧 `yield` 同一个 `canvas.canvas`,`rect` 仍为 `{ x: 0, y: 0, w: frame.width, h: frame.height }`。"
- "**清理语义(用户决定 1B)**:正常播放结束时 `canvas.clear()` 并把 `canvas.canvas.width` / `height` 置 0;提前 `.return()` 不写 `finally`、不做兜底清理,最后一帧留在同一画布中交给垃圾回收。"
- "**parse.ts 注释与 jsDoc**:除 `parseRenderAnimation` 外的 12 个顶层函数(`isRecord` / `isNumber` / `isInteger` / `readHeader` / `readSpriteDimensions` / `readRawMeta` / `validateMeta` / `validateBitmapBounds` / `toObject` / `toFrame` / `computeFrameBox` / `toBlendMode`)全部改为多行 jsDoc 并带 `@param` / `@returns`;不出现 `@throws`;补充字节偏移、校验顺序、帧包围盒数学、先 close 再记日志等有价值的行内注释。"
- "**logger 表合并(82–91)**:`packages/common/src/logger.json` 的 `error` 段 82–91 共 10 条**具体**消息(无 `$1`-only 泛化消息),92–95 删除;`1..81`、`2001..2008` 与整个 `warn` 段(含并发 `213` 与既有 `1001`)逐字不变;不新增任何 `1000+` 码。"
- "**logger 调用点只传值**:`parse.ts` 的每个 `logger.error` 只传低基数原因标签(连字符)、数字字符串、字段名标签、`'-'` 占位或 91 的异常 `message` 变量;不再传整句 / 短语字符串字面量。"
- "**animater.ts 整理**:删除全部 `#region` / `#endregion`(128 行短文件不分段);删除 `once` / `cycled` 的 jsDoc(`ITextureAnimater` 接口已文档化,dev.md 继承 API 不重复注释);**保留类级 jsDoc 整块原样不动**(Task 1 全块快照 + Task 4 / Task 5 全块比对 + `/**` 块计数,禁止新增类级注释);成员名集合不变(`composeFrame` 仅改签名,`sequence` / `once` / `cycled` 不变);`composeFrame` 与 `sequence` 改多行 jsDoc 并带 `@param` / `@returns`(`sequence` 为生成器返回)。"
- "**类级 jsDoc 文档债(只记录、不改)**:类级 jsDoc 中「每次 `.next()` 恢复后会释放上一帧」在单画布复用后已不准确;按用户要求逐字保留,未经另行批准不得改写,Task 0 与 SUMMARY 均须记录该文档债。"
- "**测试同步、数量不退化**:`parse.test.ts` 期望码全部改为 82–91 映射并同步注释与静态闸门(原来硬编码 `logger.error(88,'metadataisnotanobject')`、断言 3 处 `try`),新增 `ERROR_PARAM_COUNTS`(82–91 → 3/2/2/6/10/4/5/5/2/2)并由 `expectFailure` 断言 `calls[0].length === count + 1`;`animater.test.ts` 改为「每序列 1 个 `FakeCanvas2D`、相关用例 `const canvas = fakes.instances[0]` 并断言 `canvas.canvas.width/height`、跨帧同一 `source`、逐帧尺寸、正常结束清空归零、提前 return 保留最后一帧、空帧、变换、不释放源纹理」。实测基线为 70 个 parse 用例 + 9 个 animater 用例 = 79 passed;79 是合计,不是 parse 用例数;此前规划输入曾误写成 79 parse,本计划以实测 70 + 9 为准,改写后不得少于该数量。"
- "**范围受控、0 提交**:只写 `files_modified` 的 6 个路径;`types.ts` / `index.ts` / `package.json` / 其它包 / 根配置 / 锁文件 / 既有计划与摘要均不改;不跑游戏 / 浏览器 / dev server / `pnpm install`;不执行 git 写命令。"
artifacts:
- path: packages/render-anim/src/parse.ts
provides: "12 个顶层函数的多行 jsDoc 与行内注释、82–91 的 logger 调用点(只传标签 / 值)、单一导出区域的 region 移除、isRecord 保持不变"
- path: packages/render-anim/src/animater.ts
provides: "单画布复用的 sequence / composeFrame、多行 jsDoc、region 与 once/cycled jsDoc 移除、类级 jsDoc 保留"
- path: packages/render-anim/src/__test__/parse.test.ts
provides: "82–91 期望码与同步注释、更新后的静态闸门(新 90 号调用点文本、3 处 try)、覆盖不退化"
- path: packages/render-anim/src/__test__/animater.test.ts
provides: "单画布 / 同一 source / 逐帧尺寸 / 清空归零 / 提前 return / 空帧 / 变换 / 不释放源纹理"
- path: packages/common/src/logger.json
provides: "error 82–91(10 条具体消息)、92–95 删除、其余码段与 warn 段逐字不变"
- path: .planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md
provides: "文件清单、测试数量、错误码映射、行为变更说明、偏差与真实门禁输出"
key_links:
- "`parse.ts` → `logger.error(code, ...params: string[])`:所有数字必须 `.toString()`;低基数原因标签用连字符(`length-mismatch`),未使用的数值槽传 `'-'`,不得传整句"
- "`logger.json` error 82–91 ↔ `parse.ts` 的 10 个错误码调用点:消息文本、`$n` 数量、实参顺序必须三者一致"
- "`sequence` 单画布 ↔ `composeFrame(canvas, ...)`:`canvas.size(...)` 既是尺寸设置也是上一帧的清空点;正常结束的唯一清理在同一画布上 clear + 归零"
- "`ITextureAnimater`(`packages/render/src/assets/types.ts`)↔ `RenderAnimater.once` / `cycled`:接口已有 jsDoc 与 `@param`,实现类不再重复"
- "`MotaOffscreenCanvas2D.size()`(`packages/render/src/core/canvas2d.ts`)↔ animater 每帧调用:设置 `canvas.width` / `height` 会重置变换矩阵并清空上一帧内容"
- "`parse.test.ts` 的 `loggerMock.error.mock.calls[0]` ↔ 新参数布局:越界用例断言 `[1] === 'out-of-bounds'`、`[9] === '16'`、`[10] === '16'`"
assumptions:
- "**工作树基线(规划日实测,2026-11-09)**:HEAD `7bf9fe9`;`packages/render-anim/src/parse.ts` 574 行、`hash-object d228e871a0172ab1797597c88220014c230e72df`;`animater.ts` 128 行、`222707aee2d6e5c3cc925e7d11143d3d23860921`;`__test__/parse.test.ts` 874 行、`f965d90b3ff5cdcf2fe24492a1ca095a725ffe8e`;`__test__/animater.test.ts` 376 行、`01684f6e055ee8c7105497006cd3863f81af9d52`;`packages/common/src/logger.json` 323 行、`c77a5544189639a3a912a4ab72f2ceed690899d2`。"
- "**测试基线(规划日实测)**:`node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts packages/render-anim/src/__test__/animater.test.ts` → 2 个文件。实测基线为 70 个 parse 用例 + 9 个 animater 用例 = 79 passed;79 是合计,不是 parse 用例数;此前规划输入曾误写成 79 parse,本计划以实测 70 + 9 为准,改写后 parse 用例不得少于 70、animater 用例必须为 9,并在 Task 0 与 SUMMARY 报告实际数量。"
- "**logger 基线(规划日实测)**:`error` 段当前为 `1..81` + `82..95` + `2001..2008`;`warn` 段含 `1..213` 与 `1001`,其中 `213` 为并发未提交改动,必须逐字保留。"
- "**`parseInfo` 支持多位占位符**:`packages/common/src/logger.ts` 的 `parseInfo` 会连续读取数字直到非数字字符,因此 `$10` 可正确替换;本计划 86 号消息使用到 `$10`,已核对实现。"
- "**`MotaOffscreenCanvas2D` 现状**:`size()` 内部 `canvas.width = w * ratio` / `canvas.height = h * ratio`(`ratio = highResolution ? devicePixelRatio : 1`),因此设置尺寸即清空上一帧并重置变换;`setHD(false)` 会以当前 `width` / `height` 重新 `size()`。"
- "**Git 工作树含大量无关脏文件**:`git status` 中已有 `packages-user/*`、`docs/*`、`pnpm-lock.yaml` 等改动,Task 1 只对目标文件采集哈希基线,Task 5 只按白名单文件集合比对,不对全仓脏状态做清理。"
- "**本 run 无 RESEARCH / 无 VALIDATION**:本阶段无 requirement ID(`requirements: []`),Nyquist 不适用;spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip)。"
prohibitions:
- "不得在用户恰好回复「可以执行」之前执行任何任务或派发执行子代理(AGENTS.md / D-03)。"
- "不得修改 `animater.ts` 的类级 jsDoc(用户明确要求原样保留,即使其中「释放上一帧」措辞已成为文档债也不得改);不得在任何地方新增类级注释;不得新增 / 重命名方法或字段。"
- "不得把 `if (!x) return null` 一类提前返回当作违规去改写(dev.md 只要求并列条件用 `if/else if`);不得改动 `validateMeta` 的现有嵌套层级或结构。"
- "不得把 `object[5] !== undefined` / `object[6] !== undefined` / `item.volume !== undefined` / `item.pitch !== undefined` 改成 `isNil`(`null` 对可选原始字段必须保持非法);`isRecord` 的 `value !== null` 不得改成 `!value`(在 `typeof value === 'object'` 合取中二者不等价,会反转语义)。"
- "不得修改 `types.ts` / `index.ts` / `package.json`、其它包、根配置、锁文件或既有计划 / 摘要;不得新增依赖。"
- "不得在 `animater.ts` 保留或新增 `#region` / `#endregion`;`parse.ts` 只删除 `//#region 导出解析器` 与其 `#endregion`,保留其余 3 组功能性 region;`parse.ts` / `animater.ts` 均不得保留或新增 `// prettier-ignore`。"
- "不得新增公开 / 受保护 / 私有方法、字段或导出命名;`composeFrame` 只改签名(新增 `canvas` 参数、返回 `void`),不改名;函数内新增局部变量仅限 `angle`(animater)与既有 `reason` / `webpBlob` / `imageWidth` / `imageHeight`(parse),已报备。"
- "不得运行游戏、浏览器、dev server、`pnpm install` 或任何 git 写命令;本计划全程 0 次提交。"
open_items:
- "**OI-1(Task 0 批准)**:83 / 84 的 logger 消息保持既有文本不变;82 扩展为容器头 / 长度两类原因;86 的位图消息使用 10 个占位符(含 `$10`,已核对 `parseInfo` 支持);90 / 91 使用原因标签 + 尺寸 / 异常 message。"
- "**OI-2(Task 0 批准)**:`composeFrame` 签名由 `(texture, data, frame) => MotaOffscreenCanvas2D` 改为 `(canvas, texture, data, frame) => void`;方法名不变。"
- "**OI-3(Task 0 报备)**:`animater.ts` 新增函数内局部变量 `angle`(旋转弧度中间量,用于消除 `// prettier-ignore`);不新增方法 / 字段 / 导出。"
- "**OI-4(Task 0 报备)**:`animater.test.ts` 的测试夹具 `FakeCanvas2D` 若需记录 `size` 调用,可在测试内新增局部字段(仅测试文件);优先通过 `canvas.width` / `height` 断言逐帧尺寸,避免改动夹具。"
- "**OI-5(Task 0 报备)**:`parse.ts` 中 `'-'` 是「该槽位无值」的占位标签约定,仅出现在 logger 实参;不进入任何消息文本以外的语义。"
- "**OI-6(只记录)**:不做浏览器 E2E;单画布复用只由 `animater.test.ts` 的 fake 画布验证,不校验真实像素输出。"
- "**OI-7(只记录)**:`logger.error` 引用页编号为 `Math.floor(code / 50) + 1`(82–91 落在 `error2.html`),本计划不生成 / 不修改文档页面。"
---
<!-- planner-discipline-allow: throw -->
<!-- planner-discipline-allow: @throws -->
<!-- planner-discipline-allow: finally -->
<!-- planner-discipline-allow: try -->
<!-- planner-discipline-allow: catch -->
<!-- planner-discipline-allow: forEach -->
<!-- planner-discipline-allow: #region -->
<!-- planner-discipline-allow: #endregion -->
<!-- planner-discipline-allow: prettier-ignore -->
<!-- planner-discipline-allow: isNil -->
<!-- planner-discipline-allow: MotaOffscreenCanvas2D -->
<!-- planner-discipline-allow: logger.error(88,'metadataisnotanobject') -->
<objective>
Phase 9 · 第 56 个计划(09-55 的注释 / 日志 / 性能增量)—— 把 `@motajs/render-anim` 的 `parse.ts` 与 `animater.ts` 整理到符合 `dev.md` 的注释与 logger 规范,并修复 `sequence` 每帧新建离屏画布的真实性能缺陷。
**要解决的问题(已由用户逐条确认):**
1. `parse.ts` 中除 `parseRenderAnimation` 外的 12 个顶层函数只有单行 jsDoc,缺少 `@param` / `@returns`;关键逻辑(字节偏移、校验顺序、帧包围盒数学、先 close 再记日志)缺少有价值的行内注释。
2. `animater.ts` 的私有方法 `composeFrame`、`sequence` 只有单行 jsDoc;缺少 HD/AA 关闭、逐帧尺寸重置、变换顺序、1B 清理、为何不做兜底清理等行内注释。
3. `once` / `cycled` 上重复写了 jsDoc,但它们实现的 `ITextureAnimater` 接口已经文档化(`dev.md`:继承 / 实现的 API 注释无需变更时不应重复添加)。**类级 jsDoc 由用户亲手撰写,必须原样保留,且不得新增任何类级注释。**
4. `animater.ts` 只有 128 行却分了 3 个 `#region`,短文件不得分段。
5. `parse.ts` 的 `//#region 导出解析器` 只包住 `parseRenderAnimation` 一个函数,属于「一个函数一个段」的过细分段,需删除该 region 与其 `#endregion`(其余功能性 region 保留)。
6. `parse.ts` 的 logger 调用点把整句 / 短语当作参数传入(如 `'metadata is not an object'`、`` `bitmap ${i} is not an object` ``),消息应放在 `logger.json`,调用点只传值 / 标签 / 阶段名 / 原因串。
7. `logger.json` 的 error 82–95 中,86 / 87 / 88 / 90 / 93 共用泛化消息 `"Cannot parse animation: $1."`,重复且不可读;需合并为 **82–91** 的 10 条具体消息,删除 92–95。
8. `parse.ts` 与 `animater.ts` 各有 `// prettier-ignore`,需通过提取中间量 / 正常换行消除,不得保留。
9. `parse.test.ts` 的期望码与静态闸门、`animater.test.ts` 的画布断言都需随实现同步更新。
10. **真实设计缺陷**:`sequence` 每帧都 `new MotaOffscreenCanvas2D()`,一帧一块画布;必须改为每个序列只创建一块画布并复用,逐帧重设尺寸 / 清空。
**做法(用户决定,锁定):**
- **单画布**:`sequence` 在 `frames.length === 0` 判断之后创建唯一画布,`setHD(false)` / `setAntiAliasing(false)` 各一次;`composeFrame(canvas, texture, data, frame): void` 每帧 `canvas.size(frame.width, frame.height)` 后绘制;每帧 `yield` 同一个 `canvas.canvas`;正常结束 `clear()` + 宽高归零;提前 `.return()` 不写 `finally`,最后一帧留给 GC(用户决定 1B)。
- **logger 表**:error 段合并为 82–91,消息具体、带标签参数;`$n` 与调用点一致;不使用 `$1`-only 泛化消息;`1000+` 不新增;`warn` 段(含 `213`)逐字保留。
- **注释**:12 个顶层函数与 `composeFrame` / `sequence` 全部改多行 jsDoc(`@param` / `@returns`,无 `@throws`);补充有价值的行内注释;删除 `once` / `cycled` 的 jsDoc;保留类级 jsDoc;删除 `animater.ts` 全部 region 与 `parse.ts` 的导出 region。
- **行为不变**:`parseRenderAnimation` 仍为 `Promise<IAnimationParsedData | null>`;每个失败只记一次日志并返回 null;恰 3 处窄 `try/catch`(`JSON.parse` / `createImageBitmap` / `new Texture`),`new Blob` 与 `isRecord` / `return meta` 在 `try` 外;无 `finally`;位图越界先 close 再记日志;纹理失败先 close。
- **不做的改动**:不改类级 jsDoc、不新增类级注释、不改 early return、不改 `validateMeta` 嵌套、不把可选原始字段的 `!== undefined` 换成 `isNil`、不改 `isRecord` 的 `value !== null`(`!value` 在该合取中不等价)。
**修改方式声明(AGENTS.md):** 执行期间的全部源码、测试与 `09-56-SUMMARY.md` 写入均由**派发子代理(`gsd-executor`)执行**,非内联执行;本计划文件自身由规划流程(`gsd-planner`)创建。除 `files_modified` 外无任何写入。
**可见跳过:** spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip)。本阶段无 requirement ID,不创建 RESEARCH.md / VALIDATION.md,Nyquist 验证不适用。
</objective>
## 本计划产出物(Artifacts this plan produces)
| 类型 | 名称 / 路径 | 说明 |
|------|-------------|------|
| 改写(解析器注释 / 日志) | `packages/render-anim/src/parse.ts` | 12 个顶层函数多行 jsDoc + 行内注释 + 82–91 调用点 + 导出 region 移除 |
| 改写(合成器) | `packages/render-anim/src/animater.ts` | 单画布复用、多行 jsDoc、region 与 once/cycled jsDoc 移除、类级 jsDoc 保留 |
| 改写(解析测试) | `packages/render-anim/src/__test__/parse.test.ts` | 82–91 期望码、注释同步、静态闸门更新 |
| 改写(合成器测试) | `packages/render-anim/src/__test__/animater.test.ts` | 单画布 / 同一 source / 逐帧尺寸 / 清理语义 |
| 修改(日志表) | `packages/common/src/logger.json` | error 合并为 82–91(10 条),删除 92–95,warn 不动 |
| 交付 | `.planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md` | 文件清单、测试数量、错误码映射、行为变更说明、偏差 |
| 只验证不修改 | `packages/render-anim/src/types.ts` / `index.ts` / `package.json` | 哈希与 Task 1 基线一致 |
## 已确认问题清单(唯一依据)
| # | 文件 | 问题 | 处理 |
|---|------|------|------|
| 1 | `parse.ts` | 12 个顶层函数单行 jsDoc、缺 `@param` / `@returns` | 改多行 jsDoc;补字节偏移 / 校验顺序 / 帧数学 / close-before-log 行内注释;无 `@throws` |
| 2 | `animater.ts` | `composeFrame` / `sequence` 单行 jsDoc | 改多行 jsDoc(`sequence` 为生成器返回);补 HD/AA、逐帧尺寸、变换顺序、1B 清理、无兜底清理的注释 |
| 3 | `animater.ts` | `once` / `cycled` 重复 jsDoc | 删除这两个方法的 jsDoc(接口已文档化);**类级 jsDoc 不动** |
| 4 | `animater.ts` | 128 行文件内有 3 个 `#region` | 删除全部 `#region` / `#endregion` |
| 5 | `parse.ts` | `//#region 导出解析器` 只包一个函数 | 删除该 region 与其 `#endregion`;其余功能性 region 保留 |
| 6 | `parse.ts` | logger 调用点传整句 / 短语 | 改为只传原因标签 / 数字 / 字段名 / `'-'` / 异常 message |
| 7 | `logger.json` | 82–95 中 5 个码共用泛化 `$1` 消息 | 合并为 82–91,10 条具体消息;删除 92–95 |
| 8 | 两文件 | `// prettier-ignore` | 提取中间量 / 正常换行后删除 |
| 9 | 两个测试 | 期望码、静态闸门、画布断言未同步 | 按新实现同步,覆盖不退化 |
| 10 | `animater.ts` | 每帧新建一块离屏画布 | 每序列一块画布,逐帧 `size()` 复用 |
## 错误码合并映射(旧 → 新,唯一依据)
| 旧码 | 新码 | 触发位置(`parse.ts`) |
|------|------|------------------------|
| 82 | 82 | 容器头过短(`buffer-too-short`) |
| 85 | 82 | 头部长度不一致(`length-mismatch`) |
| 83 | 83 | 签名不匹配 |
| 84 | 84 | 版本不支持 |
| 86 | 85 | sprite 数量 < 1 / 尺寸表越界 / 单个 sprite 宽高 < 1 |
| 87 | 86 | 位图列表非数组 / 数量不匹配 / 位图项非对象 / x·y·width·height 非法 / 解码后越界 |
| 88(帧结构) | 87 | `frame` 非数组 / 帧项非对象 / `objects` 非数组 / `sound` 非数组 |
| 88(对象项非数组 / 元组 4 元 / 元组 8 元) | 88 | 对象位图条目不是 7 元组,或字段数不是 7(`not-tuple` / `invalid-field-count`) |
| 88(元数据非对象) | 90 | `readRawMeta` 的 `!isRecord` 守卫与 `validateMeta` 的纵深防御 |
| 89 | 88 | 对象位图索引越界 / 非整数 |
| 90 | 88 | 对象 x / y / scale / opacity / mirror / rotate 非法 |
| 91 | 89 | `ratio` 非法 |
| 92 | 89 | `blend` 非法 |
| 93 | 89 | 音效项非对象 / name / volume / pitch 非法 |
| 94 | 90 | 元数据 JSON 解析失败(`invalid-json`) |
| 95 | 91 | 图像解码失败(`decode-failed`)/ 纹理创建失败(`texture-failed`) |
## logger.json error 82–91 最终文本(逐字写入,唯一依据)
| code | message | 占位符数 |
|------|---------|----------|
| 82 | `Cannot parse animation: invalid container header, reason: '$1', buffer length: $2, expected length: $3.` | 3 |
| 83 | `Cannot parse animation: invalid signature 0x$1, expected 0x$2.` | 2 |
| 84 | `Cannot parse animation: unsupported version $1, expected version $2.` | 2 |
| 85 | `Cannot parse animation: invalid sprite table, reason: '$1', index: $2, sprite count: $3, width: $4, height: $5, imageDataSize: $6.` | 6 |
| 86 | `Cannot parse animation: invalid bitmap table, reason: '$1', index: $2, bitmap count: $3, sprite count: $4, x: $5, y: $6, width: $7, height: $8, image width: $9, image height: $10.` | 10 |
| 87 | `Cannot parse animation: invalid frame structure, reason: '$1', frame index: $2, frame count: $3, item index: $4.` | 4 |
| 88 | `Cannot parse animation: invalid object tuple, reason: '$1', frame index: $2, object index: $3, field: '$4', value: '$5'.` | 5 |
| 89 | `Cannot parse animation: invalid scalar field, reason: '$1', frame index: $2, sound index: $3, field: '$4', value: '$5'.` | 5 |
| 90 | `Cannot parse animation: invalid metadata, reason: '$1', size: $2 bytes.` | 2 |
| 91 | `Cannot parse animation: invalid image or texture, reason: '$1', detail: '$2'.` | 2 |
**约束:** 10 条消息两两不同;不得出现 `Cannot parse animation: $1.` 这类只含一个原因串的泛化消息;除 83 / 84 保持既有文本外,其余均为具体字段名 + 标签值。
## logger 调用点参数规范(唯一依据)
**通用规则:** 数字一律 `.toString()` 或模板字符串;原因标签全部使用小写连字符(无空格);某槽位在当前失败场景无值时传 `'-'`;音效 `name` 的值传 `typeof item.name`(避免把不可信的长名称写进日志)。
| 函数 / 场景 | 调用 |
|-------------|------|
| `readHeader` 过短 | `logger.error(82, 'buffer-too-short', data.byteLength.toString(), ANIMATION_HEADER_SIZE.toString())` |
| `readHeader` 长度不符 | `logger.error(82, 'length-mismatch', data.byteLength.toString(), (ANIMATION_HEADER_SIZE + imageDataSize + metaDataSize).toString())` |
| `readHeader` 签名 | `logger.error(83, signature.toString(16), ANIMATION_SIGNATURE.toString(16))` |
| `readHeader` 版本 | `logger.error(84, version.toString(), ANIMATION_VERSION.toString())` |
| `parseRenderAnimation` sprite 数为 0 | `logger.error(85, 'invalid-count', '-', spriteCount.toString(), '-', '-', header.imageDataSize.toString())` |
| `parseRenderAnimation` 尺寸表越界 | `logger.error(85, 'table-overflow', '-', spriteCount.toString(), '-', '-', header.imageDataSize.toString())` |
| `readSpriteDimensions` 宽高 < 1 | `logger.error(85, 'invalid-dimension', i.toString(), count.toString(), width.toString(), height.toString(), '-')` |
| `validateMeta` 位图列表非数组 | `logger.error(86, 'not-array', '-', '-', '-', '-', '-', '-', '-', '-', '-')` |
| `validateMeta` 位图数量不符 | `logger.error(86, 'count-mismatch', '-', meta.bitmaps.length.toString(), spriteCount.toString(), '-', '-', '-', '-', '-', '-')` |
| `validateMeta` 位图项非对象 | `logger.error(86, 'item-not-object', i.toString(), meta.bitmaps.length.toString(), spriteCount.toString(), '-', '-', '-', '-', '-', '-')` |
| `validateMeta` 位图 x 非法 | `logger.error(86, 'invalid-x', i.toString(), meta.bitmaps.length.toString(), spriteCount.toString(), String(bitmap.x), '-', '-', '-', '-', '-')` |
| `validateMeta` 位图 y 非法 | `logger.error(86, 'invalid-y', i.toString(), meta.bitmaps.length.toString(), spriteCount.toString(), '-', String(bitmap.y), '-', '-', '-', '-')` |
| `validateMeta` 位图 width 非法 | `logger.error(86, 'invalid-width', i.toString(), meta.bitmaps.length.toString(), spriteCount.toString(), '-', '-', String(bitmap.width), '-', '-', '-')` |
| `validateMeta` 位图 height 非法 | `logger.error(86, 'invalid-height', i.toString(), meta.bitmaps.length.toString(), spriteCount.toString(), '-', '-', '-', String(bitmap.height), '-', '-')` |
| `validateBitmapBounds` 越界 | `logger.error(86, 'out-of-bounds', i.toString(), bitmaps.length.toString(), '-', String(bitmap.x), String(bitmap.y), String(bitmap.width), String(bitmap.height), String(imageWidth), String(imageHeight))` |
| `validateMeta` frame 非数组 | `logger.error(87, 'frame-list-not-array', '-', '-', '-')` |
| `validateMeta` 帧项非对象 | `logger.error(87, 'frame-not-object', frameIndex.toString(), meta.frame.length.toString(), '-')` |
| `validateMeta` objects 非数组 | `logger.error(87, 'objects-not-array', frameIndex.toString(), meta.frame.length.toString(), '-')` |
| `validateMeta` sound 非数组 | `logger.error(87, 'sound-not-array', frameIndex.toString(), meta.frame.length.toString(), '-')` |
| `validateMeta` 对象项非数组 | `logger.error(88, 'not-tuple', frameIndex.toString(), objectIndex.toString(), '-', '-')` |
| `validateMeta` 元组字段数非法 | `logger.error(88, 'invalid-field-count', frameIndex.toString(), objectIndex.toString(), '-', object.length.toString())` |
| `validateMeta` 对象索引非法 | `logger.error(88, 'invalid-index', frameIndex.toString(), objectIndex.toString(), 'index', String(index))` |
| `validateMeta` 对象字段非法 | `logger.error(88, 'invalid-field', frameIndex.toString(), objectIndex.toString(), 'x', String(object[1]))`(`field` 取 `'x'` / `'y'` / `'scale'` / `'opacity'` / `'mirror'` / `'rotate'`,值取对应的 `object[1..6]`) |
| `validateMeta` ratio 非法 | `logger.error(89, 'invalid-ratio', '-', '-', 'ratio', String(meta.ratio))` |
| `validateMeta` blend 非法 | `logger.error(89, 'invalid-blend', '-', '-', 'blend', String(meta.blend))` |
| `validateMeta` 音效项非对象 | `logger.error(89, 'sound-not-object', frameIndex.toString(), i.toString(), '-', '-')` |
| `validateMeta` 音效 name 非法 | `logger.error(89, 'invalid-name', frameIndex.toString(), i.toString(), 'name', typeof item.name)` |
| `validateMeta` 音效 volume 非法 | `logger.error(89, 'invalid-field', frameIndex.toString(), i.toString(), 'volume', String(item.volume))` |
| `validateMeta` 音效 pitch 非法 | `logger.error(89, 'invalid-field', frameIndex.toString(), i.toString(), 'pitch', String(item.pitch))` |
| `readRawMeta` JSON 解析失败 | `logger.error(90, 'invalid-json', size.toString())` |
| `readRawMeta` 非对象 JSON | `logger.error(90, 'not-object', size.toString())` |
| `validateMeta` 纵深防御非对象 | `logger.error(90, 'not-object', '-')` |
| `parseRenderAnimation` 解码失败 | `logger.error(91, 'decode-failed', reason)` |
| `parseRenderAnimation` 纹理失败 | `logger.error(91, 'texture-failed', reason)` |
**注意:** 表中所有实参一律使用半角逗号与半角引号;未使用的数值槽传 `'-'`,不得省略参数(否则 `$n` 会落到后一个实参上)。
## `parse.ts` 注释 / jsDoc 规格(逐函数)
**总则:** 只改注释与 logger 实参,不改任何校验逻辑、循环结构、嵌套层级与函数签名(`parseRenderAnimation` 的签名与 3 处 `try/catch` 保持 09-55 现状)。每段 jsDoc 使用多行换行风格,`@param` / `@returns` 各占一行,中文说明,不以句号结尾的单行注释保持无句号;多行 jsDoc 描述可用句号。禁止 `@throws`。
| 函数 | jsDoc 内容要求 | 行内注释要求(价值型,解释为什么) |
|------|----------------|-----------------------------------|
| `isRecord` | `@param value 待判断的值`;`@returns 是否为可读取成员的普通对象` | `// 数组与 null 都不是可读取成员的普通对象`(不改 `value !== null`) |
| `isNumber` | `@param value 待判断的值`;`@returns 是否为有限数字` | `// 排除 NaN 与 Infinity,长度 / 坐标等字段必须有限` |
| `isInteger` | `@param value 待判断的值`;`@returns 是否为整数` | `// 位图索引必须是整数,小数索引无法定位位图` |
| `readHeader` | `@param data 动画文件字节视图`;`@returns 两段数据的字节长度,头部非法时返回 null` | 偏移 0 签名(大端)、偏移 4 版本(小端)、偏移 8 / 12 两段长度(小端);`// 三段长度之和必须与总长度严格相等,多一字节或少一字节都视为损坏` |
| `readSpriteDimensions` | `@param data 动画文件字节视图`;`@param count sprite 数量`;`@returns 每个 sprite 的宽高,尺寸非法时返回 null` | `// 尺寸表紧跟在 sprite 数量之后,每个 sprite 固定 8 字节(宽 + 高,小端)`;`// 宽高至少为 1,否则后续按位图裁剪会得到空区域` |
| `readRawMeta` | `@param buffer 动画文件二进制`;`@param offset 元数据段起始字节`;`@param size 元数据段字节长度`;`@returns 解析后的原始元数据,非法 JSON 或非对象时返回 null` | `// 元数据段位于头部与图像段之后,直接按 UTF-8 解码`;`// JSON 允许 primitive(42 / null / false 等),必须先确认是普通对象再交给后续校验` |
| `validateMeta` | `@param meta 原始元数据`;`@param spriteCount sprite 数量`;`@returns 元数据是否通过全部校验` | `// 先校验全局字段(ratio / blend / 位图列表),再逐项校验位图与帧,保证后续索引与包围盒计算不会越界`;`// blend 目前只接受 0(普通)与 1(加算)`;`// 音效名称可能来自不可信文件,日志只记录其类型而不是原值` |
| `validateBitmapBounds` | `@param bitmaps 位图裁剪区域`;`@param image 解码后的图像`;`@returns 所有位图是否都落在图像内` | `// 在 close() 之前捕获尺寸,close() 之后 ImageBitmap 的宽高不再可靠`;`// 先关闭位图再记录日志,确保即使日志实现抛错也不会泄漏解码资源` |
| `toObject` | `@param object 原始对象元组`;`@param ratio 动画整体缩放系数`;`@returns 运行时对象` | `// 整体缩放折入每个对象的缩放比例,运行时不再保留 ratio`;`// 可选字段缺省为 0,与运行时对象类型保持非可选` |
| `toFrame` | `@param frame 原始帧`;`@param bitmaps 已转换的位图列表`;`@param ratio 动画整体缩放系数`;`@returns 运行时帧` | `// 帧尺寸与原点由对象包围盒推导,运行时不需要再计算` |
| `computeFrameBox` | `@param objects 运行时对象列表`;`@param bitmaps 位图列表`;`@returns 帧的轴对齐包围盒` | `// 旋转 θ 后轴对齐包围盒的半宽 / 半高分别为 \|w/2·cosθ\| + \|h/2·sinθ\| 与 \|w/2·sinθ\| + \|h/2·cosθ\|`;`// 以第一个对象初始化包围盒,避免使用 ±Infinity 之类的哨兵值`;`// 空帧给 1x1,保证画布尺寸至少为 1` |
| `toBlendMode` | `@param blend 原始混合模式`;`@returns 运行时混合模式枚举` | `// 只有 1 视为加算,其余(已在校验阶段保证为 0)为普通混合` |
**`parseRenderAnimation`(保持 09-55 的 jsDoc 与实现):** 只补充行内注释(不写 `@throws`、不改 jsDoc):`// sprite 数量与尺寸表都位于图像段最前面,先把整段长度校验掉再读取 WebP`;`// webpOffset / webpSize 由图像段长度减去 sprite 数量与尺寸表得出`;`// new Blob 不涉及外部异常源,放在 try 之外`;`// 纹理创建失败时先关闭图像再记录日志,避免解码资源泄漏`。
**region 处理:** 保留 `//#region 常量与内部类型`、`//#region 读取与校验`、`//#region 帧转换与帧数学`三处功能性 region;删除 `//#region 导出解析器` 与其对应的 `//#endregion`,`parseRenderAnimation` 直接接在「帧转换与帧数学」的 `//#endregion` 之后。
**`// prettier-ignore`:** `validateBitmapBounds` 中 86 号调用改为上表的多参数形式,prettier 会自然换行,删除该注释。
## `animater.ts` 单画布与注释规格(逐方法)
**类级 jsDoc:** 原样保留(含「动画合成器,将解析后的动画逐帧合成为离屏画布」三行),**不得修改、不得新增任何类级注释**。
**`composeFrame`:**
```
private composeFrame(
canvas: MotaOffscreenCanvas2D,
texture: ITexture,
data: IAnimationParsedData,
frame: IAnimationFrame
): void
```
- 多行 jsDoc:`@param canvas 复用的离屏画布`;`@param texture 动画纹理`;`@param data 解析后的动画数据`;`@returns` 无(返回 `void`,不写 `@returns`;改为描述句「把当前帧的全部对象按顺序绘制到给定画布上」)。
- 首行 `canvas.size(frame.width, frame.height);`,行内注释:`// 复用同一块画布,逐帧重设尺寸会重置变换矩阵并清空上一帧内容`。
- 删除 `const canvas = new MotaOffscreenCanvas2D();`、`canvas.setHD(false)`、`canvas.setAntiAliasing(false)`(这三步移到 `sequence`)。
- 变换顺序行内注释:`// 先平移到帧原点,再镜像、旋转,最后按不透明度与目标矩形绘制`。
- 旋转中间量:`if (object.rotate) { const angle = (-object.rotate * Math.PI) / 180; ctx.rotate(angle); }`,删除 `// prettier-ignore`。
- 其余绘制表达式(`realWidth` / `realHeight` / `ctx.save` / `globalAlpha` / `drawImage` / `ctx.restore`)保持不变。
**`sequence`:**
```
private *sequence(
texture: ITexture,
data: IAnimationParsedData,
cycled: boolean
): Generator<ITextureRenderable, void>
```
- 多行 jsDoc:`@param texture 动画纹理`;`@param data 解析后的动画数据`;`@param cycled 是否循环播放`;`@returns 逐帧产出可渲染对象的生成器`。
- `if (frames.length === 0) return;` 之后创建唯一画布,行内注释:`// 每个序列只创建一块画布,像素素材关闭高清与抗锯齿以避免逐帧缩放模糊`;随后 `canvas.setHD(false); canvas.setAntiAliasing(false);`。
- 循环体:取 `frame` → `this.composeFrame(canvas, texture, data, frame);` → `yield { source: canvas.canvas, rect: { x: 0, y: 0, w: frame.width, h: frame.height } };` → `if (!cycled && index === frames.length - 1) break;` → `index = (index + 1) % frames.length;`。
- 循环结束后:`canvas.clear(); canvas.canvas.width = 0; canvas.canvas.height = 0;`,行内注释:`// 正常播放结束时清空并归零尺寸;提前 return 时不额外兜底,最后一帧随同一块画布交给垃圾回收`(注释不得包含英文兜底关键字,避免静态门禁误判)。
- 不写 `finally`,不写第二个 `canvas` 变量 / 不保留 `canvas = null` 逻辑。
**`once` / `cycled`:** 删除方法前的 jsDoc,保留方法体 `yield* this.sequence(texture, data, false/true);` 与签名不变。
**region:** 删除该文件全部 `//#region` 与 `//#endregion`(共 3 组 6 行),方法之间保留一个空行。
## `parse.test.ts` 改写规格
1. **期望码全部改为新映射(逐用例):**
- header:过短 `82`;签名 `83`;版本 `84`;总长度 `82`;`imageDataSize < 4` `82`;`metaDataSize = 0` `82`。
- sprite:count 0 / width 0 / height 0 / 尺寸表越界 → `85`(4 条)。
- bitmap:非数组 / 数量不符 / 项非对象 / x NaN / y NaN / width NaN / height NaN / x 负 / y 负 / width 0 / height 0 / 解码后越界 → `86`(12 条)。
- metadata 原语(`42` / `null` / `0` / `false` / `""`)→ `90`(5 条)。
- frame 结构:frame 非数组 / 帧项非对象 / objects 非数组 / sound 非数组 → `87`(4 条);对象项非数组(not-tuple)/ 元组 4 元 / 元组 8 元 → `88`(3 条)。
- 对象索引:越界 / 非整数 → `88`(2 条)。
- 对象字段:x NaN / y NaN / scale 0 / scale NaN / opacity 300 / opacity NaN / mirror NaN / rotate NaN → `88`(8 条)。
- ratio 0 / -1 / NaN、blend 2 / -1 / NaN → `89`(6 条)。
- 音效:name 空 / name 非字符串 / volume NaN / pitch NaN / 音效项非对象 → `89`(5 条)。
- 非法 JSON → `90`;解码失败 / 纹理失败 → `91`。
- 成功用例 11 条不变。
2. **注释同步:** 每个 `it` 前的一行中文注释里出现的旧码改为新码(例如「记录 94」→「记录 90」、「记录 95」→「记录 91」、「记录 87」→ 按语义改为 `86` 或 `87` / `88`,逐条对齐上表)。
3. **越界用例的明细断言:** 原断言 `calls[0][1]` 含 `exceeds the decoded image 16 x 16` 改为断言参数布局:`calls[0][1] === 'out-of-bounds'`、`calls[0][9] === '16'`、`calls[0][10] === '16'`,并保留 `bitmap.close` 被调用。
4. **非对象元数据用例:** 5 条均额外断言 `calls[0][1] === 'not-object'`(与 90 号原因标签一致)。
5. **静态闸门更新:** 保持「无 `throw` / 无 `@throws` / 恰 3 处 `try {` / 无 `finally`」,以及三处 `try` 块体与 `new Blob` 在 `try` 外的 compact 断言;把 `logger.error(88,'metadataisnotanobject')` 的 compact 断言替换为新守卫文本 `if(!isRecord(meta)){logger.error(90,'not-object',size.toString());returnnull;}returnmeta;`;继续断言 `validateMeta` / `validateBitmapBounds` 体内无 `forEach`。
6. **不弱化行为断言:** 每条失败用例仍断言 `null` + `logger.error` 恰调用一次 + 首参等于期望码;成功用例断言内容不变。
7. **arity 校验(新增):** 在测试文件顶部定义常量映射 `ERROR_PARAM_COUNTS = { 82: 3, 83: 2, 84: 2, 85: 6, 86: 10, 87: 4, 88: 5, 89: 5, 90: 2, 91: 2 }`;`expectFailure` 在保留首参码与标签 / 顺序断言的同时,断言 `loggerMock.error.mock.calls[0].length === ERROR_PARAM_COUNTS[code] + 1`(`+1` 为 code 本身)。这是 arity 校验,不是只检查码存在。
8. **compact 守卫放置:** 新 90 号守卫文本 `if(!isRecord(meta)){logger.error(90,'not-object',size.toString());returnnull;}returnmeta;` 要求 `readRawMeta` 的「JSON 允许 primitive…」注释在 `if (!isRecord(meta))` **之前**,否则 compact 断言失配。
## `animater.test.ts` 改写规格
**原则:** 每个 `it` 前保留一行中文注释;用例数量保持 9;断言从「每帧一块画布」改为「每序列一块画布」。**相关用例统一声明 `const canvas = fakes.instances[0]`,并断言 `canvas.canvas.width` / `canvas.canvas.height`(不依赖 `FakeCanvas2D` 上偶然的 `width` / `height` 转发);静态闸门与测试规格使用同一变量名。**
| # | 用例(`it` 名) | 关键断言 |
|---|-----------------|----------|
| 1 | `yields every frame once with the frame rect` | `expect(first.rect).toEqual({ x: 0, y: 0, w: 10, h: 20 })`、`expect(second.rect).toEqual({ x: 0, y: 0, w: 5, h: 6 })`、`expect(fakes.instances.length).toBe(1)`、`expect(first.source).toBe(fakes.instances[0].canvas)`、`expect(second.source).toBe(first.source)`、`expect(fakes.instances[0].highResolution).toBe(false)`、`expect(fakes.instances[0].antiAliasing).toBe(false)` |
| 2 | 恢复后复用并重设同一画布 | `const canvas = fakes.instances[0]`;`nextValue` 后 `expect(canvas.canvas.width).toBe(10)` / `expect(canvas.canvas.height).toBe(20)`;再 `nextValue` 后 `5` / `6`;`expect(fakes.instances.length).toBe(1)` |
| 3 | 正常播放结束清空并归零 | `const canvas = fakes.instances[0]`;`expect(generator.next().done).toBe(true)`;`expect(canvas.ctx.clearRect).toHaveBeenCalledTimes(1)`;`expect(canvas.canvas.width).toBe(0)` / `expect(canvas.canvas.height).toBe(0)` |
| 4 | 提前 return 保留最后一帧 | `const canvas = fakes.instances[0]`;`generator.return()`;`expect(canvas.ctx.clearRect).not.toHaveBeenCalled()`;`expect(canvas.canvas.width).toBe(10)` / `expect(canvas.canvas.height).toBe(20)` |
| 5 | cycled 回到第一帧 | 三次 `rect.w` 为 `10` / `5` / `10`;三次 `source` 全等 |
| 6 | 空帧产出 1x1 且不绘制 | `rect = {0,0,1,1}`;`ctx.drawImage` 未调用 |
| 7 | 居中变换顺序 | `save/restore` 各 1 次、`translate(21,7)`、`scale(-1,1)`、`rotate(-π/2)`、`globalAlpha = 128/255`、`drawImage(texture.source, 0,0,32,16,-32,-16,64,32)` |
| 8 | 无帧立即结束 | `once` / `cycled` 的 `next().done === true`;`expect(fakes.instances.length).toBe(0)`(画布在空帧判断之后才创建) |
| 9 | 不释放源纹理 | `expect(dispose).not.toHaveBeenCalled()` |
**夹具:** `FakeCanvas2D` 保持现有 `canvas` / `ctx` / `setHD` / `setAntiAliasing` / `size` / `clear` 结构;逐帧尺寸一律通过 `const canvas = fakes.instances[0]` 后断言 `canvas.canvas.width` / `canvas.canvas.height`,不依赖无关变量名或夹具上的额外转发字段。
## 覆盖审计(Multi-Source Coverage Audit)
| 源 | 条目 | 覆盖位置 |
|----|------|----------|
| GOAL(ROADMAP §Phase 9) | 可在浏览器中运行并验证的最小版本 | 合成器不再每帧新建画布,减少运行时分配与 GC 压力 |
| REQ | 本阶段无 requirement ID(`requirements: []`) | Nyquist 不适用(可见跳过) |
| RESEARCH | 本 run 无 RESEARCH.md | 依据 `logger.ts` / `logger.json` / `canvas2d.ts` / `dev.md` 实测 |
| CONTEXT D-01 | 增量派发,一个任务一个计划 | 本计划即该派发的唯一计划 |
| CONTEXT D-02 | 计划可累积追加 | plan 56,排在 09-01..09-55 之后(编号说明见 frontmatter) |
| CONTEXT D-03 | 执行前必须先汇报并等待「可以执行」 | Task 0(`blocking-human`),`autonomous: false` |
| CONTEXT D-04 | 新命名必须先反馈获批 | 本计划不新增生产方法 / 字段 / 导出命名;`angle` 为函数内局部变量,已在 Task 0 报备 |
| CONTEXT D-05 | 默认不逐阶段验证 | 仍做 targeted vitest / 静态门禁;不做浏览器 E2E |
| CONTEXT D-06 | 范围由用户界定 | `files_modified` 6 项 + Task 1 / Task 5 哈希门禁 |
| 用户修正 1 | 不改类级 jsDoc、不新增类级注释 | Task 4 + Task 5 静态门禁(类级 jsDoc 存在且逐字包含原描述) |
| 用户修正 2 | 提前 return 不是违规 | 计划不触碰 `if (!x) return` 结构 |
| 用户修正 3 | `validateMeta` 3 层嵌套合规 | 只改 logger 实参与注释,不改嵌套 |
| 用户修正 4 | 可选原始字段保持 `!== undefined` | Task 3 / Task 5 静态门禁 |
| 用户修正 5 | `sequence` 每帧新建画布是真实缺陷 | Task 4 单画布重构 + Task 5 静态 / 行为门禁 |
| 确认问题 1–10 | 见「已确认问题清单」 | Task 2 / 3 / 4 / 5 逐条对应 |
## 命名与注释批准清单(Task 0 逐项确认)
| 类别 | 名称 | 说明 |
|------|------|------|
| 私有方法签名(修改) | `composeFrame` | `(canvas: MotaOffscreenCanvas2D, texture: ITexture, data: IAnimationParsedData, frame: IAnimationFrame) => void`;名称不变 |
| 新增生产命名 | **无方法 / 字段 / 导出** | 仅函数内局部变量 `angle`(animater) |
| 既有注释删除 | `animater.ts` 的 `once` / `cycled` jsDoc | 接口 `ITextureAnimater` 已文档化(dev.md) |
| 既有注释删除 | `animater.ts` 的 3 组 `#region` / `#endregion` | 128 行短文件不得分段 |
| 既有注释删除 | `parse.ts` 的 `//#region 导出解析器` 与其 `#endregion` | 单函数分段过细;其余 3 个功能性 region 保留 |
| 既有注释改写 | `parse.ts` 12 个顶层函数 jsDoc | 单行 → 多行 + `@param` / `@returns`;无 `@throws` |
| 既有注释改写 | `animater.ts` 的 `composeFrame` / `sequence` jsDoc | 单行 → 多行;`sequence` 描述生成器返回 |
| **保持原样** | `animater.ts` 类级 jsDoc | 用户亲手撰写,逐字保留 |
| 日志表改写 | error `82`–`91` | 文本见「logger.json error 82–91 最终文本」;删除 `92`–`95` |
| 测试局部命名(报备) | 无新增;沿用 `loggerMock` / `parseOk` / `expectFailure` 等 | 仅测试文件 |
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/09-minimum-browser-runnable/09-CONTEXT.md
@AGENTS.md
@dev.md
@packages/render-anim/src/parse.ts
@packages/render-anim/src/animater.ts
@packages/render-anim/src/__test__/parse.test.ts
@packages/render-anim/src/__test__/animater.test.ts
@packages/render-anim/src/types.ts
@packages/render-anim/src/index.ts
@packages/render-anim/package.json
@packages/common/src/logger.ts
@packages/common/src/logger.json
@packages/render/src/core/canvas2d.ts
@packages/render/src/assets/types.ts
@.planning/phases/09-minimum-browser-runnable/09-55-PLAN.md
@.planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md
@.prettierrc
@eslint.config.js
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 预执行汇报关卡 —— 汇报注释 / jsDoc 清单、82–91 logger 表、单画布改动、测试更新预期与明确不改项,等待恰好「可以执行」</name>
<dependencies>无(本任务就是批准关卡,只依赖用户针对本计划的「可以执行」回复)</dependencies>
<precondition>`packages/render-anim/src/parse.ts` 仍是 09-55 的实现(82–95 调用点、含 `//#region 导出解析器` 与 `// prettier-ignore`);`animater.ts` 仍是 128 行、3 组 region、每帧 `new MotaOffscreenCanvas2D()`;`packages/common/src/logger.json` 的 error 段为 `1..81` + `82..95` + `2001..2008`;两个测试文件分别有 70 / 9 个用例;`node_modules` 内 vitest / prettier / eslint / vue-tsc 均存在。</precondition>
<files>无(本任务只读,不写任何文件;汇报后停下等待「可以执行」)</files>
<read_first>
- `.planning/phases/09-minimum-browser-runnable/09-CONTEXT.md`(D-01 增量派发、D-03 汇报关卡、D-04 命名批准、D-06 范围界定)
- `AGENTS.md`(执行前须获批、既有注释不得擅自修改、最小修改也走 GSD、GSD 流程豁免范围)
- `dev.md`(第 75 行「继承 / 实现的 API 注释无需变更时不重复添加」、CRLF、4 空格、首行 import、短文件不分段、方法 jsDoc 换行风格、不建议 try-catch、「不建议」视为「不得」)
- `packages/render-anim/src/parse.ts`(574 行现状:12 个单行 jsDoc 顶层函数、`//#region 导出解析器`、`// prettier-ignore`、整句 logger 参数)
- `packages/render-anim/src/animater.ts`(128 行现状:类级 jsDoc、3 组 region、`once` / `cycled` 的 jsDoc、`composeFrame` 每帧 `new MotaOffscreenCanvas2D()`、`// prettier-ignore`)
- `packages/render-anim/src/__test__/parse.test.ts`(70 个用例;静态闸门硬编码 `logger.error(88,'metadataisnotanobject')`、断言 3 处 `try`)
- `packages/render-anim/src/__test__/animater.test.ts`(9 个用例;断言 `fakes.instances.length === 2`)
- `packages/common/src/logger.json`、`packages/common/src/logger.ts`(`parseInfo` 多位占位符)
- `packages/render/src/core/canvas2d.ts`(`size()` / `setHD()` / `clear()` 语义)、`packages/render/src/assets/types.ts`(`ITextureAnimater` 的 `once` / `cycled` jsDoc)
- 本计划的「已确认问题清单」「错误码合并映射」「logger.json error 82–91 最终文本」「logger 调用点参数规范」「`parse.ts` 注释 / jsDoc 规格」「`animater.ts` 单画布与注释规格」「两个测试规格」「命名与注释批准清单」
</read_first>
<what-built>
一份待批准的整理 + 性能修复计划(`09-56-PLAN.md`):为 `parse.ts` 的 12 个顶层函数补多行 jsDoc 与行内注释、把 logger 调用点改为只传标签 / 值并把 error 82–95 合并为 82–91;为 `animater.ts` 删除短文件的 region 与 `once` / `cycled` 的重复 jsDoc、补 `composeFrame` / `sequence` 的多行 jsDoc 与行内注释,并把 `sequence` 改为每个序列只创建一块画布逐帧复用。只改 6 个路径、0 提交。
</what-built>
<action>
**停下并向用户汇报,等待其恰好回复「可以执行」后才继续;本任务不写任何文件、不建目录、不派发执行子代理。**
① **要做什么 / 为什么:** `parse.ts` 有 12 个顶层函数只有单行 jsDoc,缺少 `@param` / `@returns` 与解释性注释;logger 调用点把整句英文当作参数传入,且 error 86 / 87 / 88 / 90 / 93 共用泛化消息 `"Cannot parse animation: $1."`,重复且不可读。`animater.ts` 只有 128 行却分了 3 个 region,`once` / `cycled` 重复了接口已有的 jsDoc,并且 `sequence` **每帧都新建一块 `MotaOffscreenCanvas2D`**,这是真实的分配 / GC 缺陷。本计划做三件事:注释规范化、logger 表合并、单画布复用。
② **注释 / jsDoc 清单(逐字确认):**
- `parse.ts` 12 个顶层函数(`isRecord` / `isNumber` / `isInteger` / `readHeader` / `readSpriteDimensions` / `readRawMeta` / `validateMeta` / `validateBitmapBounds` / `toObject` / `toFrame` / `computeFrameBox` / `toBlendMode`)全部改多行 jsDoc,带 `@param` / `@returns`,**不写 `@throws`**;补充字节偏移(签名 0 / 版本 4 / 两段长度 8 与 12 / sprite 数量 16 / 尺寸表 20 + i×8)、校验顺序、帧包围盒半宽半高公式、先 close 再记日志等行内注释。
- `animater.ts` 的 `composeFrame` 改多行 jsDoc(4 个 `@param`)并描述把当前帧绘制到给定画布;`sequence` 改多行 jsDoc(3 个 `@param`)并说明逐帧产出可渲染对象的生成器。
- **删除** `once` / `cycled` 的 jsDoc(`ITextureAnimater` 接口已文档化,dev.md 第 75 行)。
- **类级 jsDoc 原样保留,且不新增任何类级注释。**
- 删除 `animater.ts` 全部 3 组 `#region` / `#endregion`;删除 `parse.ts` 的 `//#region 导出解析器` 与其 `//#endregion`(保留其余 3 个功能性 region)。
- 删除两个文件的 `// prettier-ignore`(86 号多参数调用自然换行;`ctx.rotate` 提取 `angle` 中间量)。
③ **logger 表 82–91(逐字确认):** error 段合并为 10 条具体消息(82 容器头 / 长度、83 签名、84 版本、85 sprite 表 / 数量 / 尺寸 / 越界、86 位图表 / 数量 / 项 / 边界、87 帧结构、88 对象元组结构与字段、89 ratio / blend / 音效字段、90 元数据 JSON / 对象、91 解码 / 纹理);删除 92–95。文本逐字见「logger.json error 82–91 最终文本」表(例如 82 为 `Cannot parse animation: invalid container header, reason: '$1', buffer length: $2, expected length: $3.`;86 使用到 `$10`,已核对 `parseInfo` 支持多位占位符)。**不使用 `$1`-only 泛化消息**;`1..81`、`2001..2008`、整个 `warn` 段(含并发 `213` 与既有 `1001`)逐字保留;不新增任何 `1000+` 码。
④ **logger 调用点(逐条确认):** 全部改为只传小写连字符原因标签、数字字符串、字段名标签、`'-'` 占位或 91 的异常 `message` 变量;具体实参见「logger 调用点参数规范」表。音效名称只传 `typeof item.name`,避免把不可信长名称写进日志。
⑤ **单画布设计(行为 / 性能变更,用户决定 1B):** `sequence` 在 `frames.length === 0` 判断之后只创建一块 `MotaOffscreenCanvas2D`,`setHD(false)` / `setAntiAliasing(false)` 各一次;`composeFrame` 签名改为 `(canvas, texture, data, frame): void`,每帧先 `canvas.size(frame.width, frame.height)`(重设尺寸即重置变换并清空上一帧)再绘制,内部不再构造画布;每帧 `yield` 同一个 `canvas.canvas`,`rect` 仍为 `{ x: 0, y: 0, w: frame.width, h: frame.height }`;正常结束 `canvas.clear()` + 宽高归零;提前 `.return()` **不加 `finally`**,最后一帧留在同一画布交给 GC。
⑥ **明确不做的改动(用户修正):**
- 不改 `animater.ts` 类级 jsDoc,不新增类级注释。**记录文档债:** 类级 jsDoc 里「每次 `.next()` 恢复后会释放上一帧」的旧措辞在单画布复用后已不再准确(现在复用同一块画布、不逐帧释放),但按用户要求逐字保留;这是已知文档债,未经用户另行批准不得改写。
- 不新增 / 不重命名任何方法、字段或导出;`composeFrame` 只改签名(新增 `canvas` 参数、返回 `void`),`sequence` / `once` / `cycled` 名称与既有成员集合保持不变。
- 不把 `if (!x) return null` 一类提前返回当作违规改写(dev.md 只要求并列条件用 `if/else if`)。
- 不改 `validateMeta` 的 3 层嵌套与结构。
- 不把 `object[5] !== undefined` / `object[6] !== undefined` / `item.volume !== undefined` / `item.pitch !== undefined` 改为 `isNil`(`null` 对可选原始字段必须保持非法)。
- 不改 `isRecord` 的 `value !== null`:在 `typeof value === 'object'` 合取中 `!value` 会反转语义(只对 `null` 为真),不等价,故保持原写法。
- 不改 `parseRenderAnimation` 的签名、jsDoc、3 处窄 `try/catch`、无 `throw`、位图越界先 close 再记日志、纹理失败先 close。
- 不改 `types.ts` / `index.ts` / `package.json` / 其它包 / 配置 / 锁文件 / 既有计划与摘要。
⑦ **测试更新预期:** `parse.test.ts` 的期望码按「旧 → 新」映射全部改为 82–91(header 82/83/84;sprite 85;bitmap 86;metadata 原语 90;frame 结构 87 与对象元组 88;对象索引 / 字段 88;ratio / blend / 音效 89;非法 JSON 90;解码 / 纹理 91),同步每个 `it` 前的注释,越界用例改断言 `[1] === 'out-of-bounds'`、`[9] === '16'`、`[10] === '16'`,静态闸门把 `logger.error(88,'metadataisnotanobject')` 的断言换成新的 90 号守卫文本并继续断言 3 处 `try`;**并新增错误码 82–91 → 占位符数量(3/2/2/6/10/4/5/5/2/2)的常量映射,`expectFailure` 额外断言 `loggerMock.error.mock.calls[0].length === count + 1`,校验 arity 而不只是码存在**;`animater.test.ts` 改为每序列 1 个 `FakeCanvas2D`、跨帧同一 `source`、逐帧 `canvas.canvas.width/height`(测试内统一 `const canvas = fakes.instances[0]`)、正常结束 clear + 归零、提前 return 保留 10×20、空帧时 0 个实例、变换参数、不释放源纹理。**实测基线为 70 个 parse 用例 + 9 个 animater 用例 = 79 passed;79 是合计,不是 parse 用例数;此前规划输入曾误写成 79 parse,本计划以实测 70 + 9 为准,改写后 parse 不得少于 70、animater 必须为 9。**
⑧ **门禁形态:** targeted vitest(两个测试文件)、prettier `--check`(5 个改动文件)、eslint(两个源码 + 两个测试)、CRLF / BOM / tab、过滤 `packages[\\/]render-anim` 的 `vue-tsc --noEmit --incremental false`(Windows 反斜杠也匹配;参数被拒时回退并清理生成的 `*.tsbuildinfo`),以及静态门禁(animater 无 region、无 once/cycled jsDoc、类级 jsDoc 与 Task 1 全块快照逐字一致且文件恰有 3 个 `/**` 块、成员名集合与 Task 1 快照一致、parse 无导出 region、两文件无 `// prettier-ignore`、无整句 logger 字面量、无 92–95、logger 82–91 两两不同且非 `$1`-only、可选字段仍用 `!== undefined`、animater 仅一处 `new MotaOffscreenCanvas2D` 且位于 `sequence`、`composeFrame` 内不构造画布、无 `finally`、parse 必需行内注释子串存在、12 个 jsDoc 与 `function <name>` 之间只有空白)。**不做浏览器 E2E,不跑游戏 / dev server / 真实 WebP 素材。**
⑨ **影响范围:** 只写 `packages/render-anim/src/parse.ts`、`animater.ts`、`__test__/parse.test.ts`、`__test__/animater.test.ts`、`packages/common/src/logger.json` 与 `09-56-SUMMARY.md`;`types.ts` / `index.ts` / `package.json` 只验证不改;不执行 git 写命令,**0 次提交**。
⑩ **等待批准:** 请确认以上内容后,回复恰好四个字「可以执行」。任何修改意见(尤其 82–91 消息文本、`composeFrame` 签名、删除 `once` / `cycled` jsDoc)请直接说明;未收到「可以执行」之前不开始 Task 1–6 的任何一步。
</action>
<verify>用户针对本计划恰好回复「可以执行」后才进入 Task 1–6;在此之前不执行 Task 1 / Task 2 / Task 3 / Task 4 / Task 5 / Task 6 的任何一步,也不派发执行子代理。</verify>
<fails_when>在用户回复「可以执行」之前执行了 Task 1–6 的任何一步、写入了任何文件,或派发了执行子代理;或汇报遗漏了 ①–⑩ 中任一项(注释清单、82–91 表、调用点参数、单画布设计、明确不改项、测试更新、门禁、范围、0 提交)。</fails_when>
<how-to-verify>
逐条核对 ①–⑩ 是否与你的意图一致,重点是:② 的 12 个函数 jsDoc 与 region / `// prettier-ignore` 删除、类级 jsDoc 保留;③ 的 82–91 十条消息逐字文本、删除 92–95、`warn`(含 213 / 1001)保留;④ 调用点只传标签 / 值(含 86 的 10 参数布局与 `'-'` 占位);⑤ 单画布与「正常结束 clear + 归零、提前 return 保留最后一帧、不加 finally」;⑥ 明确不改项(含类级 jsDoc 文档债与成员名不变);⑦ 测试期望码与静态闸门更新、70 + 9 的基线说明、arity 映射;⑧ 门禁形态(不做浏览器 E2E);⑨ 6 个写入路径与 0 提交。
</how-to-verify>
<resume-signal>请在确认本计划(尤其是 ③ 的 82–91 消息文本、④ 的 86 号 10 参数布局、⑤ 的单画布清理语义、⑥ 的明确不改项)后,回复恰好四个字「可以执行」。任何修改意见请直接说明。</resume-signal>
<done>已完整汇报 ①–⑩(注释 / jsDoc 清单、82–91 logger 表与调用点参数、单画布设计、明确不改项(含文档债与成员名不变)、测试更新预期与 70 + 9 基线说明、门禁形态、影响范围与 0 提交),并收到用户针对本计划的「可以执行」回复。</done>
<acceptance_criteria>
- 已向用户逐条汇报 ①–⑩,包含完整 82–91 错误码表(不是只说「合并错误码」)与 86 号 10 参数布局。
- 已明确说明「不改类级 jsDoc、不新增类级注释、不改提前返回、不改 `validateMeta` 嵌套、可选原始字段保持 `!== undefined`、`isRecord` 保持 `value !== null`」,并记录类级 jsDoc 中「每次 `.next()` 恢复后会释放上一帧」为单画布复用后的**文档债**(未经另行批准不改写)。
- 已明确说明不新增 / 不重命名方法或字段:`composeFrame` 只改签名,`sequence` / `once` / `cycled` 不变。
- 已明确说明 `parse.test.ts` 新增 82–91 → 占位符数量映射,并由 `expectFailure` 断言 `calls[0].length === count + 1`(校验 arity)。
- 已明确说明单画布设计:每序列一块、逐帧 `size()`、同一 `source`、正常结束 clear + 归零、提前 return 保留最后一帧且不加 `finally`。
- 已明确说明删除 `once` / `cycled` jsDoc 的依据(`ITextureAnimater` 已文档化,dev.md 第 75 行)。
- 已明确说明实测基线为 70 个 parse 用例 + 9 个 animater 用例 = 79 passed;79 是合计,不是 parse 用例数;此前规划输入曾误写成 79 parse,本计划以实测 70 + 9 为准。
- 已明确说明影响范围(6 个写入路径、`types.ts` / `index.ts` / `package.json` 只验证、0 提交)与门禁形态。
- 用户针对本计划明确回复「可以执行」后才进入 Task 1–6;在此之前未执行任何任务、未派发执行子代理。
</acceptance_criteria>
</task>
<task type="auto">
<name>Task 1: 读取 `dev.md` / AGENTS.md / 当前实现 / 日志契约 / 画布语义,采集状态与哈希基线(只读,临时文件仅写 TEMP)</name>
<dependencies>Task 0(汇报关卡已通过,批准效力覆盖本流程 Task 1–6)</dependencies>
<files>无(本任务只读仓库文件;只在 `process.env.TEMP` 目录写基线临时文件,不写仓库内任何文件)</files>
<read_first>
- `AGENTS.md`、`dev.md`(既有注释不得擅自修改、短文件不分段、方法 jsDoc 换行风格、继承 API 不重复注释、不建议 try-catch、CRLF、4 空格、首行 import)
- `packages/render-anim/src/parse.ts`(574 行现状:12 个单行 jsDoc、`//#region 导出解析器`、`// prettier-ignore`、整句 logger 参数、82–95 调用点)
- `packages/render-anim/src/animater.ts`(128 行现状:类级 jsDoc、3 组 region、`once` / `cycled` jsDoc、每帧 `new MotaOffscreenCanvas2D()`)
- `packages/render-anim/src/__test__/parse.test.ts`(70 个用例、`expectFailure`、静态闸门)
- `packages/render-anim/src/__test__/animater.test.ts`(9 个用例、`FakeCanvas2D`、`fakes.instances` 断言)
- `packages/common/src/logger.ts`(`parseInfo` 的多位占位符处理、`error(code, ...params: string[])`)
- `packages/common/src/logger.json`(error `1..81` + `82..95` + `2001..2008`;warn `1..213` + `1001`)
- `packages/render/src/core/canvas2d.ts`(`size()` 重置尺寸与变换、`setHD()` 重新 `size()`、`clear()`)
- `packages/render/src/assets/types.ts`(`ITextureAnimater.once` / `cycled` 的 jsDoc 与 `@param`)
- `packages/render-anim/src/types.ts`、`index.ts`、`package.json`(只验证)
- 本计划的「已确认问题清单」「错误码合并映射」「logger.json error 82–91 最终文本」「logger 调用点参数规范」「两个测试规格」
</read_first>
<action>
本任务不写仓库内文件,只读取并记录。
1. 读取并记录 `logger.error` 签名 `(code: number, ...params: string[])`;确认 `parseInfo` 会连续读取数字直到非数字,`$10` 可正确替换。记录 `logger.ts` 顶层 DOM 探测以 `typeof document !== 'undefined' && typeof main !== 'undefined'` 为条件,Node 下安全。
2. 记录 `parse.ts` 现状:12 个顶层函数各自的单行 jsDoc 原文(逐字抄录,作为 Task 3 改写前对照);`//#region` 四组名称与行号;`// prettier-ignore` 所在函数;全部 `logger.error` 调用点(码 + 实参形态),确认 82–95 均有调用点、86 / 87 / 88 / 90 / 93 传的是整句。
3. 记录 `animater.ts` 现状:类级 jsDoc 全文(**用 Node 从文件程序化切片写入** `(process.env.TEMP||'.') + '/gsd-09-56-class-jsdoc.txt'`,UTF-8 无 BOM:取 `animater.ts` 首个 `/**` 到其后第一个 `*/` 的整段,即类级 jsDoc;**禁止在 PowerShell 双引号命令里粘贴含反引号(`` ` ``)的字面量**,PowerShell 会把反引号当转义符吞掉,导致 Node 收到的文本与文件中不一致;整套 Task 1 快照、Task 4 / Task 5 全块比对都基于该切片文件,构造方式统一);3 组 region 名称;`once` / `cycled` 的 jsDoc 全文;`composeFrame` / `sequence` 的单行 jsDoc;`new MotaOffscreenCanvas2D()` 仅出现 1 次且在 `composeFrame` 内;`// prettier-ignore` 所在行。同时把类内声明的成员名(去重排序)写入 `(process.env.TEMP||'.') + '/gsd-09-56-members.txt'`(用 `^ {4}(?:(?:private|protected|public|static|async|readonly)\s+)*\*?([A-Za-z_$][\w$]*)\s*[\(=:]` 配 `gm` 提取,只取类体 4 空格缩进的成员,避免误取方法体里的 `source:` / `rect:`;当前应为 `composeFrame` / `cycled` / `once` / `sequence` 四个),作为 Task 4 / Task 5 的「无新增 / 重命名成员」基线。
4. 记录两个测试现状:`parse.test.ts` 70 个 `it`、`expectFailure`、越界用例的 `exceeds the decoded image 16 x 16` 断言、静态闸门的 5 条 compact 断言与 `logger.error(88,'metadataisnotanobject')`;`animater.test.ts` 9 个 `it`、`fakes.instances.length === 2` 断言、`instanceOf` 辅助。
5. 采集 **范围基线**:用 `node` 把当前 `git status --porcelain -uall`(统一 LF)写入 `(process.env.TEMP||'.') + '/gsd-09-56-status.txt'`(UTF-8 无 BOM),回显绝对路径,并立即断言与当前输出一致。基线必须**逐行精确包含**以下 6 条(不是只做文件-vs-当前相等):
- ` M packages/common/src/logger.json`
- `?? packages/render-anim/src/parse.ts`
- `?? packages/render-anim/src/animater.ts`
- `?? packages/render-anim/src/__test__/parse.test.ts`
- `?? packages/render-anim/src/__test__/animater.test.ts`
- `?? .planning/phases/09-minimum-browser-runnable/09-56-PLAN.md`
6. 采集 **哈希基线**:对 9 个路径逐个 `git hash-object`,写入 `(process.env.TEMP||'.') + '/gsd-09-56-hashes.txt'`(UTF-8 无 BOM),格式「路径 + 空格 + 40 位哈希」:`packages/render-anim/src/parse.ts`、`packages/render-anim/src/animater.ts`、`packages/render-anim/src/__test__/parse.test.ts`、`packages/render-anim/src/__test__/animater.test.ts`、`packages/common/src/logger.json`、`packages/render-anim/src/types.ts`、`packages/render-anim/src/index.ts`、`packages/render-anim/package.json`、`.planning/phases/09-minimum-browser-runnable/09-56-PLAN.md`。**Task 6 比对时会排除 `09-56-PLAN.md`**(规划 / 修订流程可能写计划文件),只要求其余 8 条中恰好 5 个目标文件变化、3 个只读文件不变。
7. 采集 **logger 快照基线**:把 `packages/common/src/logger.json` 原文复制为 `(process.env.TEMP||'.') + '/gsd-09-56-logger-baseline.json'`(仅复制,不解析重排)。
8. 断言现状(任一不符,停下上报,不得继续 Task 2):
- `parse.ts` 含 4 处 `//#region`、1 处 `// prettier-ignore`、含 `'metadata is not an object'` 字面量、含 `Promise<IAnimationParsedData | null>` 与 3 处 `try {`。
- `animater.ts` 含 3 组 region、`composeFrame` 内有 `new MotaOffscreenCanvas2D()`、`once` / `cycled` 前有 jsDoc、类级 jsDoc 含「动画合成器,将解析后的动画逐帧合成为离屏画布」。
- `logger.json` 的 `error['92']`..`error['95']` 存在、`warn['213']` 与 `warn['1001']` 为非空字符串、`error['81']` / `error['2001']` / `error['2008']` 存在。
- `types.ts` / `index.ts` / `package.json` 存在且未被本任务改动。
9. 记录工具链事实:`node --version`;`node_modules/vitest/vitest.mjs`、`prettier/bin/prettier.cjs`、`eslint/bin/eslint.js`、`vue-tsc/bin/vue-tsc.js` 均存在;并记录基线测试结果 `node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts packages/render-anim/src/__test__/animater.test.ts`(规划日为 70 + 9 = 79 passed;browserslist 的 stderr 提示属正常,按退出码判定)。
</action>
<verify>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const p=(process.env.TEMP||'.')+'/gsd-09-56-status.txt';const rd=s=>s.replace(/\r\n/g,'\n').replace(/^\n+|\n+$/g,'');const base=rd(fs.readFileSync(p,'utf8'));const now=rd(execSync('git status --porcelain -uall',{encoding:'utf8'}));const need=[' M packages/common/src/logger.json','?? packages/render-anim/src/parse.ts','?? packages/render-anim/src/animater.ts','?? packages/render-anim/src/__test__/parse.test.ts','?? packages/render-anim/src/__test__/animater.test.ts','?? .planning/phases/09-minimum-browser-runnable/09-56-PLAN.md'];const miss=need.filter(l=>base.split('\n').indexOf(l)===-1);if(base!==now||miss.length){console.error('baseline drift or missing entries: '+miss.join(' | '));process.exit(1);}console.log('OK: status baseline matches current tree and contains all 6 required entries');"</automated>
<fails_when>基线文件与当前 `git status --porcelain -uall` 不一致,或缺少 6 条必需条目中的任一条(打印 `baseline drift` / 缺失条目,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const BT=String.fromCharCode(96);const f=(process.env.TEMP||'.')+'/gsd-09-56-class-jsdoc.txt';const s=fs.readFileSync(f,'utf8').replace(/\r\n/g,'\n');const need=['/**','动画合成器,将解析后的动画逐帧合成为离屏画布','每次 '+BT+'.next()'+BT+' 恢复后会释放上一帧','提前 '+BT+'.return()'+BT+' 会跳过正常结束路径','*/'];const miss=need.filter(n=>s.indexOf(n)===-1);if(miss.length||s.trim().length<40){console.error('class jsDoc snapshot incomplete: '+miss.join(' | '));process.exit(1);}console.log('OK: full class jsDoc block snapshotted');"</automated>
<fails_when>类级 jsDoc 快照为空、缺少 `/**` / `*/` 或三句正文中的任一句(打印缺失项,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const s=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-56-members.txt','utf8').replace(/\r\n/g,'\n').split('\n').map(x=>x.trim()).filter(Boolean).sort();const exp=['composeFrame','cycled','once','sequence'];if(JSON.stringify(s)!==JSON.stringify(exp)){console.error('members='+JSON.stringify(s));process.exit(1);}console.log('OK: member baseline is composeFrame/sequence/once/cycled');"</automated>
<fails_when>成员名基线不是恰好 `composeFrame` / `cycled` / `once` / `sequence` 四个(打印实际集合,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const s=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-56-hashes.txt','utf8').replace(/\r\n/g,'\n').trim().split('\n').filter(Boolean);const ok=s.length===9&&s.every(l=>{const a=l.split(' ');return a.length===2&&a[1].length===40&&!/[^0-9a-f]/.test(a[1]);});if(!ok){console.error(s.join('\n'));process.exit(1);}console.log('OK: 9 hash baselines');"</automated>
<fails_when>哈希基线不是 9 行,或任一行不是「无空格路径 + 40 位小写十六进制」(打印内容,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-56-logger-baseline.json','utf8'));const fail=[];if(!j.error||!j.warn)fail.push('missing sections');for(const c of ['81','82','95','2001','2008'])if(j.error[c]===undefined)fail.push('error '+c+' missing');if(typeof j.warn['213']!=='string')fail.push('warn 213 missing');if(j.warn['1001']===undefined)fail.push('warn 1001 missing');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: logger snapshot has 82..95 pre-merge, 81 / 2001 / 2008, warn 213 / 1001');"</automated>
<fails_when>快照缺少 error 81 / 82 / 95 / 2001 / 2008,或缺少 warn 213 / 1001(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const p=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const a=fs.readFileSync('packages/render-anim/src/animater.ts','utf8');const fail=[];const region=(p.match(/#region/g)||[]).length;if(region!==4)fail.push('parse.ts regions='+region+', expected 4');if((p.match(/#endregion/g)||[]).length!==4)fail.push('parse.ts endregions mismatch');if(p.indexOf('// prettier-ignore')===-1)fail.push('parse.ts prettier-ignore missing');if(p.indexOf('metadata is not an object')===-1)fail.push('parse.ts sentence param missing');if(p.indexOf('Promise<IAnimationParsedData | null>')===-1)fail.push('nullable signature missing');if((p.match(/try\s*\{/g)||[]).length!==3)fail.push('parse.ts try count mismatch');if((a.match(/#region/g)||[]).length!==3)fail.push('animater.ts region count mismatch');if(a.indexOf('new MotaOffscreenCanvas2D()')===-1)fail.push('animater.ts canvas construction missing');if(a.indexOf('动画合成器')===-1)fail.push('class jsDoc missing');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: pre-change state matches assumptions');"</automated>
<fails_when>`parse.ts` 不是 4 组 region / 含 `// prettier-ignore` / 含整句参数 / 可空签名与 3 处 `try` 之一不符,或 `animater.ts` 不是 3 组 region / 含画布构造 / 类级 jsDoc 缺失(打印原因,退出码 1)——状态与计划不符须停下上报。</fails_when>
<automated>node -e "const fs=require('fs');const need=['packages/render-anim/src/types.ts','packages/render-anim/src/index.ts','packages/render-anim/package.json','packages/render/src/core/canvas2d.ts','packages/render/src/assets/types.ts','node_modules/vitest/vitest.mjs','node_modules/prettier/bin/prettier.cjs','node_modules/eslint/bin/eslint.js','node_modules/vue-tsc/bin/vue-tsc.js'];const miss=need.filter(f=>!fs.existsSync(f));if(miss.length){console.error('missing: '+miss.join(', '));process.exit(1);}console.log('OK: files and toolchain present');"</automated>
<fails_when>只读参考文件或工具链缺失(打印缺失列表,退出码 1)。</fails_when>
<automated>node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts packages/render-anim/src/__test__/animater.test.ts</automated>
<fails_when>退出码非 0,或输出未报告 79 passed(70 parse + 9 animater);browserslist 的 stderr 提示属正常,不作为失败依据。</fails_when>
</verify>
<acceptance_criteria>
- 已逐字记录 `parse.ts` 12 个单行 jsDoc、4 组 region、`// prettier-ignore`、全部 logger 调用点(含整句参数)与可空签名 / 3 处 `try`。
- 已逐字记录 `animater.ts` 类级 jsDoc 全块(写入 TEMP 快照文件)与成员名基线(`composeFrame` / `cycled` / `once` / `sequence`)、3 组 region、`once` / `cycled` jsDoc、`composeFrame` / `sequence` 单行 jsDoc、唯一一处 `new MotaOffscreenCanvas2D()`。
- 已记录两个测试的 70 / 9 用例结构、越界明细断言、静态闸门文本与 `fakes.instances.length === 2` 断言。
- `(process.env.TEMP||'.')/gsd-09-56-status.txt`(含 6 条必需条目)、`gsd-09-56-hashes.txt`(9 行)、`gsd-09-56-logger-baseline.json`、`gsd-09-56-class-jsdoc.txt`、`gsd-09-56-members.txt` 均已生成并通过门禁。
- 已记录 `layout` / `size()` / `setHD()` / `clear()` 语义与 `ITextureAnimater` 的接口 jsDoc;基线 vitest 为 79 passed。
- 任一现状断言不符已停下上报,未继续 Task 2。
</acceptance_criteria>
<done>已记录注释 / jsDoc / region / logger 调用点 / 画布语义 / 测试结构现状;TEMP 下的状态基线、9 行哈希基线、logger 快照基线均已生成并通过门禁;基线 vitest 79 passed;任一不符已停下上报。</done>
</task>
<task type="auto">
<name>Task 2: 合并 `logger.json` error 82–95 → 82–91(10 条具体消息,删除 92–95,warn 段逐字保留)</name>
<dependencies>Task 1(基线快照与哈希已就绪)</dependencies>
<files>packages/common/src/logger.json</files>
<read_first>
- 本计划的「logger.json error 82–91 最终文本」「错误码合并映射」「logger 调用点参数规范」(唯一内容依据)
- `packages/common/src/logger.json`(当前 error 82–95 与 warn 段)
- `packages/common/src/logger.ts`(`parseInfo` 的 `$n` 替换、未命中码转调 16)
- `dev.md`(CRLF、4 空格、JSON 不得引入注释)
</read_first>
<action>
本任务只改 `packages/common/src/logger.json`。
1. 把 error 段 82–95 的 14 条整体替换为 82–91 的 10 条,顺序 82→91,文本严格使用「logger.json error 82–91 最终文本」表,逐字一致(含 `reason: '$1'` 的引号、冒号、逗号、句号与空格)。缩进 8 个空格、行尾逗号与现有风格一致。
2. 删除 92–95 四行;不得保留空行或重复键。
3. 83 / 84 文本保持既有不变(`invalid signature 0x$1, expected 0x$2.` / `unsupported version $1, expected version $2.`);82 改为容器头原因式;85–91 使用「原因标签 + 字段值」布局。**不得出现 `Cannot parse animation: $1.` 这类泛化消息。**
4. `$n` 与「logger 调用点参数规范」一致:82=3、83=2、84=2、85=6、86=10、87=4、88=5、89=5、90=2、91=2;消息中不得出现未使用的 `$n`,也不得出现超出实参数目的占位。
5. 不改动 error 段 `1..81`、`2001..2008`,不改动整个 `warn` 段(含 `213` 与 `1001`);不新增 `1000+` 码。
6. 不碰 `parse.ts` / `animater.ts` / 测试 / SUMMARY / 其它包或配置。
</action>
<verify>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const fail=[];for(let c=82;c<=91;c++){if(typeof j.error[c]!=='string'||j.error[c].length<20)fail.push('missing or short error '+c);}for(let c=92;c<=95;c++){if(j.error[c]!==undefined)fail.push('error '+c+' still present');}if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: error 82..91 present, 92..95 removed');"</automated>
<fails_when>`logger.json` 不是合法 JSON、82–91 任一条缺失 / 过短、或 92–95 仍存在(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const base=JSON.parse(fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-56-logger-baseline.json','utf8'));const fail=[];Object.keys(base.error).forEach(k=>{const n=+k;if(n>=82&&n<=95)return;if(j.error[k]!==base.error[k])fail.push('error '+k+' changed');});if(JSON.stringify(j.warn)!==JSON.stringify(base.warn))fail.push('warn section changed');Object.keys(j.error).forEach(k=>{const n=+k;if(base.error[k]===undefined&&(n<82||n>91))fail.push('unexpected new error code '+k);});if(Object.keys(j.error).some(k=>+k>=1000&&base.error[k]===undefined))fail.push('added a 1000+ code');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 1..81 / 2001..2008 and the whole warn section unchanged; only 82..91 remain in the merged range');"</automated>
<fails_when>既有 error 码被改动、`warn` 段(含 213 / 1001)任一字符变化、在 82–91 之外新增错误码,或新增 `1000+` 码(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const counts={82:3,83:2,84:2,85:6,86:10,87:4,88:5,89:5,90:2,91:2};const D=String.fromCharCode(36);const re=new RegExp('['+D+'][0-9]+','g');const fail=[];Object.keys(counts).forEach(k=>{const msg=j.error[k]||'';const used=new Set();(msg.match(re)||[]).forEach(m=>used.add(+m.slice(1)));const nums=[...used].sort((a,b)=>a-b);const max=nums.length?nums[nums.length-1]:0;if(nums.length!==counts[k]||max!==counts[k])fail.push('code '+k+' uses '+nums.length+' params (max '+max+'), expected '+counts[k]);});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: placeholder counts match the parser call sites');"</automated>
<fails_when>任一 82–91 消息的 `$n` 数量与规范不符,或占位跳号(如用了 `$10` 却缺 `$5`)(打印实际与期望,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const BT=String.fromCharCode(96);const plan=fs.readFileSync('.planning/phases/09-minimum-browser-runnable/09-56-PLAN.md','utf8').replace(/\r\n/g,'\n');const log=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const digits=s=>s.length>0&&s.split('').every(ch=>ch>='0'&&ch<='9');const rows=plan.split('\n').map(l=>l.trim()).filter(l=>l.indexOf('|')===0).map(l=>l.split('|').map(s=>s.trim()));const expected={};rows.forEach(all=>{const c=all.filter((s,i)=>i>0&&i<all.length-1);if(c.length!==3||!digits(c[0]))return;const n=+c[0];if(n<82||n>91)return;const cell=c[1];if(cell.length>2&&cell.slice(0,1)===BT&&cell.slice(-1)===BT)expected[n]=cell.slice(1,-1);});const fail=[];for(let n=82;n<=91;n++){if(!expected[n])fail.push('plan table row missing for '+n);else if(log.error[n]!==expected[n])fail.push('message mismatch for '+n+' (json='+JSON.stringify(log.error[n])+' plan='+JSON.stringify(expected[n])+')');}const msgs=Object.keys(expected).map(k=>expected[k]);if(new Set(msgs).size!==msgs.length)fail.push('duplicate messages between 82..91');if(msgs.some(m=>m===('Cannot parse animation: '+String.fromCharCode(36)+'1.')))fail.push('generic placeholder-only message present');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 82..91 messages match the plan table verbatim, distinct, and non-generic');"</automated>
<fails_when>82–91 任一消息与计划表不是逐字一致、10 条消息出现重复,或存在 `Cannot parse animation: $1.` 泛化消息(打印差异,退出码 1)——只比对占位数量不够,必须比对整段文本。</fails_when>
<automated>node node_modules/prettier/bin/prettier.cjs --check packages/common/src/logger.json</automated>
<fails_when>prettier 报告该文件待格式化,或退出码非 0。</fails_when>
<automated>node -e "const fs=require('fs');const b=fs.readFileSync('packages/common/src/logger.json');const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;const ok=lf===crlf&&tabs===0&&!bom;console.log((ok?'OK':'FAIL')+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);process.exit(ok?0:1);"</automated>
<fails_when>出现非 CRLF 换行、制表符或 BOM(打印 `FAIL`,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- `logger.json` 的 error 段 82–91 恰有 10 条消息,文本与「logger.json error 82–91 最终文本」表**逐字一致**;92–95 已删除。
- 10 条消息两两不同,且不存在 `Cannot parse animation: $1.` 泛化消息。
- `$n` 数量为 3 / 2 / 2 / 6 / 10 / 4 / 5 / 5 / 2 / 2,与「logger 调用点参数规范」一致。
- `1..81`、`2001..2008` 与整个 `warn` 段(含 `213`、`1001`)与 Task 1 快照深比较逐字不变;未新增 `1000+` 码。
- prettier 与 CRLF / BOM / tab 门禁通过。
</acceptance_criteria>
<done>`logger.json` 的 error 已合并为 82–91 的 10 条具体消息(占位符 3/2/2/6/10/4/5/5/2/2,两两不同、无泛化消息),92–95 已删除,既有码段与 warn 段(含 213 / 1001)逐字未变;prettier 与 CRLF / BOM 门禁通过。</done>
</task>
<task type="auto">
<name>Task 3: 改写 `parse.ts` 注释 / jsDoc / logger 参数 / 导出 region,并同步 `parse.test.ts` 期望码与静态闸门</name>
<dependencies>Task 2(`logger.json` 的 82–91 已定稿)</dependencies>
<files>packages/render-anim/src/parse.ts, packages/render-anim/src/__test__/parse.test.ts</files>
<read_first>
- 本计划的「`parse.ts` 注释 / jsDoc 规格」「logger 调用点参数规范」「错误码合并映射」「logger.json error 82–91 最终文本」「`parse.test.ts` 改写规格」(唯一内容依据)
- `packages/render-anim/src/parse.ts`(Task 1 记录的现状:12 个单行 jsDoc、4 组 region、`// prettier-ignore`、整句 logger 参数)
- `packages/render-anim/src/__test__/parse.test.ts`(70 个用例、`expectFailure`、越界明细断言、静态闸门)
- `packages/common/src/logger.json`(Task 2 的 82–91 文本,确认实参与占位一致)
- `dev.md`(CRLF、4 空格、首行 import、方法 jsDoc 换行风格、短文件不分段、无类型专用导入)
</read_first>
<action>
本任务只改这两个文件。
1. **`parse.ts` jsDoc:** 按「`parse.ts` 注释 / jsDoc 规格」表,把 `isRecord` / `isNumber` / `isInteger` / `readHeader` / `readSpriteDimensions` / `readRawMeta` / `validateMeta` / `validateBitmapBounds` / `toObject` / `toFrame` / `computeFrameBox` / `toBlendMode` 的 12 段单行 jsDoc 改为多行,补 `@param` / `@returns`,不写 `@throws`;`parseRenderAnimation` 的 jsDoc 保持 09-55 原样,只补行内注释。
2. **`parse.ts` 行内注释:** 按规格表补字节偏移(签名 0 / 版本 4 / 两段长度 8 与 12 / sprite 数量 16 / 尺寸表 20 + i×8)、校验顺序、帧包围盒半宽半高公式、先 close 再记日志等注释;注释只解释原因 / 约束 / 分组,不复述代码;单行注释 `//` 后留一个空格,结尾不加句号。**`readRawMeta` 的「JSON 允许 primitive…」注释必须放在 `if (!isRecord(meta))` 守卫之前**(不要插在守卫与 `logger.error` 之间),以保证静态 compact 断言 `if(!isRecord(meta)){logger.error(90,'not-object',size.toString());returnnull;}returnmeta;` 仍能匹配。
3. **`parse.ts` logger 调用点:** 按「logger 调用点参数规范」表逐个替换 82–91 的全部调用点,只传原因标签 / 数字字符串 / 字段名 / `'-'` / 91 的 `reason` 变量;删除所有整句 / 短语字面量(含 `metadata is not an object`、`metadata is not valid JSON`、`sprite ...`、`bitmap ...`、`frame ...`、`object ...`、`sound ...` 等)。数字一律 `.toString()` 或模板字符串。**不得改动任何校验条件、循环结构、嵌套层级与 `try/catch` 作用域。**
4. **`parse.ts` region 与格式化:** 删除 `//#region 导出解析器` 与其 `//#endregion`(保留「常量与内部类型」「读取与校验」「帧转换与帧数学」三组);删除 `validateBitmapBounds` 中的 `// prettier-ignore`(86 号多参数调用交给 prettier 换行)。
5. **`parse.ts` 保持不动的项:** `isRecord` 的 `value !== null` 保留;`object[5] !== undefined` / `object[6] !== undefined` / `item.volume !== undefined` / `item.pitch !== undefined` 保留;`validateMeta` 的 3 层嵌套与提前 `return false` 保留;`readRawMeta` 的 `!isRecord` 守卫与 `return meta` 在 `try` 之后;`new Blob` 在 `try` 之外;恰 3 处 `try {`;无 `throw` / `@throws` / `finally`;签名仍为 `Promise<IAnimationParsedData | null>`。
6. **`parse.test.ts` 期望码:** 按「`parse.test.ts` 改写规格」第 1 条逐用例改为 82–91;同步每个 `it` 前的中文注释里的旧码;越界用例改断言 `calls[0][1] === 'out-of-bounds'`、`calls[0][9] === '16'`、`calls[0][10] === '16'` 并保留 `close` 被调用;5 条非对象元数据用例额外断言 `calls[0][1] === 'not-object'`;解码 / 纹理失败断言 `calls[0][1]` 为 `'decode-failed'` / `'texture-failed'`。
6b. **`parse.test.ts` arity 校验:** 在测试文件顶部新增常量映射 `ERROR_PARAM_COUNTS`(`82:3, 83:2, 84:2, 85:6, 86:10, 87:4, 88:5, 89:5, 90:2, 91:2`);`expectFailure` 在保留首参码与标签 / 顺序断言的同时,额外断言 `loggerMock.error.mock.calls[0].length === ERROR_PARAM_COUNTS[code] + 1`(`+1` 是 code 本身)。新增测试用例 / 注释时,每个 `it` 前仍保留一行中文注释。
7. **`parse.test.ts` 静态闸门:** 保留「无 `throw` / 无 `@throws` / 恰 3 处 `try {` / 无 `finally`」与三处 `try` 块体、`new Blob` 在 `try` 外的 compact 断言;把 `logger.error(88,'metadataisnotanobject')` 的 compact 断言替换为 `if(!isRecord(meta)){logger.error(90,'not-object',size.toString());returnnull;}returnmeta;`;继续断言 `validateMeta` / `validateBitmapBounds` 体内无 `forEach`。
8. 不弱化任何行为断言;成功用例 11 条全部保留;不修改 `animater.ts` / `animater.test.ts`(Task 4 处理)。
</action>
<verify>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const names=['isRecord','isNumber','isInteger','readHeader','readSpriteDimensions','readRawMeta','validateMeta','validateBitmapBounds','toObject','toFrame','computeFrameBox','toBlendMode'];const fail=[];names.forEach(n=>{const i=t.indexOf('function '+n);if(i<0){fail.push(n+' not found');return;}const before=t.slice(0,i);const close=before.lastIndexOf('*/');if(close<0){fail.push(n+' has no jsDoc');return;}const tail=before.slice(close+2);if(tail.trim()!==''){fail.push(n+' jsDoc not directly attached (text between */ and function)');return;}const open=before.lastIndexOf('/**',close);if(open<0){fail.push(n+' has no jsDoc opener');return;}const doc=before.slice(open,close+2);if(doc.indexOf('\n')===-1)fail.push(n+' jsDoc is single-line');if(doc.indexOf('@param')===-1)fail.push(n+' lacks @param');if(doc.indexOf('@returns')===-1)fail.push(n+' lacks @returns');});if(/@throws/.test(t))fail.push('@throws present');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 12 functions have directly-attached multi-line @param/@returns jsDoc, no @throws');"</automated>
<fails_when>12 个函数任一段 jsDoc 仍是单行、缺 `@param` / `@returns`、jsDoc 与 `function <name>` 之间除空白外还有其它文本(上一个函数的 jsDoc 不能顶替),或文件出现 `@throws`(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const fail=[];for(let c=82;c<=91;c++){if(!new RegExp('logger\\.error\\(\\s*'+c+'\\s*,').test(t))fail.push('missing code '+c);}for(let c=92;c<=95;c++){if(new RegExp('logger\\.error\\(\\s*'+c+'\\s*,').test(t))fail.push('old code '+c+' still used');}if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 82..91 referenced, 92..95 gone');"</automated>
<fails_when>82–91 中任一码没有调用点,或仍出现 92–95 的调用点(打印列表,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const literals=[...t.matchAll(/'((?:[^'\\]|\\.)*)'/g)].map(m=>m[1]);const spaced=literals.filter(s=>s.includes(' '));const banned=['metadata is not an object','metadata is not valid JSON'];const hit=banned.filter(s=>t.indexOf(s)!==-1);const fail=[];if(spaced.length)fail.push('sentence-like string literal contents: '+JSON.stringify(spaced));if(hit.length)fail.push('old sentence fragments: '+JSON.stringify(hit));if(t.indexOf('isNil')!==-1)fail.push('isNil introduced');if(t.indexOf('value !== null')===-1)fail.push('isRecord null check changed');if(t.indexOf('!value')!==-1)fail.push('!value used for isRecord');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: no single-quoted literal content contains a space; labels/values only; optional-field and isRecord checks untouched');"</automated>
<fails_when>`parse.ts` 存在**单引号字面量内容**含空格的整句参数(只检查 `m[1]`,不检查相邻字面量之间的文本;`logger.error(90, 'not-object', '-')` 与 `logger.error(87, 'frame-list-not-array', '-', '-', '-')` 必须通过)、出现旧整句片段、引入 `isNil`、改掉 `isRecord` 的 `value !== null` 或使用了 `!value`(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const need=['偏移 0 签名','偏移 4 版本','偏移 8 / 12','每个 sprite 固定 8 字节','先校验全局字段(ratio / blend / 位图列表)','旋转 θ 后轴对齐包围盒的半宽 / 半高分别为','在 close() 之前捕获尺寸','先关闭位图再记录日志'];const miss=need.filter(s=>t.indexOf(s)===-1);const fail=[];if(miss.length)fail.push('missing inline comment fragments: '+JSON.stringify(miss));const ci=t.indexOf('JSON 允许 primitive');const gi=t.indexOf('if (!isRecord(meta))');if(ci<0)fail.push('missing readRawMeta primitive comment');else if(gi<0)fail.push('isRecord guard not found');else if(ci>gi)fail.push('readRawMeta comment must be before the isRecord guard');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: required inline comments present and readRawMeta comment precedes the guard');"</automated>
<fails_when>缺少字节偏移 / 校验顺序 / 帧包围盒半宽半高公式 / close-before-log 的必需注释子串,或 `readRawMeta` 的 primitive 注释没有放在 `if (!isRecord(meta))` 之前(打印缺失 / 位置,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8');const fail=[];const pairs=[[82,3],[83,2],[84,2],[85,6],[86,10],[87,4],[88,5],[89,5],[90,2],[91,2]];if(t.indexOf('ERROR_PARAM_COUNTS')===-1)fail.push('ERROR_PARAM_COUNTS map missing');pairs.forEach(([c,n])=>{if(!new RegExp('\\b'+c+'\\s*:\\s*'+n+'\\b').test(t))fail.push('map missing '+c+':'+n);});if(!/calls\[0\]\.length\s*===\s*ERROR_PARAM_COUNTS\[[^\]]+\]\s*\+\s*1/.test(t))fail.push('expectFailure arity assertion missing');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 82..91 param-count map and expectFailure arity assertion present');"</automated>
<fails_when>`parse.test.ts` 缺少 `ERROR_PARAM_COUNTS` 常量映射(82–91 → 3/2/2/6/10/4/5/5/2/2)或 `expectFailure` 未断言 `calls[0].length === ERROR_PARAM_COUNTS[code] + 1`(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const fail=[];const reg=(t.match(/#region/g)||[]).length;const end=(t.match(/#endregion/g)||[]).length;if(reg!==3||end!==3)fail.push('regions='+reg+' endregions='+end+', expected 3/3');if(t.indexOf('#region 导出解析器')!==-1)fail.push('export region still present');if(t.indexOf('// prettier-ignore')!==-1)fail.push('prettier-ignore still present');if((t.match(/try\s*\{/g)||[]).length!==3)fail.push('try count changed');if(/\bthrow\b/.test(t))fail.push('throw present');if(/\bfinally\b/.test(t))fail.push('finally present');if(t.indexOf('Promise<IAnimationParsedData | null>')===-1)fail.push('signature changed');for(const need of ['object[5] !== undefined','object[6] !== undefined','item.volume !== undefined','item.pitch !== undefined']){if(t.indexOf(need)===-1)fail.push('optional check changed: '+need);}for(const need of ['new Blob','if (!isRecord(meta))','return meta;','image.close()']){if(t.indexOf(need)===-1)fail.push('missing '+need);}if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 3 functional regions, export region and prettier-ignore removed, try/throw/finally/signature/optional checks intact');"</automated>
<fails_when>region 不是 3/3、导出 region 或 `// prettier-ignore` 仍存在、`try` 数量或签名变化、出现 `throw` / `finally`、可选字段 `!== undefined` 被改(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8');const SQ=String.fromCharCode(39);const fail=[];for(let c=82;c<=91;c++){if(!new RegExp('\\b'+c+'\\b').test(t))fail.push('missing expected code '+c);}for(let c=92;c<=95;c++){if(new RegExp('\\b'+c+'\\b').test(t))fail.push('old code '+c+' still mentioned');}const guard='if(!isRecord(meta)){logger.error(90,'+SQ+'not-object'+SQ+',size.toString());returnnull;}returnmeta;';if(t.indexOf(guard)===-1)fail.push('static guard 90 text not updated');for(const label of ['out-of-bounds','decode-failed','texture-failed']){if(t.indexOf(SQ+label+SQ)===-1)fail.push('missing assertion '+label);}if(t.indexOf('toHaveBeenCalledTimes(1)')===-1)fail.push('single-log assertion missing');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: parse.test covers 82..91 only and the updated static guard');"</automated>
<fails_when>`parse.test.ts` 缺任一 82–91 码、仍出现 92–95、未更新 90 号静态闸门文本,或缺少 `out-of-bounds` / `decode-failed` / `texture-failed` / 只记一次日志的断言(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const lines=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8').replace(/\r\n/g,'\n').split('\n');const bad=[];for(let i=0;i<lines.length;i++){if(!/\bit\s*\(/.test(lines[i]))continue;let j=i-1;while(j>=0&&lines[j].trim()==='')j--;if(j<0||!lines[j].trim().startsWith('//'))bad.push(i+1);}if(bad.length){console.error('it without // comment: '+bad.join(','));process.exit(1);}console.log('OK: every it has a // comment on the preceding non-empty line');"</automated>
<fails_when>存在 `it` 前没有单行注释(打印行号,退出码 1)。</fails_when>
<automated>node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts</automated>
<fails_when>退出码非 0,或 parse 用例少于 70(允许 70 或更多;animater 不在此任务);browserslist 的 stderr 提示属正常,不作为失败依据。</fails_when>
<automated>node node_modules/prettier/bin/prettier.cjs --check packages/render-anim/src/parse.ts packages/render-anim/src/__test__/parse.test.ts</automated>
<fails_when>prettier 报告任一文件待格式化,或退出码非 0。</fails_when>
<automated>node node_modules/eslint/bin/eslint.js packages/render-anim/src/parse.ts packages/render-anim/src/__test__/parse.test.ts</automated>
<fails_when>eslint 打印任一 error / warning,或退出码非 0。</fails_when>
<automated>node -e "const fs=require('fs');const files=['packages/render-anim/src/parse.ts','packages/render-anim/src/__test__/parse.test.ts'];const fail=[];files.forEach(f=>{const b=fs.readFileSync(f);const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;if(lf!==crlf||tabs||bom)fail.push(f+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: CRLF, no tabs, no BOM');"</automated>
<fails_when>任一文件出现非 CRLF 换行、制表符或 BOM(打印实际值,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- `parse.ts` 的 12 个顶层函数均为**紧邻 `function <name>`** 的多行 jsDoc(含 `@param` / `@returns`),全文无 `@throws`;补入字节偏移、校验顺序、帧数学、close-before-log 的行内注释(必需子串门禁通过),且 `readRawMeta` 的 primitive 注释位于 `if (!isRecord(meta))` 之前。
- 82–91 全部出现在 `logger.error` 调用点,92–95 不再出现;全部调用点只传标签 / 数字 / 字段名 / `'-'` / `reason`,`parse.ts` 中不存在**字面量内容**含空格的字符串(相邻字面量之间的文本不误判)。
- `//#region 导出解析器` 与 `// prettier-ignore` 已删除,剩余 region 恰 3/3;`try` 仍 3 处、无 `throw` / `finally`、签名仍可空。
- `isRecord` 的 `value !== null`、四个可选字段的 `!== undefined`、`validateMeta` 嵌套与提前 `return false` 均未改动;未引入 `isNil` / `!value`。
- `parse.test.ts` 只覆盖 82–91,注释同步,越界 / 解码 / 纹理 / 非对象元数据断言按新参数布局;静态闸门使用新 90 号守卫文本并保留 3 处 `try` 断言;`ERROR_PARAM_COUNTS` 映射与 `expectFailure` 的 arity 断言存在;每个 `it` 有注释。
- targeted vitest 的 parse 用例 ≥ 70;prettier / eslint / CRLF / BOM 门禁通过。
</acceptance_criteria>
<done>`parse.ts` 的 12 个函数已改为多行 jsDoc 并补入有价值的行内注释,logger 调用点全部改为标签 / 值(82–91),导出 region 与 `// prettier-ignore` 已删除;不变量(3 处 try、无 throw/finally、可空签名、`isRecord` 与可选字段判断、`validateMeta` 嵌套)全部保持;`parse.test.ts` 已同步为 82–91 并通过静态闸门;parse 用例 ≥ 70,prettier / eslint / CRLF / BOM 通过。</done>
</task>
<task type="auto">
<name>Task 4: 整理 `animater.ts`(jsDoc / region / `// prettier-ignore` 移除 + 单画布复用)并同步 `animater.test.ts`</name>
<dependencies>Task 3(`parse.ts` 与 `parse.test.ts` 已完成,避免同文件并发)</dependencies>
<files>packages/render-anim/src/animater.ts, packages/render-anim/src/__test__/animater.test.ts</files>
<read_first>
- 本计划的「`animater.ts` 单画布与注释规格」「`animater.test.ts` 改写规格」(唯一内容依据)
- `packages/render-anim/src/animater.ts`(Task 1 记录的现状:类级 jsDoc、3 组 region、`once` / `cycled` jsDoc、每帧 `new MotaOffscreenCanvas2D()`、`// prettier-ignore`)
- `packages/render-anim/src/__test__/animater.test.ts`(9 个用例、`FakeCanvas2D`、`fakes.instances`)
- `packages/render/src/core/canvas2d.ts`(`size()` 重置尺寸与变换、`setHD()` 重新 `size()`、`clear()`)
- `packages/render/src/assets/types.ts`(`ITextureAnimater.once` / `cycled` 的接口 jsDoc)
- `(process.env.TEMP||'.')/gsd-09-56-class-jsdoc.txt`、`gsd-09-56-members.txt`(Task 1 的类级 jsDoc 全块与成员名基线)
- `dev.md`(方法 jsDoc 换行风格、短文件不分段、继承 API 不重复注释、CRLF、4 空格)
</read_first>
<action>
本任务只改这两个文件。
1. **单画布重构(`animater.ts`):**
- `composeFrame` 签名改为 `private composeFrame(canvas: MotaOffscreenCanvas2D, texture: ITexture, data: IAnimationParsedData, frame: IAnimationFrame): void`;删除函数内的 `const canvas = new MotaOffscreenCanvas2D();` / `canvas.setHD(false)` / `canvas.setAntiAliasing(false)`;首行改为 `canvas.size(frame.width, frame.height);`;其余绘制逻辑与顺序不变。
- `sequence` 在 `if (frames.length === 0) return;` 之后创建唯一 `const canvas = new MotaOffscreenCanvas2D();`,并调用 `canvas.setHD(false); canvas.setAntiAliasing(false);` 各一次;删除循环内 `let canvas: MotaOffscreenCanvas2D | null = null;` 与每帧 `canvas = this.composeFrame(...)` / 重用前的 `canvas.clear()` + 归零逻辑;改为每帧 `this.composeFrame(canvas, texture, data, frame);` 后 `yield { source: canvas.canvas, rect: { x: 0, y: 0, w: frame.width, h: frame.height } };`;循环结束后 `canvas.clear(); canvas.canvas.width = 0; canvas.canvas.height = 0;`。
- 不写 `finally`;提前 `.return()` 由生成器语义直接跳过结束清理,最后一帧留在同一画布。
2. **`animater.ts` jsDoc:** `composeFrame` 改多行 jsDoc(`@param canvas` / `@param texture` / `@param data` / `@param frame`,无 `@returns`,用描述句说明把当前帧绘制到给定画布);`sequence` 改多行 jsDoc(`@param texture` / `@param data` / `@param cycled` / `@returns 逐帧产出可渲染对象的生成器`)。**删除 `once` / `cycled` 的 jsDoc**;**类级 jsDoc 逐字保留,不得修改,不得新增任何类级注释**。
3. **`animater.ts` region / 格式化:** 删除全部 3 组 `//#region` / `//#endregion`,方法之间保留一个空行;把 `if (object.rotate) { ctx.rotate(-object.rotate * Math.PI / 180); }` 改为先声明 `const angle = (-object.rotate * Math.PI) / 180;` 再 `ctx.rotate(angle);`,删除 `// prettier-ignore`;不得新增其它格式化注释。
4. **`animater.ts` 行内注释:** 补「像素素材关闭高清与抗锯齿」(before `setHD(false)`)、「复用同一块画布,逐帧重设尺寸会重置变换矩阵并清空上一帧内容」(before `canvas.size(...)`)、「先平移到帧原点,再镜像、旋转,最后按不透明度与目标矩形绘制」(before 变换块)、「正常播放结束时清空并归零尺寸;提前 return 时不额外兜底,最后一帧随同一块画布交给垃圾回收」(before 结束清理)。注释不得包含英文兜底关键字,避免静态门禁误判。
5. **`animater.test.ts`:** 按「`animater.test.ts` 改写规格」的 9 条用例改写断言:每序列 1 个 `FakeCanvas2D`(`fakes.instances.length === 1`)、跨帧同一 `source`、相关用例统一 `const canvas = fakes.instances[0]` 后断言 `canvas.canvas.width/height`(不依赖偶然变量名)、正常结束 clear + 归零、提前 return 保留 10×20、无帧时 0 个实例、变换参数不变、不释放源纹理;每个 `it` 前保留一行中文注释;用例数量必须为 9。
6. 不修改 `parse.ts` / `parse.test.ts` / `logger.json` / `types.ts` / `index.ts` / `package.json`。
</action>
<verify>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/animater.ts','utf8').replace(/\r\n/g,'\n');const snap=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-56-class-jsdoc.txt','utf8').replace(/\r\n/g,'\n').trim();const fail=[];if(t.indexOf('#region')!==-1||t.indexOf('#endregion')!==-1)fail.push('region markers present');if(t.indexOf('// prettier-ignore')!==-1)fail.push('prettier-ignore present');if(t.indexOf(snap)===-1)fail.push('class jsDoc full block changed');const ci=t.indexOf(snap);if(ci>=0&&!/^\s*(?:export\s+)?class\s+RenderAnimater/.test(t.slice(ci+snap.length)))fail.push('class jsDoc not directly attached to class declaration');const blocks=(t.match(/\/\*\*/g)||[]).length;if(blocks!==3)fail.push('jsDoc block count='+blocks+', expected 3 (class + composeFrame + sequence)');if(/\/\*\*[\s\S]{0,200}\*\/\s*\*\s*once\s*\(/.test(t))fail.push('once still has jsDoc');if(/\/\*\*[\s\S]{0,200}\*\/\s*\*\s*cycled\s*\(/.test(t))fail.push('cycled still has jsDoc');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: no region/prettier-ignore; class jsDoc block verbatim and directly attached; exactly 3 jsDoc blocks; once/cycled jsDoc removed');"</automated>
<fails_when>`animater.ts` 仍有 region / `// prettier-ignore`、类级 jsDoc 全块与 Task 1 快照不是逐字一致或未紧邻类声明、`/**` 块数量不是 3(说明新增了类级注释或残留 once/cycled jsDoc),或 `once` / `cycled` 仍有 jsDoc(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/animater.ts','utf8');const snap=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-56-members.txt','utf8').replace(/\r\n/g,'\n').split('\n').map(x=>x.trim()).filter(Boolean).sort();const found=[...new Set([...t.matchAll(/^ {4}(?:(?:private|protected|public|static|async|readonly)\s+)*\*?([A-Za-z_$][\w$]*)\s*[\(=:]/gm)].map(m=>m[1]))].sort();if(JSON.stringify(found)!==JSON.stringify(snap)){console.error('member names changed; expected '+JSON.stringify(snap)+' got '+JSON.stringify(found));process.exit(1);}console.log('OK: declared member names unchanged (no new methods/fields)');"</automated>
<fails_when>`animater.ts` 的成员名集合与 Task 1 快照不一致(新增 / 重命名方法或字段;只允许 `composeFrame` 改签名,`sequence` / `once` / `cycled` 名称不变)(打印实际集合,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/animater.ts','utf8');const seg=(a,b)=>{const i=t.indexOf(a);if(i<0)return '';const j=t.indexOf(b,i+1);return j<0?'':t.slice(i,j);};const compose=seg('private composeFrame','private *sequence');const sequence=seg('private *sequence','*once(');const fail=[];if(!compose)fail.push('composeFrame not found');if(!sequence)fail.push('sequence not found');if(compose.indexOf('new MotaOffscreenCanvas2D')!==-1)fail.push('composeFrame still constructs a canvas');if(compose.indexOf('canvas.size(frame.width, frame.height)')===-1)fail.push('composeFrame does not resize per frame');if(compose.indexOf('canvas: MotaOffscreenCanvas2D')===-1)fail.push('composeFrame canvas param missing');if(!/\)\s*:\s*void\s*\{/.test(compose))fail.push('composeFrame does not return void');if((sequence.match(/new MotaOffscreenCanvas2D\(\)/g)||[]).length!==1)fail.push('sequence must construct exactly one canvas');if((sequence.match(/setHD\(false\)/g)||[]).length!==1)fail.push('setHD(false) must appear once in sequence');if((sequence.match(/setAntiAliasing\(false\)/g)||[]).length!==1)fail.push('setAntiAliasing(false) must appear once in sequence');if((sequence.match(/source:\s*canvas\.canvas/g)||[]).length!==1)fail.push('sequence must yield the same canvas source');if(sequence.indexOf('composeFrame(canvas, texture, data, frame)')===-1)fail.push('sequence does not pass the shared canvas');if(/try\s*\{/.test(t))fail.push('try added');if(/\bfinally\b/.test(t))fail.push('finally added');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: one canvas per sequence, per-frame size, same source, no try/finally');"</automated>
<fails_when>`composeFrame` 仍构造画布 / 未逐帧 `size` / 未接收 `canvas` 参数 / 未返回 `void`;`sequence` 不是恰好 1 处画布构造、`setHD(false)` 或 `setAntiAliasing(false)` 不是各 1 次、`source` 不是同一 `canvas.canvas`、或出现 `try` / `finally`(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/animater.ts','utf8');const before=(needle)=>{const i=t.indexOf(needle);if(i<0)return '';const b=t.slice(Math.max(0,i-1200),i);const o=b.lastIndexOf('/**');const c=b.lastIndexOf('*/');return o<0||c<o?'':b.slice(o,c);};const fail=[];const dc=before('private composeFrame');const ds=before('private *sequence');if(dc.indexOf('@param')===-1||dc.indexOf('\n')===-1)fail.push('composeFrame jsDoc not multi-line with @param');if(ds.indexOf('@param')===-1||ds.indexOf('@returns')===-1||ds.indexOf('\n')===-1)fail.push('sequence jsDoc not multi-line with @param/@returns');if(t.indexOf('const angle = (-object.rotate * Math.PI) / 180;')===-1)fail.push('rotate intermediate missing');for(const c of ['复用同一块画布','先平移到帧原点','正常播放结束时清空并归零尺寸']){if(t.indexOf(c)===-1)fail.push('missing inline comment: '+c);}if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: multi-line jsDoc, rotate intermediate, meaningful inline comments');"</automated>
<fails_when>`composeFrame` / `sequence` 的 jsDoc 不是多行或缺少 `@param` / `@returns`,缺少 `angle` 中间量,或缺少三处行内注释(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/__test__/animater.test.ts','utf8');const fail=[];const its=(t.match(/^\s*it\s*\(/gm)||[]).length;if(its!==9)fail.push('test count='+its+', expected 9');if(t.indexOf('instances.length).toBe(1)')===-1)fail.push('single canvas assertion missing');if(t.indexOf('toBe(fakes.instances[0].canvas)')===-1)fail.push('first source assertion missing');if(t.indexOf('expect(second.source).toBe(first.source)')===-1)fail.push('same source assertion missing');if(t.indexOf('const canvas = fakes.instances[0]')===-1)fail.push('tests must declare const canvas = fakes.instances[0]');if(t.indexOf('canvas.canvas.width).toBe(0)')===-1)fail.push('zero width on completion missing');if(t.indexOf('canvas.canvas.height).toBe(0)')===-1)fail.push('zero height on completion missing');if(t.indexOf('expect(canvas.ctx.clearRect).not.toHaveBeenCalled()')===-1)fail.push('early-return no-clear assertion missing');if(t.indexOf('instances.length).toBe(0)')===-1)fail.push('empty-frames zero-instance assertion missing');if(t.indexOf('dispose).not.toHaveBeenCalled()')===-1)fail.push('no-dispose assertion missing');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 9 animater tests cover single canvas, same source, cleanup, empty frames, no dispose');"</automated>
<fails_when>`animater.test.ts` 不是 9 个用例,或缺 `const canvas = fakes.instances[0]` / 单画布 / 同一 source / `canvas.canvas.width` 与 `canvas.canvas.height` 归零 / 提前 return 不清空 / 空帧 0 实例 / 不释放纹理的断言(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const lines=fs.readFileSync('packages/render-anim/src/__test__/animater.test.ts','utf8').replace(/\r\n/g,'\n').split('\n');const bad=[];for(let i=0;i<lines.length;i++){if(!/\bit\s*\(/.test(lines[i]))continue;let j=i-1;while(j>=0&&lines[j].trim()==='')j--;if(j<0||!lines[j].trim().startsWith('//'))bad.push(i+1);}if(bad.length){console.error('it without // comment: '+bad.join(','));process.exit(1);}console.log('OK: every it has a // comment on the preceding non-empty line');"</automated>
<fails_when>存在 `it` 前没有单行注释(打印行号,退出码 1)。</fails_when>
<automated>node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/animater.test.ts</automated>
<fails_when>退出码非 0,或输出未报告 9 passed;browserslist 的 stderr 提示属正常,不作为失败依据。</fails_when>
<automated>node node_modules/prettier/bin/prettier.cjs --check packages/render-anim/src/animater.ts packages/render-anim/src/__test__/animater.test.ts</automated>
<fails_when>prettier 报告任一文件待格式化,或退出码非 0。</fails_when>
<automated>node node_modules/eslint/bin/eslint.js packages/render-anim/src/animater.ts packages/render-anim/src/__test__/animater.test.ts</automated>
<fails_when>eslint 打印任一 error / warning,或退出码非 0。</fails_when>
<automated>node -e "const fs=require('fs');const files=['packages/render-anim/src/animater.ts','packages/render-anim/src/__test__/animater.test.ts'];const fail=[];files.forEach(f=>{const b=fs.readFileSync(f);const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;if(lf!==crlf||tabs||bom)fail.push(f+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: CRLF, no tabs, no BOM');"</automated>
<fails_when>任一文件出现非 CRLF 换行、制表符或 BOM(打印实际值,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- `sequence` 每个序列只创建 1 块画布(在空帧判断之后),`setHD(false)` / `setAntiAliasing(false)` 各 1 次;每帧调用 `composeFrame(canvas, ...)` 并 `yield` 同一个 `canvas.canvas`;正常结束 `clear()` + 宽高归零;无 `try` / `finally`。
- `composeFrame(canvas, texture, data, frame): void` 每帧 `canvas.size(frame.width, frame.height)`,内部不构造画布;变换顺序与绘制参数不变。
- `animater.ts` 无 region / `// prettier-ignore`;`composeFrame` / `sequence` 为多行 jsDoc;`once` / `cycled` 无 jsDoc;**类级 jsDoc 全块与 Task 1 快照逐字一致且紧邻类声明,文件恰有 3 个 `/**` 块(无新增类级注释)**;成员名集合与 Task 1 快照一致(无新增 / 重命名方法或字段);三处行内注释到位。
- `animater.test.ts` 恰 9 个用例,相关用例声明 `const canvas = fakes.instances[0]` 并断言 `canvas.canvas.width/height`,覆盖单画布 / 同一 source / 逐帧尺寸 / 正常结束归零 / 提前 return 保留最后一帧 / 无帧 0 实例 / 变换 / 不释放纹理;每个 `it` 有注释。
- targeted vitest 报告 9 passed;prettier / eslint / CRLF / BOM 门禁通过。
</acceptance_criteria>
<done>`animater.ts` 已改为每序列单画布复用(`composeFrame(canvas, ...)` 逐帧 `size` + 同一 `source` + 正常结束 clear/归零 + 提前 return 保留最后一帧),region 与 `// prettier-ignore` 删除、`once` / `cycled` jsDoc 删除、`composeFrame` / `sequence` 多行 jsDoc 与行内注释补齐、类级 jsDoc 原样保留;`animater.test.ts` 9 个用例全部按单画布语义通过,prettier / eslint / CRLF / BOM 通过。</done>
</task>
<task type="auto">
<name>Task 5: 全量验证(静态门禁 + targeted vitest + prettier / eslint / 过滤 vue-tsc / CRLF),只读不写</name>
<dependencies>Task 4(5 个目标文件全部改完)</dependencies>
<files>无(本任务只运行只读校验;不写仓库文件、不改 SUMMARY;`vue-tsc` 若生成任何 `*.tsbuildinfo` 必须立即删除,不得留在仓库、不得产生新的 git status 条目)</files>
<read_first>
- 本计划的「已确认问题清单」「错误码合并映射」「logger.json error 82–91 最终文本」「logger 调用点参数规范」「两个测试规格」
- `packages/render-anim/src/parse.ts`、`animater.ts`、两个测试、`packages/common/src/logger.json`(Task 2–4 产物)
- `packages/render-anim/src/types.ts` / `index.ts` / `package.json`(只验证)
- `(process.env.TEMP||'.')/gsd-09-56-class-jsdoc.txt`、`gsd-09-56-members.txt`(Task 1 基线,综合静态门禁用)
- `.planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md`(SUMMARY 风格参考,Task 6 使用)
</read_first>
<action>
本任务只读验证,不写任何文件。
1. 运行 targeted vitest:`node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts packages/render-anim/src/__test__/animater.test.ts`,记录实际用例数(parse 应 ≥ 70、animater 应 = 9,合计 ≥ 79)。
2. 运行 prettier `--check`:5 个改动文件(`parse.ts` / `animater.ts` / 两个测试 / `logger.json`)。
3. 运行 eslint:两个源码 + 两个测试。
4. 运行 CRLF / BOM / tab 检查:5 个改动文件。
5. 运行过滤类型检查:先 `node node_modules/vue-tsc/bin/vue-tsc.js --version` 哨兵,再 `node node_modules/vue-tsc/bin/vue-tsc.js --noEmit --incremental false`,只统计匹配 `packages[\\/]render-anim`(同时接受 `/` 与 `\` 分隔符)的诊断行;全仓其它既有诊断与总退出码不参与判定;哨兵无法启动或过滤出诊断则停下上报。**`tsbuildinfo` 处理(`tsconfig.node.json` 为 `composite: true`,根 `tsconfig.json` 引用它):** `--incremental false` 用于阻止写出 `*.tsbuildinfo`;若 vue-tsc 拒绝该参数(输出 `Unknown compiler option` / `TS5023` / `TS6379` / `may not disable incremental`)或仍生成 `*.tsbuildinfo`,则改为不带该参数的 `--noEmit` 运行,随后**立即删除生成的 `*.tsbuildinfo`**(只在仓库根目录按文件名匹配删除,属生成物清理,不是新增仓库文件),并在记录中注明;收尾必须断言仓库根目录无 `*.tsbuildinfo` 且 `git status --porcelain -uall` 无任何 `tsbuildinfo` 行。
6. 运行综合静态门禁(一次性脚本):确认 animater 无 region / 无 `// prettier-ignore` / 类级 jsDoc 全块与 Task 1 快照逐字一致且紧邻类声明 / 文件恰 3 个 `/**` 块 / 成员名集合与 Task 1 快照一致 / `once` / `cycled` 无 jsDoc / `sequence` 内恰 1 处画布构造 / `composeFrame` 内无画布构造 / 无 `try` / `finally`;parse 无导出 region / 无 `// prettier-ignore` / 无 `@throws` / 无整句字面量(按字面量内容判定) / 12 个顶层函数 jsDoc 与 `function` 之间只有空白 / 必需行内注释子串存在且 `readRawMeta` 注释在守卫之前 / `try` 恰 3 处 / 82–91 全在、92–95 不在 / 可选字段 `!== undefined` 保留 / `isRecord` 保留 `value !== null`;logger 82–91 两两不同且非 `$1`-only;两个测试文件均无 92–95,且 `parse.test.ts` 的 `ERROR_PARAM_COUNTS` 与 arity 断言存在。
7. 记录所有真实输出(用例数、退出码、过滤结果),供 Task 6 写入 SUMMARY;若任一失败,停止并上报,不得进入 Task 6。
</action>
<verify>
<automated>node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts packages/render-anim/src/__test__/animater.test.ts</automated>
<fails_when>退出码非 0,或 parse 用例少于 70、animater 用例不是 9;browserslist 的 stderr 提示属正常,不作为失败依据。</fails_when>
<automated>node node_modules/prettier/bin/prettier.cjs --check packages/render-anim/src/parse.ts packages/render-anim/src/animater.ts packages/render-anim/src/__test__/parse.test.ts packages/render-anim/src/__test__/animater.test.ts packages/common/src/logger.json</automated>
<fails_when>prettier 报告任一文件待格式化,或退出码非 0。</fails_when>
<automated>node node_modules/eslint/bin/eslint.js packages/render-anim/src/parse.ts packages/render-anim/src/animater.ts packages/render-anim/src/__test__/parse.test.ts packages/render-anim/src/__test__/animater.test.ts</automated>
<fails_when>eslint 打印任一 error / warning,或退出码非 0。</fails_when>
<automated>node -e "const fs=require('fs');const files=['packages/render-anim/src/parse.ts','packages/render-anim/src/animater.ts','packages/render-anim/src/__test__/parse.test.ts','packages/render-anim/src/__test__/animater.test.ts','packages/common/src/logger.json'];const fail=[];files.forEach(f=>{const b=fs.readFileSync(f);const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;if(lf!==crlf||tabs||bom)fail.push(f+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 5 files are CRLF, no tabs, no BOM');"</automated>
<fails_when>任一改动文件出现非 CRLF 换行、制表符或 BOM(打印实际值,退出码 1)。</fails_when>
<automated>node -e "const{spawnSync}=require('child_process');const r=spawnSync(process.execPath,['node_modules/vue-tsc/bin/vue-tsc.js','--version'],{encoding:'utf8'});if(r.status!==0){console.error('vue-tsc sentinel failed: '+(r.stderr||r.stdout));process.exit(1);}console.log('OK: vue-tsc sentinel '+String(r.stdout).trim());"</automated>
<fails_when>`vue-tsc --version` 哨兵无法启动(退出码非 0),说明类型检查工具链不可用(打印 stderr / stdout,退出码 1)。</fails_when>
<automated>node -e "const{spawnSync}=require('child_process');const r=spawnSync(process.execPath,['node_modules/vue-tsc/bin/vue-tsc.js','--noEmit','--incremental','false'],{encoding:'utf8',maxBuffer:1e8});const out=((r.stdout||'')+(r.stderr||'')).split(/\r?\n/);const rejected=out.filter(l=>/Unknown compiler option|TS5023|TS6379|may not disable incremental/i.test(l));if(rejected.length){console.error('vue-tsc rejected --incremental false:\n'+rejected.join('\n'));process.exit(1);}const hits=out.filter(l=>/packages[\\/]render-anim/.test(l));if(hits.length){console.error('render-anim diagnostics:\n'+hits.join('\n'));process.exit(1);}console.log('OK: 0 ts diagnostics under packages/render-anim (vue-tsc exit '+r.status+')');"</automated>
<fails_when>`vue-tsc --noEmit --incremental false` 被拒绝(输出 `Unknown compiler option` / `TS5023` / `TS6379` / `may not disable incremental`),或输出中出现任何匹配 `packages[\\/]render-anim`(正斜杠或反斜杠分隔符)的诊断行(打印这些行,退出码 1);全仓其它包的既有诊断与总退出码不参与判定。参数被拒时按 `<action>` 第 5 步回退为不带该参数的 `--noEmit` 并清理生成物。</fails_when>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const root=fs.readdirSync('.').filter(f=>f.endsWith('.tsbuildinfo'));if(root.length){console.error('tsbuildinfo left in repo root: '+root.join(', '));process.exit(1);}const st=execSync('git status --porcelain -uall',{encoding:'utf8'}).split(/\r?\n/).filter(l=>l.indexOf('tsbuildinfo')!==-1);if(st.length){console.error('tsbuildinfo in git status: '+st.join(' | '));process.exit(1);}console.log('OK: no *.tsbuildinfo in repo root and none in git status');"</automated>
<fails_when>仓库根目录仍存在 `*.tsbuildinfo`,或 `git status --porcelain -uall` 中出现任何含 `tsbuildinfo` 的条目(此时必须按 `<action>` 第 5 步删除生成物并重跑,不得进入 Task 6)(打印实际条目,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const p=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const a=fs.readFileSync('packages/render-anim/src/animater.ts','utf8').replace(/\r\n/g,'\n');const fail=[];if(a.indexOf('#region')!==-1||a.indexOf('#endregion')!==-1)fail.push('animater region present');if(a.indexOf('// prettier-ignore')!==-1)fail.push('animater prettier-ignore present');const snap=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-56-class-jsdoc.txt','utf8').replace(/\r\n/g,'\n').trim();if(a.indexOf(snap)===-1)fail.push('class jsDoc block changed');const ci=a.indexOf(snap);if(ci>=0&&!/^\s*(?:export\s+)?class\s+RenderAnimater/.test(a.slice(ci+snap.length)))fail.push('class jsDoc not attached');if((a.match(/\/\*\*/g)||[]).length!==3)fail.push('animater jsDoc block count != 3');if(/\/\*\*[\s\S]{0,200}\*\/\s*\*\s*once\s*\(/.test(a))fail.push('once jsDoc present');if(/\/\*\*[\s\S]{0,200}\*\/\s*\*\s*cycled\s*\(/.test(a))fail.push('cycled jsDoc present');const seg=(s,x,y)=>{const i=s.indexOf(x);if(i<0)return '';const j=s.indexOf(y,i+1);return j<0?'':s.slice(i,j);};const compose=seg(a,'private composeFrame','private *sequence');const sequence=seg(a,'private *sequence','*once(');if(compose.indexOf('new MotaOffscreenCanvas2D')!==-1)fail.push('composeFrame constructs canvas');if((sequence.match(/new MotaOffscreenCanvas2D\(\)/g)||[]).length!==1)fail.push('sequence canvas count != 1');if(/try\s*\{/.test(a))fail.push('animater try present');if(/\bfinally\b/.test(a))fail.push('animater finally present');if(p.indexOf('#region 导出解析器')!==-1)fail.push('parse export region present');if(p.indexOf('// prettier-ignore')!==-1)fail.push('parse prettier-ignore present');if(/@throws/.test(p))fail.push('parse @throws present');const literals=[...p.matchAll(/'((?:[^'\\]|\\.)*)'/g)].map(m=>m[1]);if(literals.some(s=>s.includes(' ')))fail.push('parse sentence literal present');if((p.match(/try\s*\{/g)||[]).length!==3)fail.push('parse try count != 3');if(/\bthrow\b/.test(p))fail.push('parse throw present');if(/\bfinally\b/.test(p))fail.push('parse finally present');for(let c=82;c<=91;c++){if(!new RegExp('logger\\.error\\(\\s*'+c+'\\s*,').test(p))fail.push('missing code '+c);}for(let c=92;c<=95;c++){if(new RegExp('logger\\.error\\(\\s*'+c+'\\s*,').test(p))fail.push('old code '+c);}for(const need of ['object[5] !== undefined','object[6] !== undefined','item.volume !== undefined','item.pitch !== undefined','value !== null']){if(p.indexOf(need)===-1)fail.push('missing invariant '+need);}if(p.indexOf('isNil')!==-1)fail.push('isNil introduced');const members=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-56-members.txt','utf8').replace(/\r\n/g,'\n').split('\n').map(x=>x.trim()).filter(Boolean).sort();const found=[...new Set([...a.matchAll(/^ {4}(?:(?:private|protected|public|static|async|readonly)\s+)*\*?([A-Za-z_$][\w$]*)\s*[\(=:]/gm)].map(m=>m[1]))].sort();if(JSON.stringify(found)!==JSON.stringify(members))fail.push('animater member names changed');const needComments=['偏移 0 签名','偏移 4 版本','偏移 8 / 12','每个 sprite 固定 8 字节','先校验全局字段(ratio / blend / 位图列表)','旋转 θ 后轴对齐包围盒的半宽 / 半高分别为','在 close() 之前捕获尺寸','先关闭位图再记录日志'];const missComments=needComments.filter(s=>p.indexOf(s)===-1);if(missComments.length)fail.push('missing inline comments: '+missComments.join(','));const ci2=p.indexOf('JSON 允许 primitive');const gi=p.indexOf('if (!isRecord(meta))');if(ci2<0||gi<0||ci2>gi)fail.push('readRawMeta comment placement');const pt=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8');if(pt.indexOf('ERROR_PARAM_COUNTS')===-1)fail.push('parse.test arity map missing');if(!/calls\[0\]\.length\s*===\s*ERROR_PARAM_COUNTS\[[^\]]+\]\s*\+\s*1/.test(pt))fail.push('parse.test arity assertion missing');const fs2=fs;const t2=fs2.readFileSync('packages/render-anim/src/parse.ts','utf8');const jsNames=['isRecord','isNumber','isInteger','readHeader','readSpriteDimensions','readRawMeta','validateMeta','validateBitmapBounds','toObject','toFrame','computeFrameBox','toBlendMode'];jsNames.forEach(n=>{const i=t2.indexOf('function '+n);if(i<0){fail.push('parse fn missing '+n);return;}const before=t2.slice(0,i);const close=before.lastIndexOf('*/');if(close<0){fail.push(n+' jsDoc missing');return;}if(before.slice(close+2).trim()!=='')fail.push(n+' jsDoc not directly attached');const open=before.lastIndexOf('/**',close);if(open<0){fail.push(n+' jsDoc opener missing');return;}const doc=before.slice(open,close+2);if(doc.indexOf('@param')===-1||doc.indexOf('@returns')===-1)fail.push(n+' jsDoc lacks @param/@returns');});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: combined static gates pass');"</automated>
<fails_when>综合静态门禁任一项失败(region / prettier-ignore / 类级 jsDoc 全块与 3 块计数 / 成员名集合 / once-cycled jsDoc / 画布构造位置与数量 / try-finally / throw / 82–91 与 92–95 / 可选字段与 isRecord 不变量 / 字面量内容空格 / 必需行内注释与 readRawMeta 注释位置 / parse.test arity 映射与断言)(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const D=String.fromCharCode(36);const generic='Cannot parse animation: '+D+'1.';const msgs=[];const fail=[];for(let c=82;c<=91;c++){const m=j.error[c];if(typeof m!=='string'){fail.push('missing '+c);continue;}msgs.push(m);if(m===generic)fail.push('generic message '+c);}if(new Set(msgs).size!==msgs.length)fail.push('duplicate messages');for(let c=92;c<=95;c++){if(j.error[c]!==undefined)fail.push('error '+c+' still present');}if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 10 distinct specific messages, 92..95 removed');"</automated>
<fails_when>`logger.json` 的 82–91 缺失、出现重复消息、出现 `Cannot parse animation: $1.` 泛化消息,或 92–95 仍存在(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const files=['packages/render-anim/src/__test__/parse.test.ts','packages/render-anim/src/__test__/animater.test.ts'];const fail=[];files.forEach(f=>{const s=fs.readFileSync(f,'utf8');for(let c=92;c<=95;c++){if(new RegExp('\\b'+c+'\\b').test(s))fail.push(f+' mentions old code '+c);}});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: both test files are free of old codes 92..95');"</automated>
<fails_when>任一测试文件仍出现 92–95(打印原因,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- targeted vitest 通过:parse ≥ 70、animater = 9(规划日基线 79 passed)。
- prettier `--check`、eslint、CRLF / BOM / tab 对 5 个改动文件全部通过。
- `vue-tsc --version` 哨兵通过,`--noEmit --incremental false` 过滤 `packages/render-anim` 诊断 0 行;参数被拒时已按回退流程执行,且仓库根目录无 `*.tsbuildinfo`、git status 无任何 `tsbuildinfo` 条目。
- 综合静态门禁通过:animater 无 region / 无 `// prettier-ignore` / 类级 jsDoc 全块与 Task 1 快照逐字一致且紧邻类声明 / 恰 3 个 `/**` 块 / 成员名集合不变 / `once` / `cycled` 无 jsDoc / `sequence` 恰 1 处画布构造 / `composeFrame` 内不构造 / 无 `try` / `finally`;parse 无导出 region / 无 `// prettier-ignore` / 无 `@throws` / 无字面量内容含空格 / 12 个顶层函数 jsDoc 与 `function` 之间只有空白 / 必需行内注释子串存在且 readRawMeta 注释在守卫之前 / `try` 恰 3 处 / 82–91 全在、92–95 不在 / 可选字段与 `isRecord` 不变量保留;logger 82–91 两两不同且非 `$1`-only;测试文件无 92–95,`parse.test.ts` 含 `ERROR_PARAM_COUNTS` 与 arity 断言。
- 所有真实输出已记录,供 Task 6 写入 SUMMARY;本任务未写任何仓库文件(若 vue-tsc 生成 `*.tsbuildinfo` 已在收尾删除)。
</acceptance_criteria>
<done>targeted vitest(parse ≥ 70、animater 9)、prettier、eslint、CRLF / BOM、过滤 vue-tsc(`--noEmit --incremental false`,或已回退并清理生成物)与综合静态门禁全部通过;仓库根目录无 `*.tsbuildinfo`、git status 无 `tsbuildinfo`;真实输出已记录,未写任何仓库文件。</done>
</task>
<task type="auto">
<name>Task 6: 范围 / 哈希复核并写 `09-56-SUMMARY.md`(文件清单、测试数量、错误码映射、行为变更、偏差)</name>
<dependencies>Task 5(全部门禁通过)</dependencies>
<files>.planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md</files>
<read_first>
- 本计划的 `<success_criteria>` 与「覆盖审计」(SUMMARY 必须覆盖的条目)
- `(process.env.TEMP||'.')/gsd-09-56-status.txt`、`gsd-09-56-hashes.txt`、`gsd-09-56-logger-baseline.json`、`gsd-09-56-class-jsdoc.txt`、`gsd-09-56-members.txt`(Task 1 基线)
- `packages/render-anim/src/parse.ts`、`animater.ts`、两个测试、`packages/common/src/logger.json`(Task 2–4 产物)
- Task 5 记录的真实输出(用例数、prettier / eslint / vue-tsc / CRLF 结果)
- `.planning/phases/09-minimum-browser-runnable/09-55-SUMMARY.md`(SUMMARY 结构与 frontmatter 风格参考)
- `AGENTS.md` / `dev.md`(CRLF、无 BOM)
</read_first>
<action>
本任务只写 `09-56-SUMMARY.md`,不改任何代码文件。
1. **写 SUMMARY 前的范围闸门(必须在写文件之前内联执行):** 运行显式 `node` 命令,要求 `addedIn` 为空、`removedIn` / `addedOut` / `removedOut` / `extra` / `missing` 为空,**且显式断言 `09-56-SUMMARY.md` 尚不存在**(`fs.existsSync` 为 false,且 `git status --porcelain -uall` 中没有任何 `09-56-SUMMARY.md` 条目)。基线中已包含 `?? .planning/.../09-56-PLAN.md` 与 5 个目标文件的未跟踪 / 修改状态,因此本 run 只改内容、不改状态。**仓库根目录不得存在任何 `*.tsbuildinfo`**(Task 5 收尾已清理;若此处出现,它会被计入 `addedOut` 而失败——此时停下上报并删除生成物,不得把它留在仓库或写进 SUMMARY)。任一不符,停下上报,不写 SUMMARY。
2. **写 SUMMARY 前的哈希闸门:** 9 条基线中**排除 `09-56-PLAN.md`**(计划文件可能被规划 / 修订流程写入),只比较其余 8 条;其中只允许 `parse.ts`、`animater.ts`、`parse.test.ts`、`animater.test.ts`、`logger.json` 的哈希变化,`types.ts` / `index.ts` / `package.json` 哈希不变。预期变化集合恰为这 5 个目标文件。
3. **写 `09-56-SUMMARY.md`**:UTF-8 无 BOM、CRLF、4 空格缩进的 Markdown。frontmatter 至少包含 `phase: 09-minimum-browser-runnable`、`plan: 56`、`subsystem: render-anim`、`tags`、`requires`、`provides`、`affects`、`actuals`(tokens / tasks / commits: 0)、`tech-stack`、`key-files`(modified)、`key-decisions`、`patterns-established`、`duration`、`completed`、`status: complete`。正文至少包含:
- **本次范围**:只改 5 个文件 + 本 SUMMARY;`types.ts` / `index.ts` / `package.json` 未动;不跑游戏 / 浏览器 / dev server;**0 次提交**;09-56 / 波次 5 / `depends_on: 09-55` 的编号说明。
- **文件清单**:逐个列出 5 个改动文件与本 SUMMARY。
- **测试数量**:parse 实测用例数(基线 70)、animater 9、合计;并声明实测基线为 70 个 parse 用例 + 9 个 animater 用例 = 79 passed,79 是合计,不是 parse 用例数,此前规划输入曾误写成 79 parse,以实测 70 + 9 为准;记录 `parse.test.ts` 新增的 `ERROR_PARAM_COUNTS`(82–91 → 3/2/2/6/10/4/5/5/2/2)与 `expectFailure` arity 断言。
- **错误码映射表**:旧 82–95 → 新 82–91,一行一条(含旧 88 的 not-tuple / 4 元 / 8 元 → 新 88),并标注 92–95 已删除、`warn` 段(含 213 / 1001)未变。
- **行为变更说明**:`sequence` 单画布复用(每序列一块 `MotaOffscreenCanvas2D`、逐帧 `size`、同一 `source`、正常结束 clear + 归零、提前 return 保留最后一帧、不加 `finally`);`composeFrame` 签名变更。
- **注释 / jsDoc 变更**:12 个顶层函数、`composeFrame` / `sequence` 多行 jsDoc(与 `function` / 方法签名之间只有空白);删除 `once` / `cycled` jsDoc;删除 animater 3 组 `#region` / `#endregion` 与 parse 导出 region;删除两处 `// prettier-ignore`;类级 jsDoc 全块逐字未动;成员名集合未变(`composeFrame` 仅改签名,`sequence` / `once` / `cycled` 不变)。
- **文档债**:类级 jsDoc 中「每次 `.next()` 恢复后会释放上一帧」在单画布复用后已不准确;按用户要求逐字保留,未经另行批准不改写。
- **明确未改项**:early return、`validateMeta` 嵌套、可选字段 `!== undefined`、`isRecord` 的 `value !== null`。
- **门禁结果**:真实输出摘要(vitest 用例数、prettier / eslint / CRLF / BOM、过滤 `packages[\\/]render-anim` 的 vue-tsc、综合静态门禁、哈希闸门)。
- **偏差**:如有(例如测试夹具调整、`'-'` 占位约定、用例数量差异),逐条记录;无偏差则写「无」。
- **未校准估算**:`confidence: low`、`tokens: 110000`(7 个任务 / 110k 仅为 advisory 建议值,**plan-checker 已指出可能超出 smart-zone,但按用户要求保持单计划不拆分**,不作为拆分依据、不阻断执行)。
4. **写后的范围闸门:** `added` 恰为 `?? .planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md`;`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 为空。
5. 不写 `09-56-RESEARCH.md` / `09-56-VALIDATION.md`;不改 `STATE.md` / `ROADMAP.md` / `09-CONTEXT.md` / 09-55 计划与摘要;不执行任何 git 写命令。
</action>
<verify>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const SUMMARY='?? .planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md';const sumPath='.planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md';const base=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-56-status.txt','utf8').split(/\r?\n/).filter(l=>l.length>0);const cur=execSync('git status --porcelain -uall',{encoding:'utf8'}).split(/\r?\n/).filter(l=>l.length>0);if(fs.existsSync(sumPath)){console.error('SUMMARY already exists before write');process.exit(1);}if(cur.some(l=>l.indexOf('09-56-SUMMARY.md')!==-1)){console.error('SUMMARY already present in git status');process.exit(1);}const inScope=l=>{const p=l.slice(3);return p.indexOf('packages/render-anim/')===0||p.indexOf('packages/common/src/logger.json')===0||p.indexOf('.planning/phases/09-minimum-browser-runnable/')===0;};const added=cur.filter(l=>base.indexOf(l)===-1);const removed=base.filter(l=>cur.indexOf(l)===-1);const addedIn=added.filter(inScope);const addedOut=added.filter(l=>!inScope(l));const removedIn=removed.filter(inScope);const removedOut=removed.filter(l=>!inScope(l));const pre=addedIn.filter(l=>l.indexOf('09-56-SUMMARY.md')===-1);console.log('addedIn:\n'+addedIn.join('\n'));if(pre.length||removedIn.length||addedOut.length||removedOut.length){console.error('range drift');process.exit(1);}console.log('OK: SUMMARY absent; no status change other than the summary itself');"</automated>
<fails_when>`09-56-SUMMARY.md` 在写前已存在或已出现在 git status,或出现 SUMMARY 之外的新增 / 删除条目(打印分组,退出码 1)。</fails_when>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const p=(process.env.TEMP||'.')+'/gsd-09-56-hashes.txt';const plan='.planning/phases/09-minimum-browser-runnable/09-56-PLAN.md';const base=fs.readFileSync(p,'utf8').replace(/\r\n/g,'\n').trim().split('\n').filter(Boolean).filter(l=>l.split(' ')[0]!==plan);const now=base.map(l=>{const f=l.split(' ')[0];return f+' '+execSync('git hash-object '+f,{encoding:'utf8'}).trim();});const changed=now.filter(l=>base.indexOf(l)===-1);const expected=['packages/render-anim/src/parse.ts','packages/render-anim/src/animater.ts','packages/render-anim/src/__test__/parse.test.ts','packages/render-anim/src/__test__/animater.test.ts','packages/common/src/logger.json'];const names=changed.map(l=>l.split(' ')[0]);const missing=expected.filter(f=>names.indexOf(f)===-1);const extra=names.filter(n=>expected.indexOf(n)===-1);console.log('changed:\n'+changed.join('\n'));if(base.length!==8||missing.length||extra.length){console.error('unexpected changed set; missing='+missing.join(',')+' extra='+extra.join(','));process.exit(1);}console.log('OK: PLAN excluded; exactly the 5 intended files changed among the 8 compared baselines');"</automated>
<fails_when>排除 `09-56-PLAN.md` 后变化的文件不是恰好 5 个目标文件(含 `types.ts` / `index.ts` / `package.json` 被改动),或比较基线行数不是 8(打印差异,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const f='.planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md';const s=fs.readFileSync(f,'utf8');const need=['09-56','parse.ts','animater.ts','logger.json','82','91','92','95','sequence','composeFrame','MotaOffscreenCanvas2D','once','cycled','#region','prettier-ignore','isRecord','validateMeta','vitest','prettier','eslint','vue-tsc','213','0 次提交','偏差','未校准','70','9'];const miss=need.filter(n=>s.indexOf(n)===-1);if(miss.length){console.error('missing '+miss.join(','));process.exit(1);}console.log('OK: summary content present');"</automated>
<fails_when>SUMMARY 缺少文件清单 / 错误码映射 / 行为变更 / 注释变更 / 明确未改项 / 测试数量 / 门禁结果 / 偏差 / 未校准估算 / 0 提交等关键内容(打印缺失项,退出码 1)。</fails_when>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const base=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-56-status.txt','utf8').split(/\r?\n/).filter(l=>l.length>0);const cur=execSync('git status --porcelain -uall',{encoding:'utf8'}).split(/\r?\n/).filter(l=>l.length>0);const summary='?? .planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md';const added=cur.filter(l=>base.indexOf(l)===-1);const removed=base.filter(l=>cur.indexOf(l)===-1);const inScope=l=>{const p=l.slice(3);return p.indexOf('packages/render-anim/')===0||p.indexOf('packages/common/src/logger.json')===0||p.indexOf('.planning/phases/09-minimum-browser-runnable/')===0;};const addedIn=added.filter(inScope);const addedOut=added.filter(l=>!inScope(l));const removedIn=removed.filter(inScope);const removedOut=removed.filter(l=>!inScope(l));const extra=addedIn.filter(l=>l!==summary);const missing=addedIn.indexOf(summary)===-1?[summary]:[];console.log('addedIn:\n'+addedIn.join('\n'));if(extra.length||missing.length||removedIn.length||addedOut.length||removedOut.length){console.error('post-write range drift');process.exit(1);}console.log('OK: post-write range is exactly the summary');"</automated>
<fails_when>写后 `addedIn` 不是恰好 `09-56-SUMMARY.md`,或出现 `extra` / `missing` / `removedIn` / `addedOut` / `removedOut`(退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const b=fs.readFileSync('.planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md');const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;const ok=lf===crlf&&tabs===0&&!bom;console.log((ok?'OK':'FAIL')+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);process.exit(ok?0:1);"</automated>
<fails_when>SUMMARY 出现非 CRLF 换行、制表符或 BOM(打印 `FAIL`,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- 写 SUMMARY 前的范围闸门在 `<action>` 第 1 步内联执行:除 SUMMARY 自身外无新增 / 删除条目,且显式断言 `09-56-SUMMARY.md` 尚不存在(`fs.existsSync` 为 false,git status 无该条目);仓库根目录无 `*.tsbuildinfo` 且 git status 无 `tsbuildinfo` 条目。
- 哈希闸门:排除 `09-56-PLAN.md` 后比较 8 条基线,只有 5 个目标文件变化(预期变化集合恰为 5);`types.ts` / `index.ts` / `package.json` 不变。
- `09-56-SUMMARY.md` 已写入(UTF-8 无 BOM + CRLF),覆盖文件清单、测试数量(parse 实测 + animater 9;声明 79 为合计、此前规划输入曾误写成 79 parse,以实测 70 + 9 为准)、82–95 → 82–91 映射(含旧 88 元组三态)、`MotaOffscreenCanvas2D` 单画布行为变更、`#region` / jsDoc 变更、类级 jsDoc 文档债、明确未改项、门禁真实输出、偏差、未校准估算。
- 写后范围闸门:`added` 恰为 `09-56-SUMMARY.md`;0 次提交;未运行游戏 / 浏览器 / dev server / `pnpm install`。
</acceptance_criteria>
<done>写前范围闸门与哈希闸门通过(只有 5 个目标文件变化);`09-56-SUMMARY.md` 已写入并覆盖文件清单、测试数量与差异、错误码映射、单画布行为变更、注释变更、明确未改项、门禁结果、偏差与未校准估算;写后范围闸门通过;0 次提交。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 动画二进制 → 解析器 | `.animate` 文件是不可信输入;头部 / 长度 / sprite 表 / JSON / 位图 / 对象索引全部在 `parse.ts` 内校验,失败只记日志并返回 `null` |
| 解析器 → 日志系统 | 失败原因编码为 82–91 的固定消息;调用点只传原因标签 / 数字 / 字段名 / `'-'` / 91 的异常 message,不把整句或文件内容塞进参数 |
| 解析器 / 合成器 → 画布 | `sequence` 复用同一块离屏画布逐帧重绘;若某帧不清空,上一帧像素会残留到下一帧 |
| 日志表 → 全仓调用点 | 合并 82–91 会改变码段含义;旧 92–95 的删除必须与 `parse.ts` / 测试同步,否则会命中 `logger.error(16)` 兜底 |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|----------|----------|-------------|-----------------|
| T-56-01 | Tampering | `parse.ts` 校验条件 | high | mitigate | 本计划只改注释与 logger 实参;Task 3 / Task 5 门禁断言 `try` 仍 3 处、无 `throw` / `finally`、可空签名、可选字段 `!== undefined`、`isRecord` 的 `value !== null` 与 `validateMeta` 嵌套不变 |
| T-56-02 | Tampering | `logger.json` 码段 | high | mitigate | Task 2 / Task 6 用 Task 1 快照深比较:`1..81`、`2001..2008` 与整个 `warn` 段(含 `213` / `1001`)逐字不变;82–91 十条消息逐字比对计划表、两两不同、禁止 `$1`-only;92–95 删除 |
| T-56-03 | Denial of Service | `animater.ts` 画布复用 | medium | mitigate | 复用画布必须逐帧 `canvas.size(frame.width, frame.height)`;`MotaOffscreenCanvas2D.size()` 会重设 `canvas.width/height` 从而重置变换并清空上一帧;Task 4 / Task 5 门禁断言 `composeFrame` 内不构造画布、`sequence` 恰一处构造、`source` 始终为同一 `canvas.canvas` |
| T-56-04 | Information Disclosure | `parse.ts` 日志参数 | low | mitigate | 音效 `name` 只记录 `typeof item.name`,不把不可信名称写入日志;91 只记录解码 / 纹理异常的 `message`;单引号字面量内容不含空格(Task 3 门禁只检查 `m[1]`,不误判相邻字面量之间的文本) |
| T-56-05 | Denial of Service | 资源释放 | medium | mitigate | 保留「位图越界先 `image.close()` 再记日志」「纹理创建失败先 `image.close()`」;正常结束 `clear()` + 归零;提前 `.return()` 不写 `finally`,避免吞掉异常或引入额外分支 |
| T-56-06 | Tampering | 注释 / jsDoc 误改 | medium | mitigate | 用户撰写的类级 jsDoc 用 Task 1 **整块**快照 + Task 4 / Task 5 全块比对与 `/**` 块计数校验;成员名集合与 Task 1 快照比对(禁止新增 / 重命名方法或字段);`once` / `cycled` jsDoc 的删除有 `ITextureAnimater` 接口文档支撑;不改 early return / `validateMeta` 嵌套 |
| T-56-SC | Tampering | 依赖安装 | high | mitigate | 不新增任何依赖、不执行 `pnpm install`、不访问 registry、不改锁文件 |
</threat_model>
<verification>
- **单画布(核心)**:`animater.ts` 中 `new MotaOffscreenCanvas2D()` 恰 1 处且位于 `sequence`(空帧判断之后);`composeFrame(canvas, texture, data, frame): void` 每帧 `canvas.size(frame.width, frame.height)` 且内部不构造画布;每帧 `yield` 同一个 `canvas.canvas`;正常结束 `clear()` + 宽高归零;提前 `.return()` 不清空、保留最后一帧;无 `try` / `finally`。
- **注释 / jsDoc**:`parse.ts` 12 个顶层函数为**紧邻** `function <name>` 的多行 jsDoc + `@param` / `@returns`,无 `@throws`;`composeFrame` / `sequence` 多行 jsDoc;`once` / `cycled` 无 jsDoc;`animater.ts` 类级 jsDoc 全块与 Task 1 快照逐字一致、紧邻类声明、文件恰 3 个 `/**` 块;成员名集合与 Task 1 快照一致;`parse.ts` 无 `//#region 导出解析器`,`animater.ts` 无 region;两文件无 `// prettier-ignore`;补入字节偏移 / 校验顺序 / 帧数学 / close-before-log / 单画布 / 变换顺序 / 清理语义等行内注释(必需子串门禁通过)。
- **logger 表**:`logger.json` error 82–91 十条具体消息逐字匹配计划表、两两不同、非 `$1`-only;92–95 删除;`1..81` / `2001..2008` / `warn`(含 `213` / `1001`)与 Task 1 快照逐字一致;无新增 `1000+`。
- **logger 调用点**:`parse.ts` 只传原因标签 / 数字字符串 / 字段名 / `'-'` / `reason`;无**字面量内容**含空格的字符串(相邻字面量之间的文本不误判);82–91 全部有调用点,92–95 无调用点。
- **测试**:`parse.test.ts` 只覆盖 82–91(含非对象元数据 5 条、越界 `out-of-bounds` + 图像尺寸、解码 / 纹理 `91`),静态闸门使用新 90 号守卫文本并保留 3 处 `try`,含 `ERROR_PARAM_COUNTS` 与 `expectFailure` arity 断言;`animater.test.ts` 9 条用例统一 `const canvas = fakes.instances[0]` 并断言 `canvas.canvas.width/height`,覆盖单画布 / 同一 `source` / 逐帧尺寸 / 归零 / 提前 return / 空帧 0 实例 / 变换 / 不释放纹理;每个 `it` 有一行注释;targeted vitest 全通过(parse ≥ 70,animater = 9)。
- **格式 / lint / 类型**:prettier `--check`、eslint、CRLF / BOM / tab 对 5 个改动文件通过;`vue-tsc --version` 哨兵通过,`--noEmit --incremental false` 过滤 `packages[\\/]render-anim` 诊断 0 行(参数被拒则回退并清理);仓库根目录无 `*.tsbuildinfo`、git status 无 `tsbuildinfo`;SUMMARY 记录真实结果。
- **范围 / 哈希**:Task 5 前后无新增状态条目(含无 `*.tsbuildinfo`);Task 6 写后仅新增 `09-56-SUMMARY.md`;Task 6 哈希闸门排除 `09-56-PLAN.md` 后比较 8 条基线,只有 5 个目标文件变化。
- **明确不做**:不运行游戏 / 浏览器 / dev server / `pnpm install`;不做真实 WebP 素材与像素 E2E;不改类级 jsDoc、early return、`validateMeta` 嵌套;不执行 git 写命令,0 次提交。
</verification>
<success_criteria>
- [ ] Task 0 已向用户完整汇报注释 / jsDoc 清单、82–91 logger 表与调用点参数、单画布设计、明确不改项(含类级 jsDoc 文档债与成员名不变)、测试更新预期(含 70 + 9、arity 映射与「79 为合计、此前规划输入曾误写成 79 parse」的说明)、门禁形态与影响范围,并等待用户针对本计划回复「可以执行」后才继续。
- [ ] `animater.ts` 的 `sequence` 每序列只创建 1 块画布并逐帧复用;`composeFrame(canvas, texture, data, frame): void` 每帧 `size()` 且不构造画布;每帧同一 `source`;正常结束 `clear()` + 归零;提前 `.return()` 保留最后一帧;无 `try` / `finally`。
- [ ] `parse.ts` 12 个顶层函数为**紧邻** `function` 的多行 jsDoc(`@param` / `@returns`,无 `@throws`)并补入有价值行内注释(必需子串门禁通过);导出 region 与 `// prettier-ignore` 删除;3 处 `try`、无 `throw` / `finally`、可空签名、`isRecord` 的 `value !== null`、可选字段 `!== undefined`、`validateMeta` 嵌套均未改动。
- [ ] `animater.ts` 删除全部 region、删除 `once` / `cycled` 的 jsDoc、删除 `// prettier-ignore`;`composeFrame` / `sequence` 多行 jsDoc;类级 jsDoc 全块与 Task 1 快照逐字一致且恰 3 个 `/**` 块(未新增类级注释);成员名集合与快照一致(无新增 / 重命名方法或字段)。
- [ ] `logger.json` error 合并为 82–91 的 10 条具体消息(占位 3/2/2/6/10/4/5/5/2/2,两两不同、无泛化消息),92–95 删除;`1..81`、`2001..2008` 与整个 `warn` 段(含 `213` / `1001`)逐字不变;无新增 `1000+`。
- [ ] `parse.ts` 的 logger 调用点只传标签 / 数字 / 字段名 / `'-'` / 异常 message,不再有字面量内容含空格的整句参数。
- [ ] `parse.test.ts` 期望码与注释同步为 82–91、静态闸门更新、含 `ERROR_PARAM_COUNTS` 与 arity 断言;`animater.test.ts` 为单画布语义的 9 条用例且统一 `const canvas = fakes.instances[0]` / `canvas.canvas.width/height`;targeted vitest 全部通过,parse 用例 ≥ 70。
- [ ] prettier、eslint、CRLF / BOM、综合静态门禁通过;`vue-tsc` 经哨兵确认可启动后以 `--noEmit --incremental false` 过滤 `packages[\\/]render-anim` 诊断为 0 行;仓库根目录无 `*.tsbuildinfo`、git status 无 `tsbuildinfo` 条目。
- [ ] 除规划 / 修订流程可能写 `09-56-PLAN.md` 外,`types.ts` / `index.ts` / `package.json` 哈希不变;未修改其它包或配置;未新增依赖。
- [ ] `09-56-SUMMARY.md` 已写入(UTF-8 无 BOM + CRLF),包含文件清单、测试数量与差异、82–95 → 82–91 映射、单画布行为变更、注释 / jsDoc 变更、类级 jsDoc 文档债、明确未改项、门禁真实输出、偏差与未校准估算(advisory + smart-zone 说明)。
- [ ] 范围闸门与哈希闸门通过;0 次提交;未运行游戏 / 浏览器 / dev server / `pnpm install`。
</success_criteria>
<output>
Create `.planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md` when done
</output>
@@ -0,0 +1,173 @@
---
phase: 09-minimum-browser-runnable
plan: 56
subsystem: render-anim
tags:
- render-anim
- animation
- jsdoc
- logger
- error-codes
- single-canvas
- vitest
requires:
- 09-55 parseRenderAnimation v2 binary parser with logger.error codes 82..95
provides:
- parse.ts multi-line jsDoc and meaningful inline comments for 12 top-level functions
- logger.json error codes merged from 82..95 into 82..91 with specific messages
- animater.ts single offscreen canvas reuse per sequence
- parse.test.ts updated expected codes, arity map and static guard
- animater.test.ts single-canvas semantics (9 tests)
affects:
- packages/render-anim/src/parse.ts
- packages/render-anim/src/animater.ts
- packages/render-anim/src/__test__/parse.test.ts
- packages/render-anim/src/__test__/animater.test.ts
- packages/common/src/logger.json
actuals:
tokens: 24494
tasks: 6
commits: 0
tech-stack:
patterns:
- one MotaOffscreenCanvas2D per sequence, resized per frame with canvas.size
- logger.error only receives low-cardinality reason labels, numbers, field names, '-' placeholders
- logger.json error 82..91 with matching $n arity 3/2/2/6/10/4/5/5/2/2
key-files:
modified:
- packages/render-anim/src/parse.ts
- packages/render-anim/src/animater.ts
- packages/render-anim/src/__test__/parse.test.ts
- packages/render-anim/src/__test__/animater.test.ts
- packages/common/src/logger.json
- .planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md
key-decisions:
- sequence creates exactly one MotaOffscreenCanvas2D after the empty-frames guard and reuses it
- composeFrame(canvas, texture, data, frame): void resizes with canvas.size each frame and no longer constructs a canvas
- normal completion calls canvas.clear() and zeroes canvas.canvas.width / height; early .return() does not use finally
- logger.json error 82..95 merged into 82..91, 92..95 deleted, 1..81 / 2001..2008 / warn incl. 213 and 1001 verbatim
- parse.ts logger call sites pass only reason labels, numbers, field names, '-' or the 91 reason message
- the class-level jsDoc of RenderAnimater is preserved verbatim and no class comment is added
patterns-established:
- readRawMeta comment precedes the !isRecord(meta) guard so the compact static assertion stays stable
- animater tests assert const canvas = fakes.instances[0] plus canvas.canvas.width / height
duration: 约 14 分钟
completed: 2026-11-09T18:30:00+08:00
status: complete
---
# Phase 09 Plan 56: 动画解析器注释 / logger 合并与单画布复用 Summary
为 `@motajs/render-anim` 补齐 `parse.ts` / `animater.ts` 的注释与 jsDoc、把 logger error 82–95 合并为 82–91,并把 `sequence` 从每帧新建离屏画布改为每个序列复用一块画布。
## 本计划范围
`files_modified` 共 6 个路径:
- `packages/render-anim/src/parse.ts`
- `packages/render-anim/src/animater.ts`
- `packages/render-anim/src/__test__/parse.test.ts`
- `packages/render-anim/src/__test__/animater.test.ts`
- `packages/common/src/logger.json`
- `.planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md`
本计划编号为 09-56(09-01..09-55 已占用),波次 5,`depends_on: 09-55`。只写上述 5 个目标文件与本 SUMMARY;`types.ts` / `index.ts` / `package.json` 只验证不改(哈希基线一致);不跑游戏 / 浏览器 / dev server / `pnpm install`;不执行 git 写命令,**0 次提交**。
## 文件清单
| 文件 | 变更 |
|------|------|
| `packages/render-anim/src/parse.ts` | 12 个顶层函数多行 jsDoc + 行内注释、logger 调用点改为 82–91、删除导出 region 与 `// prettier-ignore` |
| `packages/render-anim/src/animater.ts` | 单画布复用、composeFrame / sequence 多行 jsDoc、删除 3 组 region 与 once / cycled jsDoc、类级 jsDoc 原样保留 |
| `packages/render-anim/src/__test__/parse.test.ts` | 期望码 82–91、注释同步、ERROR_PARAM_COUNTS 与 arity 断言、静态闸门更新 |
| `packages/render-anim/src/__test__/animater.test.ts` | 9 条单画布语义用例 |
| `packages/common/src/logger.json` | error 82–91 共 10 条具体消息,删除 92–95 |
| `.planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md` | 本摘要 |
## 测试数量
- `parse.test.ts`:70 个用例(实测)。
- `animater.test.ts`:9 个用例(实测)。
- 合计:79 passed。
**说明:** 实测基线为 70 个 parse 用例 + 9 个 animater 用例 = 79 passed;79 是合计,不是 parse 用例数。此前规划输入曾误写成 79 parse,本计划以实测 70 + 9 为准。改写后 parse 用例仍为 70、animater 仍为 9,数量未退化。
`parse.test.ts` 新增 `ERROR_PARAM_COUNTS`(82–91 → 3/2/2/6/10/4/5/5/2/2),`expectFailure` 额外断言 `loggerMock.error.mock.calls[0].length === ERROR_PARAM_COUNTS[code] + 1`,校验调用点 arity 而不只是错误码存在。
## 错误码映射表(旧 → 新)
| 旧码 | 新码 | 触发位置 |
|------|------|----------|
| 82 | 82 | 容器头过短 / 头部长度不一致 |
| 83 | 83 | 签名不匹配 |
| 84 | 84 | 版本不支持 |
| 85 | 82 | 总长度不一致(旧 85 并入 82) |
| 86 | 85 | sprite 数量 < 1 / 尺寸表越界 / 宽高 < 1 |
| 87 | 86 | 位图列表非数组 / 数量不符 / 项非对象 / 字段非法 / 解码后越界 |
| 88(帧结构) | 87 | frame 非数组 / 帧项非对象 / objects 非数组 / sound 非数组 |
| 88(对象项非数组 / 元组 4 元 / 元组 8 元) | 88 | not-tuple / invalid-field-count |
| 88(元数据非对象) | 90 | readRawMeta 守卫与 validateMeta 纵深防御 |
| 89 | 88 | 对象位图索引越界 / 非整数 |
| 90 | 88 | 对象 x / y / scale / opacity / mirror / rotate 非法 |
| 91 | 89 | ratio 非法 |
| 92 | 89 | blend 非法 |
| 93 | 89 | 音效项非对象 / name / volume / pitch 非法 |
| 94 | 90 | 元数据 JSON 解析失败(invalid-json) |
| 95 | 91 | 图像解码失败(decode-failed)/ 纹理创建失败(texture-failed) |
- 92–95 已删除;`1..81`、`2001..2008` 与整个 `warn` 段(含并发 `213` 与既有 `1001`)逐字未变。
- 未新增任何 `1000+` 码。
## 行为变更说明
- `sequence` 在 `frames.length === 0` 判断之后只创建一块 `MotaOffscreenCanvas2D`,`setHD(false)` / `setAntiAliasing(false)` 各一次。
- `composeFrame(canvas, texture, data, frame): void` 每帧首行 `canvas.size(frame.width, frame.height)`(重设尺寸会重置变换矩阵并清空上一帧),内部不再构造画布。
- 每帧 `yield` 同一个 `canvas.canvas`,`rect` 仍为 `{ x: 0, y: 0, w: frame.width, h: frame.height }`。
- 正常播放结束 `canvas.clear()` 并把 `canvas.canvas.width` / `height` 置 0;提前 `.return()` 不写 `finally`、不做兜底清理,最后一帧留在同一画布交给垃圾回收。
- `composeFrame` 签名由 `(texture, data, frame) => MotaOffscreenCanvas2D` 改为 `(canvas, texture, data, frame) => void`,方法名与其它成员名不变。
## 注释 / jsDoc 变更
- `parse.ts` 12 个顶层函数(`isRecord` / `isNumber` / `isInteger` / `readHeader` / `readSpriteDimensions` / `readRawMeta` / `validateMeta` / `validateBitmapBounds` / `toObject` / `toFrame` / `computeFrameBox` / `toBlendMode`)改为紧邻 `function` 的多行 jsDoc,带 `@param` / `@returns`,无 `@throws`。
- 补充字节偏移、校验顺序、帧包围盒半宽 / 半高公式、先 close 再记日志等行内注释;`readRawMeta` 的 primitive 注释位于 `if (!isRecord(meta))` 之前。
- `animater.ts` 的 `composeFrame` / `sequence` 改为多行 jsDoc;删除 `once` / `cycled` 的 jsDoc(`ITextureAnimater` 接口已文档化)。
- 删除 `animater.ts` 全部 3 组 `#region` / `#endregion`;删除 `parse.ts` 的导出 region(保留其余 3 个功能性 region)。
- 删除两处 `// prettier-ignore`(86 号多参数调用自然换行;`ctx.rotate` 提取 `angle` 中间量)。
- 类级 jsDoc 全块逐字未动;文件恰有 3 个 `/**` 块(类 + composeFrame + sequence),未新增任何类级注释。
- 成员名集合保持 `composeFrame` / `cycled` / `once` / `sequence`(`composeFrame` 仅改签名)。
## 类级 jsDoc 文档债
类级 jsDoc 中「每次 `.next()` 恢复后会释放上一帧」在单画布复用后已不准确(现在复用同一块画布、不逐帧释放);按用户要求逐字保留,未经另行批准不得改写。
## 明确未改项
- 未把 `if (!x) return` 一类提前返回当作违规改写。
- 未改动 `validateMeta` 的嵌套层级与结构。
- 可选原始字段仍使用 `!== undefined`(`object[5]` / `object[6]` / `item.volume` / `item.pitch`)。
- `isRecord` 仍使用 `value !== null`(未引入 `isNil` / `!value`)。
- 未改 `parseRenderAnimation` 的签名、3 处窄 `try/catch` 与可空返回;无 `throw` / `finally`;`new Blob` 在 `try` 外;位图越界先 close 再记日志;纹理失败先 close。
## 门禁结果
- `node node_modules/vitest/vitest.mjs run parse.test.ts animater.test.ts`:2 files / 79 passed(70 parse + 9 animater)。
- `prettier --check`:5 个改动文件全部通过。
- `eslint`:两个源码 + 两个测试,无 error / warning。
- CRLF / 无 BOM / 无 tab:5 个改动文件全部通过。
- `vue-tsc --version` 哨兵通过(Version 6.0.3);`--noEmit --incremental false` 过滤 `packages[\\/]render-anim` 诊断为 0 行(全仓其它包既有诊断导致进程退出码 2,不参与判定)。
- 仓库根目录无 `*.tsbuildinfo`,`git status` 无 `tsbuildinfo` 条目。
- 综合静态门禁:animater 无 region / 无 `// prettier-ignore` / 类级 jsDoc 全块逐字一致且紧邻类声明 / 恰 3 个 `/**` 块 / 成员名集合不变 / once / cycled 无 jsDoc / sequence 恰 1 处画布构造 / composeFrame 内不构造 / 无 try / finally;parse 无导出 region / 无 `// prettier-ignore` / 无 `@throws` / 无字面量内容含空格 / 12 个 jsDoc 紧邻 `function` / 必需行内注释齐全且 readRawMeta 注释在守卫之前 / try 恰 3 处 / 82–91 全在、92–95 不在 / 可选字段与 isRecord 不变量保留;logger 82–91 两两不同且非 `$1`-only;测试文件无 92–95 且含 arity 映射与断言。
- 哈希闸门:排除 `09-56-PLAN.md` 后比较 8 条基线,恰有 5 个目标文件变化,`types.ts` / `index.ts` / `package.json` 不变。
- 写后范围闸门:`git status` 仅新增本 `09-56-SUMMARY.md`,无其它新增 / 删除条目。
## 偏差
无。计划命令均可按原样执行,未发现需要修正的计划命令缺陷;未触发行为 / 代码歧义。
## 未校准估算
`confidence: low`、`tokens: 110000`(7 个任务 / 110k 仅为 advisory 建议值;plan-checker 已指出可能超出 smart-zone,但按用户要求保持单计划不拆分,不作为拆分依据、不阻断执行)。本次按改动文件 `chars/4` 实测约 24494 tokens。
## 可见跳过
spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip)。
@@ -0,0 +1,782 @@
---
phase: 09-minimum-browser-runnable
plan: 57
type: execute
# 编号说明:09-01..09-56 均已占用,本计划使用下一个空闲编号 09-57。
# depends_on 09-56:本计划只改 09-56 落地的 parse.ts / parse.test.ts logger 调用点与 logger.json,不改 animater.ts。
wave: 6
depends_on:
- 09-56
files_modified:
- packages/render-anim/src/parse.ts
- packages/render-anim/src/__test__/parse.test.ts
- packages/common/src/logger.json
- .planning/phases/09-minimum-browser-runnable/09-57-SUMMARY.md
autonomous: false
requirements: []
estimate:
# 未校准估算(confidence: low),SUMMARY 须声明。7 个任务 / 80k 仅为 advisory 建议值,
# 不作为拆分或阻断依据。成本主要在 parse.ts 全部 logger 调用点的重写、
# logger.json error 82–96 的 15 条消息、parse.test.ts 期望码 / arity / 静态闸门的同步,
# 以及 vitest / prettier / eslint / 过滤 vue-tsc 的往返。
tokens: 80000
raw_tokens: 80000
tasks: 7
confidence: low
must_haves:
truths:
- "**第一个 block 点是 Task 0 的 `blocking-human` 汇报关卡(AGENTS.md / D-03)**:逐字汇报 82–96 logger 表、调用点参数规范、明确不改项与影响范围,然后停下等待用户恰好回复「可以执行」。"
- "**logger.json error 82–96(替换 09-56 的 82–91)**:15 条具体消息逐字采用「logger.json error 82–96 最终文本」表;占位符数量为 1/0/0/1/1/1/2/1/0/2/3/1/3/1/1;两两不同;不存在 `Cannot parse animation: $1.` 泛化消息;`1..81`、`2001..2008`、整个 `warn` 段(含 213 / 1001)逐字不变;不新增任何 `1000+` 码。"
- "**parse.ts 调用点只传原因 + 索引(用户规则)**:parser 诊断只需错误原因与对应索引,具体值(actual/expected、尺寸、x/y/w/h、图像宽高、JSON 大小、异常 message)一律不传;每个 `logger.error` 至多 3 个参数;索引只用 `.toString()`;原因只用小写连字符标签;不存在 `'-'` 占位、`String(value)`、`.message`、尺寸/坐标/图像维度的实参。"
- "**parse.ts 行为不变**:校验逻辑、提前返回、`validateMeta` 嵌套、可选字段 `!== undefined`、`isRecord` 的 `value !== null`、`parseRenderAnimation` 签名、3 处窄 `try/catch`、无 `throw` / `finally`、`new Blob` 在 `try` 外、位图越界先 `image.close()` 再记日志、纹理失败先关闭图像——全部保持 09-56 现状;catch 块改为无绑定 `catch { ... }`。"
- "**保留 09-56 注释成果**:09-56 的 jsDoc / 行内注释 / 3 组功能性 `#region` / 类级 jsDoc / 单画布改动一律不动;不得修改 `animater.ts` / `types.ts` / `index.ts` / `package.json`。"
- "**parse.test.ts 同步到 82–96**:期望码、注释、`ERROR_PARAM_COUNTS`(82:1,83:0,84:0,85:1,86:1,87:1,88:2,89:1,90:0,91:2,92:3,93:1,94:3,95:1,96:1)、`expectFailure` 的 arity 断言、静态闸门(`catch{`、95 号守卫)全部同步;92–96 现在都是合法码,测试与门禁均不得断言 92–95 缺失(无需新增或删除针对 92–95 的否定断言);新增「无值实参」静态断言;保留 70 个用例,每个 `it` 前有一行注释。"
- "**范围受控、0 提交**:只写 `files_modified` 的 4 个路径;不跑游戏 / 浏览器 / dev server / `pnpm install`;不执行 git 写命令,0 次提交。"
- "**风格一致**:82–96 的具体措辞对齐 `logger.json` 既有风格(具体上下文 + `reason: '$n'` 或索引,无具体值),例如 warn 44 / error 63-67 / warn 179。"
artifacts:
- path: packages/render-anim/src/parse.ts
provides: "82–96 的低基数 logger 调用点(原因 + 索引),行为与 09-56 完全一致"
- path: packages/render-anim/src/__test__/parse.test.ts
provides: "82–96 期望码、ERROR_PARAM_COUNTS、arity / 无值实参静态闸门、70 个用例"
- path: packages/common/src/logger.json
provides: "error 82–96 共 15 条具体消息;其余码段与 warn 逐字不变"
- path: .planning/phases/09-minimum-browser-runnable/09-57-SUMMARY.md
provides: "文件清单、错误码映射、测试数量、风格说明、偏差与真实门禁输出"
key_links:
- "`logger.json` error 82–96 ↔ `parse.ts` 调用点:消息文本、`$n` 数量、实参顺序三者必须一致"
- "`parse.test.ts` 的 `ERROR_PARAM_COUNTS` ↔ `logger.json` 占位符数量:两者都必须等于 82:1,83:0,84:0,85:1,86:1,87:1,88:2,89:1,90:0,91:2,92:3,93:1,94:3,95:1,96:1"
- "`parse.test.ts` 静态闸门 ↔ `parse.ts` 结构:恰 3 处 `try {`、两处无绑定 `catch {`、95 号守卫 compact 文本、`validateMeta` / `validateBitmapBounds` 内无 `forEach`"
- "`validateBitmapBounds` 的 `imageWidth` / `imageHeight` ↔ 越界判断:仍在 `close()` 前读取用于判定,只是不再写入日志"
- "`parseRenderAnimation` 的 decode / texture catch ↔ 96 号:`catch { ... }` 无绑定,96 号只传 `decode-failed` / `texture-failed`"
assumptions:
- "**工作树基线(规划日实测,2026-11-09)**:HEAD `7bf9fe9`;`packages/render-anim/src/parse.ts` 839 行、`hash-object 98823f4b56a5e8b13ab3f8dd899b43850c1a06f9`;`packages/render-anim/src/__test__/parse.test.ts` 899 行、`hash-object 409b706945dedc96ae89927dbc649ed8a284d546`;`packages/common/src/logger.json` `hash-object 3b37f336b012d671034d2bf255edf1114a35f0db`。"
- "**测试基线(规划日实测)**:`packages/render-anim/src/__test__/parse.test.ts` 恰有 70 个 `it`;09-56 SUMMARY 记录 70 parse + 9 animater = 79 passed。本计划只改 parse,改写后 parse 必须仍为 70。"
- "**logger 基线(规划日实测)**:error 段当前为 `1..81` + `82..91` + `2001..2008`;`82..91` 占位符数量为 3/2/2/6/10/4/5/5/2/2;`92..95` 当前不存在;`warn` 段含 `213` 与 `1001`,必须逐字保留。"
- "**当前 parse.ts 过参数化现状**:39 处 `logger.error` 调用;`86` 传 10 个参数、`85` 传 6 个、`87` 传 4 个、`89` 传 5 个,两者均大量使用 `'-'`;`String(meta.ratio)` / `String(bitmap.x)` / `error.message` 等值实参存在;两处 `catch (error)` 使用 `reason` 变量。"
- "**工具链**:`node_modules/vitest/vitest.mjs`、`prettier/bin/prettier.cjs`、`eslint/bin/eslint.js`、`vue-tsc/bin/vue-tsc.js` 均存在。"
- "**本 run 无 RESEARCH / 无 VALIDATION**:本阶段无 requirement ID(`requirements: []`),Nyquist 不适用;spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip)。"
prohibitions:
- "不得在用户恰好回复「可以执行」之前执行任何任务或派发执行子代理(AGENTS.md / D-03)。"
- "不得修改 `animater.ts` / `types.ts` / `index.ts` / `package.json`、其它包、根配置、锁文件或既有计划 / 摘要;不得新增依赖。"
- "不得改任何校验逻辑、提前返回、`validateMeta` 嵌套、可选字段 `!== undefined`、`isRecord` 的 `value !== null`、`parseRenderAnimation` 签名、`try/catch` 的作用域与数量;不得新增 `throw` / `finally`。"
- "不得修改 09-56 落地的 jsDoc / 行内注释 / `#region` / 类级 jsDoc;不得新增 / 重命名任何公开、受保护、私有方法、字段或导出命名。"
- "不得传入任何具体值:`'-'`、`String(meta.*)`、`String(bitmap.*)`、`String(object.*)`、`String(item.*)`、`String(signature)`、`String(version)`、`String(image.*)`、`String(error)`、`error.message`,以及 actual / expected / size / dimension / width / height 值。"
- "不得新增 / 删除测试用例(保持 70),不得弱化任何行为断言;每个 `it` 前必须有一行注释。"
- "不得运行游戏、浏览器、dev server、`pnpm install` 或任何 git 写命令;本计划全程 0 次提交。"
---
<!-- planner-discipline-allow: throw -->
<!-- planner-discipline-allow: @throws -->
<!-- planner-discipline-allow: finally -->
<!-- planner-discipline-allow: try -->
<!-- planner-discipline-allow: catch -->
<!-- planner-discipline-allow: #region -->
<!-- planner-discipline-allow: #endregion -->
<!-- planner-discipline-allow: '-' -->
<!-- planner-discipline-allow: String( -->
<!-- planner-discipline-allow: .message -->
<!-- planner-discipline-allow: error.message -->
<!-- planner-discipline-allow: Cannot parse animation: $1. -->
<!-- planner-discipline-allow: !== undefined -->
<!-- planner-discipline-allow: value !== null -->
<!-- planner-discipline-allow: forEach -->
<!-- planner-discipline-allow: MotaOffscreenCanvas2D -->
<objective>
Phase 9 · 第 57 个计划(09-56 的 logger 去参数化增量,D-01 / D-06)—— 把 `@motajs/render-anim` 的 `parse.ts` 解析器诊断收紧为「**错误原因 + 对应索引**」,不再传递任何具体值。
**要解决的问题(用户逐条确认):**
09-56 的 logger 调用点过度参数化:`86` 号传 10 个参数、`85` 号传 6 个、`87` 号传 4 个、`89` 号传 5 个,并且大量使用 `'-'` 占位;还传入了实际值、期望值、尺寸、x/y/w/h、图像宽高、JSON 大小、异常 `message` 等。用户规则:解析器诊断只需 **错误原因 + 对应索引**,具体值对排查无价值且不应传入。每个 `logger.error` 至多 3 个参数、无 `'-'`、无 `String(value)`、无 actual/expected/size/error.message。消息必须保持具体、贴合既有 logger 风格,不得退化为 `Cannot parse animation: $1.`。
**做法(用户设计,锁定):**
- **error 82–96(替换当前 82–91)**:15 条具体消息,逐字见「logger.json error 82–96 最终文本」。
- **调用约定**:82/85/87/93/95/96 → `logger.error(code, reason)`;83/84/90 → `logger.error(code)`;86/89 → `logger.error(code, index.toString())`;88/91 → `logger.error(code, index.toString(), reason)`;92/94 → `logger.error(code, frame.toString(), subIndex.toString(), reason)`。**92/94 固定按「帧索引在前、对象/音效索引在后、reason 最后」传入**(消息 92/94 用 `$1` 表示帧、`$2` 表示对象/音效、`$3` 表示原因,因此 `$2` 是对象/音效索引、`$1` 是帧索引);其余索引按对应消息 `$n` 的顺序传入;reason 一律小写连字符。
- **行为不变**:只改 logger 实参;`parse.ts` 的校验逻辑、提前返回、`validateMeta` 嵌套、可选字段 `!== undefined`、`isRecord` 的 `value !== null`、签名、3 处窄 `try/catch`、无 `throw` / `finally`、`new Blob` 在 `try` 外、位图越界先 close、纹理失败先 close 全部保持。
- **测试同步**:`parse.test.ts` 期望码改为 82–96、`ERROR_PARAM_COUNTS` 更新、`expectFailure` 断言 `calls[0].length === count + 1`、92–96 均为合法码(不得断言 92–95 缺失)、新增无值实参静态断言、保留 70 用例。
**修改方式声明(AGENTS.md):** 执行期间的全部源码、测试与 `09-57-SUMMARY.md` 写入均由**派发子代理(`gsd-executor`)执行**,非内联执行;本计划文件自身由规划流程(`gsd-planner`)创建。除 `files_modified` 外无任何写入。
**可见跳过:** spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip)。本阶段无 requirement ID,不创建 RESEARCH.md / VALIDATION.md。
</objective>
## 本计划产出物(Artifacts this plan produces)
| 类型 | 名称 / 路径 | 说明 |
|------|-------------|------|
| 改写(解析器) | `packages/render-anim/src/parse.ts` | 82–96 的低基数 logger 调用点;行为与 09-56 一致 |
| 改写(解析测试) | `packages/render-anim/src/__test__/parse.test.ts` | 82–96 期望码、arity、注释、静态闸门;70 用例 |
| 修改(日志表) | `packages/common/src/logger.json` | error 82–96 共 15 条;92–95 重新作为合法码加入 |
| 交付 | `.planning/phases/09-minimum-browser-runnable/09-57-SUMMARY.md` | 文件清单、映射、测试数量、风格说明、偏差 |
| 只验证不修改 | `animater.ts` / `types.ts` / `index.ts` / `package.json` | 哈希与 Task 1 基线一致 |
## 已确认问题清单(唯一依据)
| # | 文件 | 问题 | 处理 |
|---|------|------|------|
| 1 | `parse.ts` | `86` 传 10 个参数(含 bitmap 索引、计数、sprite 计数、x/y/w/h、图像宽高) | 拆为 87/88/89 的低基数调用(旧 86 的位图列表 / 位图项 / 越界三处站点分别映射到 87 / 88 / 89) |
| 2 | `parse.ts` | `85` 传 6 个参数(index、count、width、height、imageDataSize) | 85 只传 `invalid-count` / `table-overflow`;单 sprite 宽高非法改为 86 只传索引 |
| 3 | `parse.ts` | `87` 传 4 个参数、`89` 传 5 个参数,且大量 `'-'` | 帧结构 → 90/91;ratio/blend → 93;音效 → 94 |
| 4 | `parse.ts` | `String(meta.*)` / `String(bitmap.*)` / `String(object.*)` / `String(item.*)` 值实参 | 全部删除,只保留原因与索引 |
| 5 | `parse.ts` | `error.message` / `String(error)` 作为 91 的 detail | 删除 `reason` 变量,96 只传 `decode-failed` / `texture-failed` |
| 6 | `parse.ts` | 83/84 传 signature / version 值 | 83/84 改为 0 参数 |
| 7 | `logger.json` | error 82–91 消息含 buffer 长度、期望长度、计数、尺寸、字段值等 | 重写为 82–96 的 15 条「具体上下文 + reason/index」消息 |
| 8 | `parse.test.ts` | 期望码、arity 映射与静态闸门仍指向 09-56 | 同步为 82–96;92–96 均为合法码,不断言 92–95 缺失 |
## logger.json error 82–96 最终文本(逐字写入,唯一依据)
| code | message | 占位符数 |
|------|---------|----------|
| 82 | `Cannot parse animation: invalid header, reason: '$1'.` | 1 |
| 83 | `Cannot parse animation: invalid signature.` | 0 |
| 84 | `Cannot parse animation: unsupported version.` | 0 |
| 85 | `Cannot parse animation: invalid sprite table, reason: '$1'.` | 1 |
| 86 | `Cannot parse animation: invalid sprite $1.` | 1 |
| 87 | `Cannot parse animation: invalid bitmap table, reason: '$1'.` | 1 |
| 88 | `Cannot parse animation: invalid bitmap $1, reason: '$2'.` | 2 |
| 89 | `Cannot parse animation: bitmap $1 exceeds the decoded image.` | 1 |
| 90 | `Cannot parse animation: frame list is invalid.` | 0 |
| 91 | `Cannot parse animation: invalid frame $1, reason: '$2'.` | 2 |
| 92 | `Cannot parse animation: invalid object $2 in frame $1, reason: '$3'.` | 3 |
| 93 | `Cannot parse animation: invalid scalar field, reason: '$1'.` | 1 |
| 94 | `Cannot parse animation: invalid sound $2 in frame $1, reason: '$3'.` | 3 |
| 95 | `Cannot parse animation: invalid metadata, reason: '$1'.` | 1 |
| 96 | `Cannot parse animation: image failed, reason: '$1'.` | 1 |
**约束:** 15 条消息两两不同;不存在 `Cannot parse animation: $1.` 这类泛化消息;`1..81`、`2001..2008`、整个 `warn` 段逐字保留;不新增 `1000+` 码。
## logger 调用点参数规范(唯一依据)
**通用规则:** 每个调用至多 3 个参数(不含 code);索引一律 `.toString()`;原因一律小写连字符;不使用 `'-'` 占位、不传任何值。92/94 固定帧索引在前、对象/音效索引在后、reason 最后(消息 92/94 的 `$1` 是帧、`$2` 是对象/音效、`$3` 是原因)。
| 函数 / 场景 | 新调用 |
|-------------|--------|
| `readHeader` 头过短 | `logger.error(82, 'buffer-too-short')` |
| `readHeader` 长度不符(含 `imageDataSize < 4` / `metaDataSize < 1`) | `logger.error(82, 'length-mismatch')` |
| `readHeader` 签名 | `logger.error(83)` |
| `readHeader` 版本 | `logger.error(84)` |
| `parseRenderAnimation` sprite 数 < 1 | `logger.error(85, 'invalid-count')` |
| `parseRenderAnimation` 尺寸表越界 | `logger.error(85, 'table-overflow')` |
| `readSpriteDimensions` 单个 sprite 宽或高 < 1 | `logger.error(86, i.toString())` |
| `validateMeta` 位图列表非数组 | `logger.error(87, 'not-array')` |
| `validateMeta` 位图数量不符 | `logger.error(87, 'count-mismatch')` |
| `validateMeta` 位图项非对象 | `logger.error(88, i.toString(), 'not-object')` |
| `validateMeta` 位图 x / y / width / height 非法 | `logger.error(88, i.toString(), 'invalid-x' / 'invalid-y' / 'invalid-width' / 'invalid-height')` |
| `validateBitmapBounds` 越界 | `logger.error(89, i.toString())` |
| `validateMeta` frame 非数组 | `logger.error(90)` |
| `validateMeta` 帧项非对象 | `logger.error(91, frameIndex.toString(), 'not-object')` |
| `validateMeta` objects 非数组 | `logger.error(91, frameIndex.toString(), 'objects-not-array')` |
| `validateMeta` sound 非数组 | `logger.error(91, frameIndex.toString(), 'sound-not-array')` |
| `validateMeta` 对象项非数组 | `logger.error(92, frameIndex.toString(), objectIndex.toString(), 'not-tuple')` |
| `validateMeta` 元组字段数非法 | `logger.error(92, frameIndex.toString(), objectIndex.toString(), 'invalid-field-count')` |
| `validateMeta` 对象索引非法 | `logger.error(92, frameIndex.toString(), objectIndex.toString(), 'invalid-index')` |
| `validateMeta` 对象 x / y / scale / opacity / mirror / rotate 非法 | `logger.error(92, frameIndex.toString(), objectIndex.toString(), 'invalid-x' / 'invalid-y' / 'invalid-scale' / 'invalid-opacity' / 'invalid-mirror' / 'invalid-rotate')` |
| `validateMeta` ratio 非法 | `logger.error(93, 'invalid-ratio')` |
| `validateMeta` blend 非法 | `logger.error(93, 'invalid-blend')` |
| `validateMeta` 音效项非对象 | `logger.error(94, frameIndex.toString(), i.toString(), 'not-object')` |
| `validateMeta` 音效 name / volume / pitch 非法 | `logger.error(94, frameIndex.toString(), i.toString(), 'invalid-name' / 'invalid-volume' / 'invalid-pitch')` |
| `readRawMeta` JSON 解析失败 | `logger.error(95, 'invalid-json')` |
| `readRawMeta` 非对象 JSON / `validateMeta` 纵深防御非对象 | `logger.error(95, 'not-object')` |
| `parseRenderAnimation` 解码失败 | `catch { logger.error(96, 'decode-failed'); return null; }` |
| `parseRenderAnimation` 纹理失败 | `catch { image.close(); logger.error(96, 'texture-failed'); return null; }` |
## `parse.ts` 行为不变量(保持 09-56,逐条门禁)
- 校验条件、循环结构、嵌套层级、提前 `return null` / `return false` 一律不改。
- `validateMeta` 的三层嵌套与结构不改;`isRecord` 的 `value !== null` 不改;`object[5]` / `object[6]` / `item.volume` / `item.pitch` 仍用 `!== undefined`。
- `parseRenderAnimation` 签名仍为 `Promise<IAnimationParsedData | null>`;`try/catch` 恰 3 处;无 `throw` / `@throws` / `finally`;`new Blob` 在 `try` 外。
- 两个 catch 改为无绑定 `catch {`,删除 `reason` 变量;纹理失败仍先 `image.close()` 再记日志;位图越界仍先 `image.close()` 再记日志。
- `validateBitmapBounds` 仍在 `close()` 前读取 `image.width` / `image.height` 用于越界判断,只是不再把它们写进日志。
- 09-56 的 jsDoc / 行内注释 / 3 组功能性 `#region` / 类级 jsDoc / 单画布实现逐字保留。
## `parse.test.ts` 改写规格
1. **期望码(逐用例):**
- header:过短 / 总长度不符 / `imageDataSize < 4` / `metaDataSize = 0` → `82`;签名 → `83`;版本 → `84`。
- sprite:count 0 / 尺寸表越界 → `85`;width 0 / height 0 → `86`。
- bitmap:列表非数组 / 数量不符 → `87`;项非对象 / x / y / width / height 非法(含 NaN / 负 / 0)→ `88`;解码后越界 → `89`。
- metadata 原语(`42` / `null` / `0` / `false` / 空字符串)→ `95`;非法 JSON → `95`。
- frame:frame 非数组 → `90`;帧项非对象 / objects 非数组 / sound 非数组 → `91`。
- 对象:非元组 / 4 元 / 8 元 / 索引越界 / 非整数 / x / y / scale 0 / scale NaN / opacity 300 / opacity NaN / mirror NaN / rotate NaN → `92`。其中至少一个 92 用例额外断言 `calls[0][1]` = 帧索引、`calls[0][2]` = 对象索引、`calls[0][3]` = reason(帧索引在前、对象索引在后、reason 最后)。
- ratio 0 / -1 / NaN、blend 2 / -1 / NaN → `93`。
- 音效:name 空 / name 非字符串 / volume NaN / pitch NaN / 音效项非对象 → `94`。其中至少一个 94 用例额外断言 `calls[0][1]` = 帧索引、`calls[0][2]` = 音效索引、`calls[0][3]` = reason(帧索引在前、音效索引在后、reason 最后)。
- 解码失败 / 纹理失败 → `96`。
- 成功用例 11 条不变。
2. **注释同步:** 每个 `it` 前的一行中文注释里出现的旧码改为新码(例如「记录 85」的 sprite 宽高改为「记录 86」、「记录 86」的位图改为「记录 87 / 88 / 89」、「记录 87」的帧结构改为「记录 90 / 91」、「记录 88」的对象改为「记录 92」、「记录 89」的 ratio/blend/音效改为「记录 93 / 94」、「记录 90」的元数据改为「记录 95」、「记录 91」的 image 改为「记录 96」)。
3. **越界用例:** 改为 `expectFailure(..., 89)`;**把旧的 `expect(loggerMock.error.mock.calls[0][1]).toBe('out-of-bounds')` 断言整行替换为 `expect(loggerMock.error.mock.calls[0][1]).toBe('0')`(新 89 号只传索引「0」,不再有 `'out-of-bounds'` 原因)**,保留 `bitmap.close` 被调用;删除旧的 `[9]` / `[10]` 尺寸断言。旧 `'out-of-bounds'` 断言与新 `'0'` 断言不得并存(替换而非追加)。
4. **非对象元数据用例:** 5 条仍额外断言 `calls[0][1] === 'not-object'`(对应 95 号 reason)。
5. **解码 / 纹理用例:** `expectFailure(..., 96)`,分别断言 `calls[0][1] === 'decode-failed'` / `'texture-failed'`,纹理用例保留 `bitmap.close` 被调用。
6. **arity:** `ERROR_PARAM_COUNTS` 改为 `{ 82:1, 83:0, 84:0, 85:1, 86:1, 87:1, 88:2, 89:1, 90:0, 91:2, 92:3, 93:1, 94:3, 95:1, 96:1 }`;`expectFailure` 断言 `loggerMock.error.mock.calls[0].length === ERROR_PARAM_COUNTS[code] + 1`。
7. **静态闸门(在既有 `it('keeps the parser free of throw statements')` 内扩展,不新增 `it`):**
- 保留「无 `throw` / 无 `@throws` / 恰 3 处 `try {` / 无 `finally`」。
- compact 断言把两处 `catch(error)` 改为 `catch{`:`try{image=awaitcreateImageBitmap(webpBlob);}catch{`、`try{texture=newTexture(image);}catch{`。
- 把旧的 `logger.error(90,'not-object',size.toString())` 守卫断言替换为 `if(!isRecord(meta)){logger.error(95,'not-object');returnnull;}returnmeta;`。
- 继续断言 `validateMeta` / `validateBitmapBounds` 体内无 `forEach`。
- 新增「无值实参」断言:**内联在既有静态闸门 `it` 内**,用平衡括号提取 `parse.ts` 的每个 `logger.error(...)` 实参(不新增任何具名辅助函数),断言每段实参要么匹配索引正则 `/^[A-Za-z_][A-Za-z0-9_]*\.toString\(\)$/`,要么是 `'kebab-case'` 原因标签(且属于允许集合);据此排除 `'-'`、`String(...)`、`.message` 与任何具体值。
- 新增断言:82–96 全部出现在 `parse.ts` 的 `logger.error` 调用中;92–96 均为合法码,测试与门禁均不得断言 92–95 缺失(它们是合法码)。
8. **不新增 / 不删除用例:** 总数仍为 70;每个 `it` 前仍有一行注释;成功用例断言不变。
## 风格核对(Task 0 与 Task 6 都要记录)
新 82–96 消息与 `logger.json` 既有风格一致——「具体上下文 + `reason: '$n'` / 索引,无具体值」:
- warn 44:`Unexpected end when loading stream audio, reason: '$1'`
- error 63:`Cannot create game map '$2' from raw data since the '$1' container is missing, null, or not an object.`
- warn 179:`Replay $1 received an out-of-range index $2, the current replay length is $3.`
反例(禁止):`Cannot parse animation: $1.`(只有一个原因串,脱离上下文不可读)。
## 覆盖审计(Multi-Source Coverage Audit)
| 源 | 条目 | 覆盖位置 |
|----|------|----------|
| GOAL(ROADMAP §Phase 9) | 可在浏览器中运行并验证的最小版本 | 解析器诊断可读、无值泄漏,便于排查 |
| REQ | 本阶段无 requirement ID(`requirements: []`) | Nyquist 不适用(可见跳过) |
| RESEARCH | 本 run 无 RESEARCH.md | 依据实测 `parse.ts` / `logger.json` / `logger.ts` |
| CONTEXT D-01 | 增量派发,一个任务一个计划 | 本计划即该派发的唯一计划 |
| CONTEXT D-02 | 计划可累积追加 | plan 57,排在 09-01..09-56 之后 |
| CONTEXT D-03 | 执行前必须先汇报并等待「可以执行」 | Task 0(`blocking-human`),`autonomous: false` |
| CONTEXT D-04 | 新命名必须先反馈获批 | 本计划不新增任何命名 |
| CONTEXT D-05 | 默认不逐阶段验证 | 仍做 targeted vitest / 静态门禁;不做浏览器 E2E |
| CONTEXT D-06 | 范围由用户界定 | `files_modified` 4 项 + Task 1 / Task 6 哈希门禁 |
| 用户设计 | 82–96 消息、调用约定、行为不变、测试同步 | Task 2 / 3 / 4 / 5 逐条对应 |
## 命名与注释批准清单(Task 0 逐项确认)
| 类别 | 名称 | 说明 |
|------|------|------|
| 新增生产命名 | **无** | 不新增 / 重命名任何方法、字段、导出 |
| logger 码段 | error `82`–`96` | 82/85/87 复用既有码;83/84/86/88/89/90/91 复用;92–95 重新启用;96 新增 |
| 既有注释 | 09-56 jsDoc / region / 类级 jsDoc | 逐字保留,不改 |
| 测试局部命名 | `ERROR_PARAM_COUNTS`(既有) | 只改数值,不改名;**不新增任何测试辅助函数命名**(无值实参提取内联在既有 `it` 内) |
| 日志消息文本 | 82–96 共 15 条 | 见「logger.json error 82–96 最终文本」 |
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/09-minimum-browser-runnable/09-CONTEXT.md
@.planning/phases/09-minimum-browser-runnable/09-56-PLAN.md
@.planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md
@AGENTS.md
@dev.md
@packages/render-anim/src/parse.ts
@packages/render-anim/src/__test__/parse.test.ts
@packages/common/src/logger.json
@packages/common/src/logger.ts
@packages/render-anim/src/types.ts
@packages/render-anim/src/index.ts
@packages/render-anim/package.json
@.prettierrc
@eslint.config.js
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 预执行汇报关卡 —— 汇报 82–96 表、调用点参数、明确不改项与影响范围,等待恰好「可以执行」</name>
<dependencies>无(本任务就是批准关卡,只依赖用户针对本计划的「可以执行」回复)</dependencies>
<precondition>`packages/render-anim/src/parse.ts` 仍是 09-56 的过参数化实现(39 处 `logger.error`、86 号 10 参数、85 号 6 参数、`'-'` 占位、`String(...)` 与 `error.message`);`packages/common/src/logger.json` error 段为 `1..81` + `82..91` + `2001..2008`,`92..95` 不存在;`parse.test.ts` 有 70 个 `it`;工具链存在。</precondition>
<files>无(本任务只读,不写任何文件;汇报后停下等待「可以执行」)</files>
<read_first>
- `.planning/phases/09-minimum-browser-runnable/09-CONTEXT.md`(D-01 增量派发、D-03 汇报关卡、D-04 命名批准、D-06 范围界定)
- `AGENTS.md`(执行前须获批、既有注释不得擅自修改、最小修改也走 GSD、GSD 流程豁免范围)
- `dev.md`(第 74-86 行注释规范、第 116 行 CRLF、第 121 行不建议 try-catch、「不建议」视为「不得」)
- `packages/render-anim/src/parse.ts`(839 行现状:39 处 `logger.error`、82–91 过参数化)
- `packages/common/src/logger.json`(error 82–91 现状与 warn 既有风格)
- `packages/render-anim/src/__test__/parse.test.ts`(70 个用例、`ERROR_PARAM_COUNTS`、静态闸门)
- 本计划「logger.json error 82–96 最终文本」「logger 调用点参数规范」「`parse.ts` 行为不变量」「`parse.test.ts` 改写规格」「风格核对」
</read_first>
<what-built>
一份待批准的去参数化计划(`09-57-PLAN.md`):把 `parse.ts` 的解析器诊断收敛为「错误原因 + 对应索引」,error 段重写为 82–96 的 15 条具体消息,同步 `parse.test.ts` 的期望码 / arity / 静态闸门。只改 3 个源码 / 测试 / 配置路径 + 本 SUMMARY,0 提交。
</what-built>
<action>
**停下并向用户汇报,等待其恰好回复「可以执行」后才继续;本任务不写任何文件、不建目录、不派发执行子代理。**
① **要做什么 / 为什么(D-01 / D-06):** 09-56 的 logger 调用点过度参数化。用户规则是:解析器诊断只需**错误原因 + 对应索引**;actual/expected、尺寸、x/y/w/h、图像宽高、JSON 大小、异常 `message` 等具体值无排查价值且不应传入。本计划把调用点收敛到至多 3 个参数,并把 error 段重写为 82–96 的具体消息。
② **logger 82–96 表(逐字确认,取自「logger.json error 82–96 最终文本」):**
- 82 头非法(`buffer-too-short` / `length-mismatch`,1 参)
- 83 签名非法(0 参)
- 84 版本不支持(0 参)
- 85 sprite 表非法(`invalid-count` / `table-overflow`,1 参)
- 86 sprite 非法(索引,1 参)
- 87 位图列表非法(`not-array` / `count-mismatch`,1 参)
- 88 位图项非法(索引 + `not-object` / `invalid-x` / `invalid-y` / `invalid-width` / `invalid-height`,2 参)
- 89 位图越界(索引,1 参)
- 90 帧列表非法(0 参)
- 91 帧项非法(帧索引 + `not-object` / `objects-not-array` / `sound-not-array`,2 参)
- 92 对象非法(帧索引 + 对象索引 + 原因,3 参)
- 93 标量字段非法(`invalid-ratio` / `invalid-blend`,1 参)
- 94 音效非法(帧索引 + 音效索引 + 原因,3 参)
- 95 元数据非法(`invalid-json` / `not-object`,1 参)
- 96 图像失败(`decode-failed` / `texture-failed`,1 参)
逐字文本见计划表;15 条两两不同,无 `Cannot parse animation: $1.` 泛化消息。
③ **调用点参数规范(逐条确认):** 82/85/87/93/95/96 → `logger.error(code, reason)`;83/84/90 → `logger.error(code)`;86/89 → `logger.error(code, index.toString())`;88/91 → `logger.error(code, index.toString(), reason)`;92/94 → `logger.error(code, frame.toString(), subIndex.toString(), reason)`。**92/94 固定帧索引在前、对象/音效索引在后、reason 最后(消息用 `$1` 表示帧、`$2` 表示对象/音效、`$3` 表示原因)**;其余索引按对应消息 `$n` 的顺序传入;reason 小写连字符;**无 `'-'` 占位、无 `String(value)`、无 `.message`、无尺寸 / 坐标 / 图像维度值**。具体实参见「logger 调用点参数规范」表。
④ **`parse.ts` 行为不变(逐条确认):** 不改校验逻辑、提前返回、`validateMeta` 嵌套、可选字段 `!== undefined`、`isRecord` 的 `value !== null`、`parseRenderAnimation` 签名、3 处窄 `try/catch`、无 `throw` / `finally`、`new Blob` 在 `try` 外、位图越界先 close、纹理失败先 close。两个 catch 改为无绑定 `catch {`,删除 `reason` 变量。`validateBitmapBounds` 仍读图像宽高做越界判断,只是不写日志。
⑤ **保留 09-56 成果:** jsDoc / 行内注释 / 3 组 `#region` / 类级 jsDoc / 单画布改动一律不动;**不修改 `animater.ts` / `types.ts` / `index.ts` / `package.json`**。
⑥ **测试更新预期:** `parse.test.ts` 期望码改为 82–96(header 82/83/84;sprite 85/86;bitmap 87/88/89;frame 90/91;对象 92;ratio/blend 93;音效 94;metadata 95;decode/texture 96),同步每个 `it` 前注释;越界用例改断言 code 89 + 索引并保留 `image.close`;`ERROR_PARAM_COUNTS` 改为 82:1,83:0,84:0,85:1,86:1,87:1,88:2,89:1,90:0,91:2,92:3,93:1,94:3,95:1,96:1;`expectFailure` 断言 `calls[0].length === count + 1`;静态闸门把两处 `catch(error)` 改为 `catch{`、把 90 号守卫改为 95 号、92–96 均为合法码(不得断言 92–95 缺失)、新增「无值实参」断言;新增 92 / 94 参数顺序断言(至少一个 92 与一个 94 用例断言 `calls[0][1]` 帧索引、`calls[0][2]` 对象/音效索引、`calls[0][3]` reason,仅强化既有用例,不新增 `it`);**保留 70 个用例**。
⑦ **风格一致:** 新消息沿用既有风格(具体上下文 + reason / 索引,无具体值),参照 warn 44、error 63、warn 179;不允许 `Cannot parse animation: $1.`。
⑧ **门禁形态:** `parse.test.ts` 70 passed;prettier `--check`(3 个改动文件);eslint(2 个源码 / 测试);CRLF / BOM / tab;过滤 `packages[\\/]render-anim` 的 `vue-tsc --noEmit --incremental false`(**必须使用 `--incremental false`;若被拒绝则直接失败,不回退;收尾清理并校验无 `*.tsbuildinfo`**);静态门禁(82–96 全在、参数 ≤3 且只含索引 / 允许的原因、无值与 `'-'`、logger 表逐字比对计划、`1..81` / `2001..2008` / warn 不变、行为不变量、`image.close()` 在 `logger.error(89, ...)` 之前且宽高先读、纹理失败先 close(compact `image.close();logger.error(96,'texture-failed');`)、92/94 帧索引在前(compact `logger.error(92,frameIndex.toString(),objectIndex.toString(),` / `logger.error(94,frameIndex.toString(),i.toString(),`))。**不做浏览器 E2E。**
⑨ **影响范围:** 只写 `packages/render-anim/src/parse.ts`、`packages/render-anim/src/__test__/parse.test.ts`、`packages/common/src/logger.json` 与 `09-57-SUMMARY.md`;`animater.ts` / `types.ts` / `index.ts` / `package.json` 只验证不改;不执行 git 写命令,**0 次提交**。
⑩ **等待批准:** 请确认以上内容后,回复恰好四个字「可以执行」。任何修改意见(尤其 82–96 消息文本、调用点顺序、无值规则)请直接说明;未收到「可以执行」之前不开始 Task 1–6 的任何一步。
</action>
<verify>用户针对本计划恰好回复「可以执行」后才进入 Task 1–6;在此之前不执行任何任务,也不派发执行子代理。</verify>
<fails_when>在用户回复「可以执行」之前执行了 Task 1–6 的任何一步、写入了任何文件,或派发了执行子代理;或汇报遗漏了 ①–⑩ 中任一项(82–96 表、调用约定、明确不改项、测试更新、门禁、范围、0 提交)。</fails_when>
<how-to-verify>
逐条核对 ①–⑩ 是否与你的意图一致,重点是:② 的 82–96 十五条消息;③ 的调用顺序与「无值」规则;④ 的行为不变量与无绑定 catch;⑤ 的 09-56 注释保留与不修改 animater;⑥ 的 82–96 期望码、arity 映射、70 用例;⑧ 的门禁形态;⑨ 的 4 个写入路径与 0 提交。
</how-to-verify>
<resume-signal>请在确认本计划(尤其是 ② 的 82–96 消息文本、③ 的调用顺序与无值规则、④ 的行为不变量、⑤ 的不修改项)后,回复恰好四个字「可以执行」。任何修改意见请直接说明。</resume-signal>
<done>已完整汇报 ①–⑩(82–96 表、调用点参数、行为不变量、保留 09-56 成果、测试更新与 70 用例、门禁形态、影响范围与 0 提交),并收到用户针对本计划的「可以执行」回复。</done>
<acceptance_criteria>
- 已向用户逐条汇报 ①–⑩,包含完整 82–96 错误码表(不是只说「合并错误码」)与调用点参数规范。
- 已明确说明只传原因 + 索引,不传任何具体值,且每个调用至多 3 个参数。
- 已明确说明 `parse.ts` 行为不变(含无绑定 catch、位图越界先 close、纹理失败先 close)。
- 已明确说明保留 09-56 jsDoc / 注释 / region / 类级 jsDoc / 单画布成果,且不修改 animater / types / index / package.json。
- 已明确说明 `parse.test.ts` 的 82–96 期望码、`ERROR_PARAM_COUNTS`、arity 断言、静态闸门更新与 70 用例保留。
- 已明确说明 92 / 94 的参数顺序(帧索引在前、对象/音效索引在后、reason 最后)由静态 compact 断言与测试 `calls[0][1]` / `calls[0][2]` / `calls[0][3]` 断言机器校验。
- 已明确说明「纹理失败先 close」由 compact `image.close();logger.error(96,'texture-failed');` 静态断言机器校验(独立于越界 `image.close();logger.error(89,` gate),不仅是散文描述。
- 已明确说明影响范围(4 个写入路径)与 0 提交。
- 用户针对本计划明确回复「可以执行」后才进入 Task 1–6;在此之前未执行任何任务、未派发执行子代理。
</acceptance_criteria>
</task>
<task type="auto">
<name>Task 1: 读取当前 09-56 实现与既有 logger 风格,采集状态 / 哈希 / logger 快照基线(只读,临时文件仅写 TEMP)</name>
<dependencies>Task 0(汇报关卡已通过,批准效力覆盖本流程 Task 1–6)</dependencies>
<files>无(本任务只读仓库文件;只在 `process.env.TEMP` 目录写基线临时文件,不写仓库内任何文件)</files>
<read_first>
- `packages/render-anim/src/parse.ts`(839 行现状:39 处 `logger.error`、82–91 过参数化、两处 `catch (error)` + `reason`)
- `packages/common/src/logger.json`(error 82–91 现状、`1..81`、`2001..2008`、warn 含 213 / 1001)
- `packages/common/src/logger.ts`(`error(code: number, ...params: string[])` 与 `parseInfo` 的 `$n` 替换)
- `packages/render-anim/src/__test__/parse.test.ts`(70 个用例、`ERROR_PARAM_COUNTS`、静态闸门当前文本)
- `packages/render-anim/src/animater.ts` / `types.ts` / `index.ts` / `package.json`(只验证基线)
- 本计划「logger.json error 82–96 最终文本」「logger 调用点参数规范」「`parse.ts` 行为不变量」「`parse.test.ts` 改写规格」
- `dev.md`(CRLF、4 空格、注释规范)
</read_first>
<action>
本任务不写仓库内文件,只读取并记录。
1. 记录 `logger.error` 签名 `(code: number, ...params: string[])`;确认 `parseInfo` 连续读取数字直到非数字,`$n` 可正确替换。
2. 记录 `parse.ts` 现状:39 处 `logger.error` 的码与实参形态;确认 82–91 均有调用点,86 为 10 参数、85 为 6 参数、87 为 4 参数、89 为 5 参数,且存在 `'-'`、`String(meta.*)`、`String(bitmap.*)`、`String(object.*)`、`String(item.*)`、`error.message`;两处 `catch (error)` + `reason`。把现状审计写入 `(process.env.TEMP||'.') + '/gsd-09-57-parse-audit.txt'`(UTF-8 无 BOM)。
3. 记录 `logger.json` 现状:error `1..81` + `82..91` + `2001..2008`;`92..95` 不存在;warn 含 `213`(并发未提交改动,必须逐字保留)与 `1001`。把原文复制为 `(process.env.TEMP||'.') + '/gsd-09-57-logger-baseline.json'`(仅复制,不解析重排)。
4. 记录 `parse.test.ts` 现状:70 个 `it`;`ERROR_PARAM_COUNTS` 当前值 82–91;`expectFailure` 断言;越界用例的 `[9]` / `[10]` 尺寸断言;静态闸门中两处 `catch(error)` 与 90 号守卫文本。
5. 采集 **范围基线**:把当前 `git status --porcelain -uall`(统一 LF)写入 `(process.env.TEMP||'.') + '/gsd-09-57-status.txt'`(UTF-8 无 BOM),回显绝对路径,并立即断言与当前输出一致。基线必须逐行精确包含:` M packages/common/src/logger.json`、`?? packages/render-anim/src/parse.ts`、`?? packages/render-anim/src/__test__/parse.test.ts`、`?? .planning/phases/09-minimum-browser-runnable/09-57-PLAN.md`(其余并发脏文件按当前树原样保留)。
6. 采集 **哈希基线**:对 9 个路径逐个 `git hash-object`,写入 `(process.env.TEMP||'.') + '/gsd-09-57-hashes.txt'`(UTF-8 无 BOM),格式「**仓库相对路径** + 空格 + 40 位哈希」,路径必须是完整仓库相对路径(不得只写文件名,否则 Task 6 的 `git hash-object` 会找不到文件):`packages/render-anim/src/parse.ts`、`packages/render-anim/src/__test__/parse.test.ts`、`packages/common/src/logger.json`、`packages/render-anim/src/animater.ts`、`packages/render-anim/src/__test__/animater.test.ts`、`packages/render-anim/src/types.ts`、`packages/render-anim/src/index.ts`、`packages/render-anim/package.json`、`.planning/phases/09-minimum-browser-runnable/09-57-PLAN.md`。**Task 6 比对时排除 `.planning/phases/09-minimum-browser-runnable/09-57-PLAN.md`**,只要求其余 8 条中恰好 3 个目标文件变化、5 个只读文件不变。
7. 断言现状(任一不符,停下上报,不得继续 Task 2):
- `parse.ts` 含 39 处 `logger.error`、含值形式 `String(...)`(非 `.toString()`)、含 `error.message`、含 `'-'`、含两处 `catch (error)`、恰 3 处 `try {`、含 `Promise<IAnimationParsedData | null>`。
- `parse.test.ts` 恰 70 个 `it`、含 `ERROR_PARAM_COUNTS`、含 `catch(error)` 的 compact 断言、含 `logger.error(90,'not-object',size.toString())` 的守卫断言。
- `logger.json` 的 `error['82']`..`error['91']` 存在、`error['92']`..`error['95']` 不存在、`warn['213']` 与 `warn['1001']` 为非空字符串、`error['81']` / `error['2001']` / `error['2008']` 存在。
- `animater.ts` / `types.ts` / `index.ts` / `package.json` 存在且未被本任务改动。
8. 记录工具链事实:`node --version`;四个工具入口存在;基线测试 `node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts` 为 70 passed。
</action>
<verify>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const p=(process.env.TEMP||'.')+'/gsd-09-57-status.txt';const rd=s=>s.replace(/\r\n/g,'\n').replace(/^\n+|\n+$/g,'');const base=rd(fs.readFileSync(p,'utf8'));const now=rd(execSync('git status --porcelain -uall',{encoding:'utf8'}));const need=[' M packages/common/src/logger.json','?? packages/render-anim/src/parse.ts','?? packages/render-anim/src/__test__/parse.test.ts','?? .planning/phases/09-minimum-browser-runnable/09-57-PLAN.md'];const miss=need.filter(l=>base.split('\n').indexOf(l)===-1);if(base!==now||miss.length){console.error('baseline drift or missing entries: '+miss.join(' | '));process.exit(1);}console.log('OK: status baseline matches current tree and contains required entries');"</automated>
<fails_when>基线文件与当前 `git status --porcelain -uall` 不一致,或缺少必需条目(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const s=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-57-hashes.txt','utf8').replace(/\r\n/g,'\n').trim().split('\n').filter(Boolean);const ok=s.length===9&&s.every(l=>{const a=l.split(' ');return a.length===2&&a[1].length===40&&!/[^0-9a-f]/.test(a[1]);});if(!ok){console.error(s.join('\n'));process.exit(1);}console.log('OK: 9 hash baselines');"</automated>
<fails_when>哈希基线不是 9 行,或任一行不是「无空格路径 + 40 位小写十六进制」(打印内容,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-57-logger-baseline.json','utf8'));const fail=[];for(const c of ['81','82','91','2001','2008'])if(j.error[c]===undefined)fail.push('error '+c+' missing');for(const c of ['92','93','94','95'])if(j.error[c]!==undefined)fail.push('error '+c+' already present');if(typeof j.warn['213']!=='string')fail.push('warn 213 missing');if(j.warn['1001']===undefined)fail.push('warn 1001 missing');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: logger snapshot is pre-change (82..91, no 92..95, warn 213/1001)');"</automated>
<fails_when>快照缺少 error 81 / 82 / 91 / 2001 / 2008,或已含 92–95,或缺 warn 213 / 1001(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const p=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const SQ=String.fromCharCode(39);const fail=[];const calls=(p.match(/logger\.error\(/g)||[]).length;if(calls!==39)fail.push('logger.error calls='+calls+', expected 39');for(let c=82;c<=91;c++){if(!new RegExp('logger\\.error\\(\\s*'+c+'\\b').test(p))fail.push('missing code '+c);}if(!/\bString\s*\(/.test(p))fail.push('String() value missing');if(p.indexOf('error.message')===-1)fail.push('error.message missing');if(p.indexOf(SQ+'-'+SQ)===-1)fail.push('dash placeholder missing');if((p.match(/catch \(error\)/g)||[]).length!==2)fail.push('catch(error) count mismatch');if((p.match(/try\s*\{/g)||[]).length!==3)fail.push('try count mismatch');if(p.indexOf('Promise<IAnimationParsedData | null>')===-1)fail.push('nullable signature missing');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: pre-change parse.ts matches the over-parameterized assumptions');"</automated>
<fails_when>`parse.ts` 不是 39 处 `logger.error` / 缺 82–91 / 缺值形式 `String(...)`(非 `.toString()`)/ `error.message` / `'-'` / 两处 `catch (error)` / 3 处 `try` / 可空签名之一(打印原因,退出码 1)——状态与计划不符须停下上报。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8');const fail=[];const its=(t.match(/^\s*it\s*\(/gm)||[]).length;if(its!==70)fail.push('it count='+its+', expected 70');if(t.indexOf('ERROR_PARAM_COUNTS')===-1)fail.push('ERROR_PARAM_COUNTS missing');if(t.indexOf('catch(error)')===-1)fail.push('catch(error) compact assertion missing');if(t.indexOf('logger.error(90')===-1)fail.push('90 guard assertion missing');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: parse.test.ts baseline matches');"</automated>
<fails_when>`parse.test.ts` 不是 70 个 `it`,或缺 `ERROR_PARAM_COUNTS` / `catch(error)` 断言 / 90 号守卫(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const need=['packages/render-anim/src/types.ts','packages/render-anim/src/index.ts','packages/render-anim/package.json','packages/render-anim/src/animater.ts','node_modules/vitest/vitest.mjs','node_modules/prettier/bin/prettier.cjs','node_modules/eslint/bin/eslint.js','node_modules/vue-tsc/bin/vue-tsc.js'];const miss=need.filter(f=>!fs.existsSync(f));if(miss.length){console.error('missing: '+miss.join(', '));process.exit(1);}console.log('OK: files and toolchain present');"</automated>
<fails_when>只读参考文件或工具链缺失(打印缺失列表,退出码 1)。</fails_when>
<automated>node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts</automated>
<fails_when>退出码非 0,或输出未报告 70 passed;browserslist 的 stderr 提示属正常,不作为失败依据。</fails_when>
</verify>
<acceptance_criteria>
- 已记录 `parse.ts` 的 39 处 `logger.error`、82–91 调用点、`String(...)` / `error.message` / `'-'` / 两处 `catch (error)` / 3 处 `try` / 可空签名。
- 已记录 `parse.test.ts` 的 70 个 `it`、`ERROR_PARAM_COUNTS`、`catch(error)` 断言、90 号守卫。
- `(process.env.TEMP||'.')/gsd-09-57-status.txt`(含必需条目)、`gsd-09-57-hashes.txt`(9 行)、`gsd-09-57-logger-baseline.json`、`gsd-09-57-parse-audit.txt` 均已生成并通过门禁。
- 已记录 `logger.error` 签名 / `parseInfo` 行为与既有 logger 风格(warn 44 / error 63 / warn 179)。
- 基线 vitest 为 70 passed;任一现状不符已停下上报,未继续 Task 2。
</acceptance_criteria>
<done>已记录 09-56 过参数化现状与既有 logger 风格;TEMP 下的状态基线、9 行哈希基线、logger 快照与 parse 审计均已生成并通过门禁;基线 vitest 70 passed;任一不符已停下上报。</done>
</task>
<task type="auto">
<name>Task 2: 重写 `logger.json` error 82–96(15 条具体消息,保留 1..81 / 2001..2008 / warn 含 213、1001)</name>
<dependencies>Task 1(logger 快照与哈希已就绪)</dependencies>
<files>packages/common/src/logger.json</files>
<read_first>
- 本计划「logger.json error 82–96 最终文本」「logger 调用点参数规范」「风格核对」(唯一内容依据)
- `packages/common/src/logger.json`(当前 error 82–91 与 warn 段)
- `packages/common/src/logger.ts`(`parseInfo` 的 `$n` 替换、未命中码转调 16)
- `dev.md`(CRLF、4 空格、JSON 不得引入注释)
</read_first>
<action>
本任务只改 `packages/common/src/logger.json`。
1. 把当前 error 段 82–91 的 10 条整体替换为 82–96 的 15 条,顺序 82→96,文本严格使用「logger.json error 82–96 最终文本」表,逐字一致(含 `reason: '$1'` 的引号、冒号、逗号、句号与空格)。缩进 8 个空格、行尾逗号与现有风格一致。
2. 92–95 作为合法码重新加入(92 对象 / 93 标量 / 94 音效 / 95 元数据),96 为图像失败;不得重复键、不得保留空行。
3. `$n` 与「logger 调用点参数规范」一致:82=1、83=0、84=0、85=1、86=1、87=1、88=2、89=1、90=0、91=2、92=3、93=1、94=3、95=1、96=1;消息中不得出现未使用的 `$n`,也不得出现超出实参数目的占位。
4. 不改动 error 段 `1..81`、`2001..2008`,不改动整个 `warn` 段(含 `213` 与 `1001`);不新增 `1000+` 码。
5. 不碰 `parse.ts` / `parse.test.ts` / SUMMARY / 其它包或配置。
</action>
<verify>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const fail=[];for(let c=82;c<=96;c++){if(typeof j.error[c]!=='string'||j.error[c].length<15)fail.push('missing or short error '+c);}if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: error 82..96 present');"</automated>
<fails_when>`logger.json` 不是合法 JSON,或 82–96 任一条缺失 / 过短(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const base=JSON.parse(fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-57-logger-baseline.json','utf8'));const fail=[];Object.keys(base.error).forEach(k=>{const n=+k;if(n>=82&&n<=91)return;if(j.error[k]!==base.error[k])fail.push('error '+k+' changed');});if(JSON.stringify(j.warn)!==JSON.stringify(base.warn))fail.push('warn section changed');Object.keys(j.error).forEach(k=>{const n=+k;if(base.error[k]===undefined&&(n<82||n>96))fail.push('unexpected new error code '+k);if(n>=1000&&base.error[k]===undefined)fail.push('added 1000+ code '+k);});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 1..81 / 2001..2008 / warn unchanged; only 82..96 in the merged range');"</automated>
<fails_when>既有 error 码被改动、`warn` 段(含 213 / 1001)任一字符变化、在 82–96 之外新增错误码,或新增 `1000+` 码(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const counts={82:1,83:0,84:0,85:1,86:1,87:1,88:2,89:1,90:0,91:2,92:3,93:1,94:3,95:1,96:1};const D=String.fromCharCode(36);const re=new RegExp('['+D+'][0-9]+','g');const fail=[];Object.keys(counts).forEach(k=>{const msg=j.error[k]||'';const used=new Set();(msg.match(re)||[]).forEach(m=>used.add(+m.slice(1)));const nums=[...used].sort((a,b)=>a-b);const max=nums.length?nums[nums.length-1]:0;if(nums.length!==counts[k]||max!==counts[k])fail.push('code '+k+' uses '+nums.length+' params (max '+max+'), expected '+counts[k]);});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: placeholder counts match the parser call sites');"</automated>
<fails_when>任一 82–96 消息的 `$n` 数量与规范不符,或占位跳号(打印实际与期望,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const BT=String.fromCharCode(96);const plan=fs.readFileSync('.planning/phases/09-minimum-browser-runnable/09-57-PLAN.md','utf8').replace(/\r\n/g,'\n');const log=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const digits=s=>s.length>0&&s.split('').every(ch=>ch>='0'&&ch<='9');const rows=plan.split('\n').map(l=>l.trim()).filter(l=>l.indexOf('|')===0).map(l=>l.split('|').map(s=>s.trim()));const expected={};rows.forEach(all=>{const c=all.filter((s,i)=>i>0&&i<all.length-1);if(c.length!==3||!digits(c[0]))return;const n=+c[0];if(n<82||n>96)return;const cell=c[1];if(cell.length>2&&cell.slice(0,1)===BT&&cell.slice(-1)===BT)expected[n]=cell.slice(1,-1);});const fail=[];for(let n=82;n<=96;n++){if(!expected[n])fail.push('plan table row missing for '+n);else if(log.error[n]!==expected[n])fail.push('message mismatch for '+n+' (json='+JSON.stringify(log.error[n])+' plan='+JSON.stringify(expected[n])+')');}const msgs=Object.keys(expected).map(k=>expected[k]);if(new Set(msgs).size!==msgs.length)fail.push('duplicate messages between 82..96');if(msgs.some(m=>m===('Cannot parse animation: '+String.fromCharCode(36)+'1.')))fail.push('generic placeholder-only message present');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 82..96 messages match the plan table verbatim, distinct, non-generic');"</automated>
<fails_when>82–96 任一消息与计划表不是逐字一致、15 条消息出现重复,或存在 `Cannot parse animation: $1.` 泛化消息(打印差异,退出码 1)——只比对占位数量不够,必须比对整段文本。</fails_when>
<automated>node node_modules/prettier/bin/prettier.cjs --check packages/common/src/logger.json</automated>
<fails_when>prettier 报告该文件待格式化,或退出码非 0。</fails_when>
<automated>node -e "const fs=require('fs');const b=fs.readFileSync('packages/common/src/logger.json');const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;const ok=lf===crlf&&tabs===0&&!bom;console.log((ok?'OK':'FAIL')+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);process.exit(ok?0:1);"</automated>
<fails_when>出现非 CRLF 换行、制表符或 BOM(打印 `FAIL`,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- `logger.json` 的 error 段 82–96 恰有 15 条消息,文本与「logger.json error 82–96 最终文本」表**逐字一致**。
- 15 条消息两两不同,且不存在 `Cannot parse animation: $1.` 泛化消息。
- `$n` 数量为 1/0/0/1/1/1/2/1/0/2/3/1/3/1/1,与「logger 调用点参数规范」一致。
- `1..81`、`2001..2008` 与整个 `warn` 段(含 `213`、`1001`)与 Task 1 快照深比较逐字不变;未新增 `1000+` 码。
- prettier 与 CRLF / BOM / tab 门禁通过。
</acceptance_criteria>
<done>`logger.json` 的 error 已重写为 82–96 的 15 条具体消息(占位符数量 1/0/0/1/1/1/2/1/0/2/3/1/3/1/1,两两不同、无泛化消息),既有码段与 warn 段(含 213 / 1001)逐字未变;prettier 与 CRLF / BOM 门禁通过。</done>
</task>
<task type="auto">
<name>Task 3: 重写 `parse.ts` 的 logger 调用点为「原因 + 索引」,行为不变(不跑 vitest,测试在 Task 4 同步)</name>
<dependencies>Task 2(`logger.json` 的 82–96 已定稿)</dependencies>
<files>packages/render-anim/src/parse.ts</files>
<read_first>
- 本计划「logger 调用点参数规范」「`parse.ts` 行为不变量」「logger.json error 82–96 最终文本」(唯一内容依据)
- `packages/render-anim/src/parse.ts`(Task 1 记录的 39 处调用点与行为不变量)
- `packages/common/src/logger.json`(Task 2 的 82–96 文本,确认实参与占位一致)
- `dev.md`(CRLF、4 空格、注释规范)
</read_first>
<action>
本任务只改 `parse.ts`,只改 `logger.error` 调用表达式(以及删除两个 `reason` 变量与 `catch (error)` 的绑定),不改任何其它逻辑。
1. 按「logger 调用点参数规范」逐处替换:
- `readHeader`:头过短 → `logger.error(82, 'buffer-too-short')`;签名 → `logger.error(83)`;版本 → `logger.error(84)`;长度不符(含 `imageDataSize < 4` / `metaDataSize < 1` 的三合一条件)→ `logger.error(82, 'length-mismatch')`。
- `parseRenderAnimation`:sprite 数 < 1 → `logger.error(85, 'invalid-count')`;尺寸表越界 → `logger.error(85, 'table-overflow')`。
- `readSpriteDimensions`:单个 sprite 宽或高 < 1 → `logger.error(86, i.toString())`(不再传 count / width / height)。
- `validateMeta`:`!isRecord` 纵深防御 → `logger.error(95, 'not-object')`;ratio → `logger.error(93, 'invalid-ratio')`;blend → `logger.error(93, 'invalid-blend')`;位图列表非数组 → `logger.error(87, 'not-array')`;数量不符 → `logger.error(87, 'count-mismatch')`;位图项非对象 → `logger.error(88, i.toString(), 'not-object')`;x/y/width/height → `logger.error(88, i.toString(), 'invalid-x' / 'invalid-y' / 'invalid-width' / 'invalid-height')`;frame 非数组 → `logger.error(90)`;帧项非对象 → `logger.error(91, frameIndex.toString(), 'not-object')`;objects 非数组 → `logger.error(91, frameIndex.toString(), 'objects-not-array')`;对象项非元组 → `logger.error(92, frameIndex.toString(), objectIndex.toString(), 'not-tuple')`;字段数 → `'invalid-field-count'`;对象索引 → `'invalid-index'`;对象字段 → `'invalid-x' / 'invalid-y' / 'invalid-scale' / 'invalid-opacity' / 'invalid-mirror' / 'invalid-rotate'`;sound 非数组 → `logger.error(91, frameIndex.toString(), 'sound-not-array')`;音效项非对象 → `logger.error(94, frameIndex.toString(), i.toString(), 'not-object')`;音效 name / volume / pitch → `'invalid-name' / 'invalid-volume' / 'invalid-pitch'`。
- `validateBitmapBounds`:越界 → 先 `image.close()` 再 `logger.error(89, i.toString())`(顺序不可颠倒);仍保留 `imageWidth` / `imageHeight` 的读取与越界判断,只是不写日志。
- `readRawMeta`:JSON 解析失败 → `logger.error(95, 'invalid-json')`;非对象 → `logger.error(95, 'not-object')`。
- `parseRenderAnimation` 解码失败 → `catch { logger.error(96, 'decode-failed'); return null; }`;纹理失败 → `catch { image.close(); logger.error(96, 'texture-failed'); return null; }`;删除两个 `reason` 局部变量。
2. 索引必须是 `.toString()` 形式;原因必须是小写连字符标签;任何调用不得超过 code + 3 个参数;不得出现 `'-'`、值形式 `String(value)`(注意:索引的 `.toString()` 是允许且必需的,不算 `String(`)、`.message` 或任何具体值。
3. 保持行为不变量(见「`parse.ts` 行为不变量」):不改校验条件、循环、嵌套、提前返回、可选字段判断、`isRecord`、签名、`try` 数量、`new Blob` 位置、close 顺序;不新增 `throw` / `finally`。**参数顺序固定:92 必须 `frameIndex.toString(), objectIndex.toString(), reason`;94 必须 `frameIndex.toString(), i.toString(), reason`(帧索引在前、对象/音效索引在后、reason 最后);纹理失败必须 `image.close(); logger.error(96, 'texture-failed')` 顺序(先关闭再记日志)。**
4. 保持 09-56 的 jsDoc / 行内注释 / 3 组 `#region` / 类级 jsDoc / 单画布实现逐字不动;不新增 / 重命名任何命名。
5. 不碰 `parse.test.ts`(Task 4 处理)、`animater.ts`、`logger.json`、其它文件。
</action>
<verify>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const fail=[];for(let c=82;c<=96;c++){if(!new RegExp('logger\\.error\\(\\s*'+c+'\\b').test(t))fail.push('missing code '+c);}if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 82..96 all referenced');"</automated>
<fails_when>82–96 中任一码没有调用点(打印列表,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const src=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const SQ=String.fromCharCode(39);const key='logger.error(';const calls=[];let idx=0;while(true){const p=src.indexOf(key,idx);if(p<0)break;let i=p+key.length,depth=1,args='',quote=false;while(i<src.length&&depth>0){const c=src[i];if(quote){if(c==='\\'){args+=c+src[i+1];i+=2;continue;}if(c===SQ)quote=false;args+=c;i++;continue;}if(c===SQ){quote=true;args+=c;i++;continue;}if(c==='('){depth++;args+=c;i++;continue;}if(c===')'){depth--;if(depth===0){i++;break;}args+=c;i++;continue;}args+=c;i++;}calls.push(args);idx=i;}const allowed=new Set(['buffer-too-short','length-mismatch','invalid-count','table-overflow','not-array','count-mismatch','not-object','invalid-x','invalid-y','invalid-width','invalid-height','objects-not-array','sound-not-array','not-tuple','invalid-field-count','invalid-index','invalid-scale','invalid-opacity','invalid-mirror','invalid-rotate','invalid-ratio','invalid-blend','invalid-name','invalid-volume','invalid-pitch','invalid-json','decode-failed','texture-failed']);const fail=[];calls.forEach((a,n)=>{const parts=[];let depth=0,q=false,buf='';for(let i=0;i<a.length;i++){const c=a[i];if(q){if(c==='\\'){buf+=c+(a[i+1]||'');i++;continue;}if(c===SQ)q=false;buf+=c;continue;}if(c===SQ){q=true;buf+=c;continue;}if(c==='(')depth++;if(c===')')depth--;if(c===','&&depth===0){parts.push(buf.trim());buf='';continue;}buf+=c;}if(buf.trim())parts.push(buf.trim());const code=parts[0];if(!/^(8[2-9]|9[0-6])$/.test(code))fail.push('call '+n+' unknown code '+code);if(parts.length<1||parts.length>4)fail.push('call '+n+' arity '+(parts.length-1)+' params (>3)');for(const raw of parts.slice(1)){const p=raw.trim();if(new RegExp('^[A-Za-z_][A-Za-z0-9_]*\\.toString\\(\\)$').test(p))continue;if(new RegExp('^'+SQ+'[a-z][a-z-]*'+SQ+'$').test(p)){if(!allowed.has(p.slice(1,-1)))fail.push('call '+n+' unknown reason '+p);continue;}fail.push('call '+n+' invalid param '+p);}});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: '+calls.length+' logger calls: <=3 params, index .toString() or allowed kebab reason only, no values');"</automated>
<fails_when>任一 `logger.error` 调用超过 3 个参数、参数不是「索引 `.toString()`」或「允许的原因标签」、出现 `'-'` / `String(...)` / `.message` / 任何具体值,或 code 不在 82–96(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const SQ=String.fromCharCode(39);const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const fail=[];if(/\bString\s*\(/.test(t))fail.push('String() value present');if(t.indexOf('.message')!==-1)fail.push('.message present');if(t.indexOf(SQ+'-'+SQ)!==-1)fail.push('dash placeholder present');if(/actual|expected/i.test(t))fail.push('actual/expected present');if((t.match(/catch \(error\)/g)||[]).length!==0)fail.push('catch(error) binding remains');if(t.indexOf('catch {')===-1)fail.push('unbound catch missing');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: no String()/message/dash/actual/expected; unbound catch used');"</automated>
<fails_when>`parse.ts` 仍含值形式 `String(value)`(`.toString()` 不算)/ `.message` / `'-'` / actual / expected / `catch (error)`,或缺少无绑定 `catch {`(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const fail=[];const reg=(t.match(/#region/g)||[]).length;const end=(t.match(/#endregion/g)||[]).length;if(reg!==3||end!==3)fail.push('regions='+reg+' endregions='+end+', expected 3/3');if((t.match(/try\s*\{/g)||[]).length!==3)fail.push('try count changed');if(/\bthrow\b/.test(t))fail.push('throw present');if(/\bfinally\b/.test(t))fail.push('finally present');if(t.indexOf('Promise<IAnimationParsedData | null>')===-1)fail.push('signature changed');for(const need of ['object[5] !== undefined','object[6] !== undefined','item.volume !== undefined','item.pitch !== undefined','value !== null']){if(t.indexOf(need)===-1)fail.push('invariant missing: '+need);}for(const need of ['new Blob','if (!isRecord(meta))','return meta;','image.close()']){if(t.indexOf(need)===-1)fail.push('missing '+need);}if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 3 regions, 3 try, no throw/finally, signature and invariants intact');"</automated>
<fails_when>region 不是 3/3、`try` 数量或签名变化、出现 `throw` / `finally`、可选字段 / `isRecord` 不变量被改、或缺 `new Blob` / `isRecord` / `return meta` / `image.close`(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const compact=t.replace(/\s+/g,'');const fail=[];if(compact.indexOf('try{meta=JSON.parse(text);}catch{')===-1)fail.push('JSON.parse catch changed');if(compact.indexOf('try{image=awaitcreateImageBitmap(webpBlob);}catch{')===-1)fail.push('decode catch changed');if(compact.indexOf('try{texture=newTexture(image);}catch{')===-1)fail.push('texture catch changed');if(compact.indexOf('if(!isRecord(meta)){logger.error(95,'+String.fromCharCode(39)+'not-object'+String.fromCharCode(39)+');returnnull;}returnmeta;')===-1)fail.push('95 guard compact text missing');if(compact.indexOf('constwebpBlob=newBlob([webpBytes],{type:'+String.fromCharCode(39)+'image/webp'+String.fromCharCode(39)+'});')===-1)fail.push('Blob outside try changed');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: catch blocks unbound, 95 guard exact, Blob outside try');"</automated>
<fails_when>两处 `catch` 不是无绑定、95 号守卫 compact 文本不精确,或 `new Blob` 位置变化(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const c=t.replace(/\s+/g,'');const fail=[];const close=c.indexOf('image.close();logger.error(89,');if(close===-1)fail.push('image.close() before logger.error(89, ...) missing');const w=c.indexOf('image.width'),h=c.indexOf('image.height');if(w===-1||h===-1||w>close||h>close)fail.push('image dimensions not read before close for bounds check');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: image.close() precedes logger.error(89, ...); dimensions read before close');"</automated>
<fails_when>`validateBitmapBounds` 中 `image.close()` 不在 `logger.error(89, ...)` 之前(compact `image.close();logger.error(89,` 缺失),或 `image.width` / `image.height` 未在 close 前读取用于越界判定(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const c=t.replace(/\s+/g,'');const needle='image.close();logger.error(96,'+String.fromCharCode(39)+'texture-failed'+String.fromCharCode(39)+');';if(c.indexOf(needle)===-1){console.error('texture close-before-log missing (expected compact: '+needle+')');process.exit(1);}console.log('OK: texture path closes image before logging 96 texture-failed');"</automated>
<fails_when>纹理失败路径缺少 compact `image.close();logger.error(96,'texture-failed');`(close 必须在记日志之前;此断言独立于越界 `image.close();logger.error(89,` gate)(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const c=t.replace(/\s+/g,'');const fail=[];if(c.indexOf('logger.error(92,frameIndex.toString(),objectIndex.toString(),')===-1)fail.push('92 arg order (frame,objectIndex,reason) missing');if(c.indexOf('logger.error(94,frameIndex.toString(),i.toString(),')===-1)fail.push('94 arg order (frame,sound index i,reason) missing');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 92/94 pass frame index first, object/sound index second, reason third');"</automated>
<fails_when>92 未按 `logger.error(92,frameIndex.toString(),objectIndex.toString(),` 顺序(帧索引在前、对象索引在后、reason 最后),或 94 未按 `logger.error(94,frameIndex.toString(),i.toString(),` 顺序(帧索引在前、音效索引在后、reason 最后)(打印原因,退出码 1)。</fails_when>
<automated>node node_modules/prettier/bin/prettier.cjs --check packages/render-anim/src/parse.ts</automated>
<fails_when>prettier 报告该文件待格式化,或退出码非 0。</fails_when>
<automated>node node_modules/eslint/bin/eslint.js packages/render-anim/src/parse.ts</automated>
<fails_when>eslint 打印任一 error / warning,或退出码非 0。</fails_when>
<automated>node -e "const fs=require('fs');const b=fs.readFileSync('packages/render-anim/src/parse.ts');const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;const ok=lf===crlf&&tabs===0&&!bom;console.log((ok?'OK':'FAIL')+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);process.exit(ok?0:1);"</automated>
<fails_when>出现非 CRLF 换行、制表符或 BOM(打印 `FAIL`,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- 82–96 全部出现在 `logger.error` 调用点,每个调用至多 3 个参数,实参要么是索引 `.toString()`、要么是允许的小写连字符原因标签。
- 不存在 `'-'`、值形式 `String(value)`(`.toString()` 是要求的索引形式,不在此列)、`.message`、actual / expected 或任何具体值;两个 catch 改为无绑定 `catch {`,`reason` 变量已删除。
- 行为不变量全部保持:3 组 region、3 处 `try`、无 `throw` / `finally`、可空签名、可选字段 `!== undefined`、`isRecord` 的 `value !== null`、`new Blob` 在 `try` 外、位图越界先 close、纹理失败先 close。
- 95 号守卫 compact 文本精确、`new Blob` 位置未变。
- 纹理失败路径 compact `image.close();logger.error(96,'texture-failed');` 精确出现(独立于越界 `image.close();logger.error(89,` gate)。
- 92 按 `frameIndex.toString(), objectIndex.toString(), reason`、94 按 `frameIndex.toString(), i.toString(), reason` 顺序(帧索引在前、对象/音效索引在后、reason 最后)的 compact 断言通过。
- prettier / eslint / CRLF / BOM 通过。
- 本任务未运行 vitest(`parse.test.ts` 尚未同步,属预期)。
</acceptance_criteria>
<done>`parse.ts` 的 39 处 `logger.error` 已收敛为 82–96 的「原因 + 索引」(至多 3 参数、无值、无 `'-'`、无值形式 `String(value)`/`.message`),两个 catch 改为无绑定并删除 `reason`;行为不变量与 09-56 注释成果全部保持;纹理失败先 close(compact `image.close();logger.error(96,'texture-failed');`)与 92/94 帧索引在前的 compact 断言均通过;prettier / eslint / CRLF / BOM 通过;未跑 vitest。</done>
</task>
<task type="auto">
<name>Task 4: 同步 `parse.test.ts` 的 82–96 期望码 / arity / 注释 / 静态闸门,保留 70 用例</name>
<dependencies>Task 3(`parse.ts` 已改为 82–96)</dependencies>
<files>packages/render-anim/src/__test__/parse.test.ts</files>
<read_first>
- 本计划「`parse.test.ts` 改写规格」「logger 调用点参数规范」「logger.json error 82–96 最终文本」(唯一内容依据)
- `packages/render-anim/src/__test__/parse.test.ts`(Task 1 记录的 70 用例、`ERROR_PARAM_COUNTS`、静态闸门)
- `packages/render-anim/src/parse.ts`(Task 3 产物,确认调用点 / compact 文本)
- `dev.md`(测试文件每个 `it` 前一行注释、CRLF、4 空格)
</read_first>
<action>
本任务只改 `parse.test.ts`。
1. **期望码:** 按「`parse.test.ts` 改写规格」第 1 条逐用例改为 82–96;同步每个 `it` 前的一行中文注释(旧码 → 新码)。
2. **`ERROR_PARAM_COUNTS`:** 改为 `{ 82:1, 83:0, 84:0, 85:1, 86:1, 87:1, 88:2, 89:1, 90:0, 91:2, 92:3, 93:1, 94:3, 95:1, 96:1 }`;`expectFailure` 保留首参码断言并断言 `loggerMock.error.mock.calls[0].length === ERROR_PARAM_COUNTS[code] + 1`。
3. **越界用例:** 改为 `expectFailure(..., 89)`;**删除旧的 `expect(loggerMock.error.mock.calls[0][1]).toBe('out-of-bounds')` 整行,替换为 `expect(loggerMock.error.mock.calls[0][1]).toBe('0')`**(新 89 号只传索引 0,没有 `'out-of-bounds'` 原因),保留 `bitmap.close` 被调用;删除旧的 `[9]` / `[10]` 尺寸断言。旧 `'out-of-bounds'` 断言与新 `'0'` 断言不得同时存在。
4. **非对象元数据 / 解码 / 纹理:** 5 条非对象元数据断言 `calls[0][1] === 'not-object'`(95 号);解码 / 纹理改为 `96` 并断言 `'decode-failed'` / `'texture-failed'`,纹理用例保留 `bitmap.close`。
**92 / 94 参数顺序断言(强化既有用例,不新增 `it`):** 至少一个 92 用例断言 `calls[0][1]` 为帧索引、`calls[0][2]` 为对象索引、`calls[0][3]` 为 reason;至少一个 94 用例断言 `calls[0][1]` 为帧索引、`calls[0][2]` 为音效索引、`calls[0][3]` 为 reason。帧索引在前、对象/音效索引在后、reason 最后,与 `logger.error(92, frameIndex.toString(), objectIndex.toString(), ...)` / `logger.error(94, frameIndex.toString(), i.toString(), ...)` 一致;只强化既有 92 / 94 用例,保持 70 个 `it`。
5. **静态闸门(在既有 `it('keeps the parser free of throw statements')` 内扩展,严禁新增 `it`):**
- 保留「无 `throw` / 无 `@throws` / 恰 3 处 `try {` / 无 `finally`」。
- compact 断言把两处 `catch(error)` 改为 `catch{`;把旧 90 号守卫断言替换为 `if(!isRecord(meta)){logger.error(95,'not-object');returnnull;}returnmeta;`。
- 继续断言 `validateMeta` / `validateBitmapBounds` 体内无 `forEach`。
- 新增「无值实参」断言:**在既有静态闸门 `it` 内联**用平衡括号提取 `parse.ts` 每个 `logger.error(...)` 的实参(不得新增任何具名辅助函数,如 `extractLoggerCalls`;既有 `extractFunctionBody` 保持不动),断言每段实参要么匹配索引正则 `/^[A-Za-z_][A-Za-z0-9_]*\.toString\(\)$/`、要么是 `'kebab-case'` 原因标签且属于允许集合;据此排除 `'-'`、值形式 `String(value)`、`.message` 与任何具体值。允许集合必须与 Task 3 / Task 5 的平衡括号门禁同源,逐字包含 `buffer-too-short`、`length-mismatch`、`invalid-count`、`table-overflow`、`not-array`、`count-mismatch`、`not-object`、`invalid-x`、`invalid-y`、`invalid-width`、`invalid-height`、`objects-not-array`、`sound-not-array`、`not-tuple`、`invalid-field-count`、`invalid-index`、`invalid-scale`、`invalid-opacity`、`invalid-mirror`、`invalid-rotate`、`invalid-ratio`、`invalid-blend`、`invalid-name`、`invalid-volume`、`invalid-pitch`、`invalid-json`、`decode-failed`、`texture-failed`。
- 新增顺序断言:`validateBitmapBounds` 中 `image.close()` 必须出现在 `logger.error(89, ...)` 之前(compact `image.close();logger.error(89,`),且 `image.width` / `image.height` 的读取在 close 之前(仍用于越界判定)。
- 新增断言 82–96 全部出现在 `parse.ts`;92–96 现在都是合法码,测试不得断言 92–95 缺失(若既有测试原本没有此类否定断言则无需改动,也不要新增)。
- 不得新增 `it`,也不得新增任何具名辅助函数(D-04:命名须先获批;提取逻辑内联在既有 `it` 中)。
6. **不新增 / 不删除用例:** 总数仍 70;每个 `it` 前有一行注释;成功用例 11 条断言不变。
7. 不碰 `parse.ts` / `logger.json` / `animater.ts` / `animater.test.ts` / 其它文件。
</action>
<verify>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8');const fail=[];const pairs=[[82,1],[83,0],[84,0],[85,1],[86,1],[87,1],[88,2],[89,1],[90,0],[91,2],[92,3],[93,1],[94,3],[95,1],[96,1]];if(t.indexOf('ERROR_PARAM_COUNTS')===-1)fail.push('ERROR_PARAM_COUNTS missing');pairs.forEach(p=>{if(!new RegExp('\\b'+p[0]+'\\s*:\\s*'+p[1]+'\\b').test(t))fail.push('map missing '+p[0]+':'+p[1]);});if(!/calls\[0\]\.length\s*===\s*ERROR_PARAM_COUNTS\[[^\]]+\]\s*\+\s*1/.test(t))fail.push('arity assertion missing');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 82..96 param-count map and arity assertion present');"</automated>
<fails_when>`parse.test.ts` 缺 `ERROR_PARAM_COUNTS` 的新映射或 `expectFailure` 未断言 `calls[0].length === ERROR_PARAM_COUNTS[code] + 1`(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8');const SQ=String.fromCharCode(39);const fail=[];for(let c=82;c<=96;c++){if(!new RegExp('\\b'+c+'\\b').test(t))fail.push('missing expected code '+c);}const guard='if(!isRecord(meta)){logger.error(95,'+SQ+'not-object'+SQ+');returnnull;}returnmeta;';if(t.indexOf(guard)===-1)fail.push('static guard 95 text missing');if(t.indexOf('catch(error)')!==-1)fail.push('old catch(error) assertion remains');if(t.indexOf('catch{')===-1)fail.push('catch{ assertion missing');for(const label of ['decode-failed','texture-failed','not-object'])if(t.indexOf(SQ+label+SQ)===-1)fail.push('missing label '+label);if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: parse.test covers 82..96 and the updated static guard');"</automated>
<fails_when>`parse.test.ts` 缺 82–96、未更新 95 号守卫、仍含 `catch(error)` 断言、缺 `catch{`,或缺 `decode-failed` / `texture-failed` / `not-object` 断言(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8');const fail=[];const its=(t.match(/^\s*it\s*\(/gm)||[]).length;if(its!==70)fail.push('it count='+its+', expected 70');if(/calls\[0\]\[(9|10)\]/.test(t))fail.push('old [9]/[10] dimension assertion remains');if(t.indexOf('toHaveBeenCalledTimes(1)')===-1)fail.push('single-log assertion missing');if(t.indexOf('out-of-bounds')!==-1)fail.push('old out-of-bounds reason assertion remains');if(!/calls\[0\]\[1\]\s*\)\s*\.toBe\('0'\)/.test(t))fail.push('boundary index assertion missing');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 70 tests, old dimension assertions removed, single-log assertion kept');"</automated>
<fails_when>测试数不是 70、仍保留 `[9]` / `[10]` 尺寸断言、仍保留旧的 `'out-of-bounds'` 原因断言、缺索引 `'0'` 断言,或缺「只记一次日志」断言(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const lines=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8').replace(/\r\n/g,'\n').split('\n');const bad=[];for(let i=0;i<lines.length;i++){if(!/\bit\s*\(/.test(lines[i]))continue;let j=i-1;while(j>=0&&lines[j].trim()==='')j--;if(j<0||!lines[j].trim().startsWith('//'))bad.push(i+1);}if(bad.length){console.error('it without // comment: '+bad.join(','));process.exit(1);}console.log('OK: every it has a // comment on the preceding non-empty line');"</automated>
<fails_when>存在 `it` 前没有单行注释(打印行号,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8');const fail=[];if(t.indexOf('A-Za-z0-9_')===-1)fail.push('index .toString() regex missing');if(t.indexOf('buffer-too-short')===-1)fail.push('allowed reason set missing');if(t.indexOf('@throws')===-1)fail.push('static guard it lost');if(t.indexOf('extractLoggerCalls')!==-1)fail.push('new named helper extractLoggerCalls must not be added');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: no-value static assertions present (details checked by vitest run)');"</automated>
<fails_when>`parse.test.ts` 未新增「无值实参」静态断言(缺索引正则 `A-Za-z0-9_` 片段、缺允许原因集合),或新增了具名辅助函数 `extractLoggerCalls`(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8');const n=(t.match(/calls\[0\]\[3\]/g)||[]).length;const its=(t.match(/^\s*it\s*\(/gm)||[]).length;if(n<2){console.error('expected >=2 calls[0][3] arg-order assertions (92 & 94), found '+n);process.exit(1);}if(its!==70){console.error('it count='+its+', expected 70');process.exit(1);}console.log('OK: '+n+' calls[0][3] assertions and 70 its');"</automated>
<fails_when>`parse.test.ts` 缺少至少 2 处 `calls[0][3]` 参数顺序断言(分别覆盖 92 与 94 的 reason),或 `it` 数不为 70(打印实测,退出码 1)。</fails_when>
<automated>node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts</automated>
<fails_when>退出码非 0,或输出未报告 70 passed;browserslist 的 stderr 提示属正常,不作为失败依据。</fails_when>
<automated>node node_modules/prettier/bin/prettier.cjs --check packages/render-anim/src/__test__/parse.test.ts</automated>
<fails_when>prettier 报告该文件待格式化,或退出码非 0。</fails_when>
<automated>node node_modules/eslint/bin/eslint.js packages/render-anim/src/__test__/parse.test.ts</automated>
<fails_when>eslint 打印任一 error / warning,或退出码非 0。</fails_when>
<automated>node -e "const fs=require('fs');const b=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts');const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;const ok=lf===crlf&&tabs===0&&!bom;console.log((ok?'OK':'FAIL')+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);process.exit(ok?0:1);"</automated>
<fails_when>出现非 CRLF 换行、制表符或 BOM(打印 `FAIL`,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- `parse.test.ts` 只覆盖 82–96,注释同步;`ERROR_PARAM_COUNTS` 与 `expectFailure` arity 断言正确。
- 越界用例断言 code 89 + 索引并保留 `image.close`;解码 / 纹理断言 96 + reason;非对象元数据断言 `not-object`。
- 至少一个 92 用例断言 `calls[0][1]` / `calls[0][2]` / `calls[0][3]` 分别为帧索引 / 对象索引 / reason;至少一个 94 用例断言 `calls[0][1]` / `calls[0][2]` / `calls[0][3]` 分别为帧索引 / 音效索引 / reason;未新增 `it`(仍 70)。
- 静态闸门使用 `catch{` 与 95 号守卫,不对 92–95 作缺失断言(92–96 均为合法码),并新增「无值实参」断言。
- 恰 70 个用例,每个 `it` 前有一行注释;成功用例断言不变。
- targeted vitest 报告 70 passed;prettier / eslint / CRLF / BOM 通过。
</acceptance_criteria>
<done>`parse.test.ts` 已同步为 82–96 的期望码、`ERROR_PARAM_COUNTS`、arity 断言、注释与静态闸门(含无值实参断言),并强化既有 92 / 94 用例断言帧索引 / 对象或音效索引 / reason 的实参顺序(未新增 `it`);70 个用例全部通过;prettier / eslint / CRLF / BOM 通过。</done>
</task>
<task type="auto">
<name>Task 5: 全量验证(静态门禁 + vitest 70 + prettier / eslint / CRLF + 过滤 vue-tsc),只读不写</name>
<dependencies>Task 4(3 个目标文件全部改完)</dependencies>
<files>无(本任务只运行只读校验;不写仓库文件、不改 SUMMARY;`vue-tsc` 若生成任何 `*.tsbuildinfo` 必须立即删除,不得留在仓库、不得产生新的 git status 条目)</files>
<read_first>
- 本计划「logger.json error 82–96 最终文本」「logger 调用点参数规范」「`parse.ts` 行为不变量」「`parse.test.ts` 改写规格」
- `packages/render-anim/src/parse.ts`、`parse.test.ts`、`packages/common/src/logger.json`(Task 2–4 产物)
- `packages/render-anim/src/animater.ts` / `types.ts` / `index.ts` / `package.json`(只验证)
- `(process.env.TEMP||'.')/gsd-09-57-hashes.txt`、`gsd-09-57-logger-baseline.json`(Task 1 基线)
</read_first>
<action>
本任务只读验证,不写任何文件。
1. 运行 `node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts`,记录实际用例数(应为 70)。
2. 运行 prettier `--check`:3 个改动文件(`parse.ts` / `parse.test.ts` / `logger.json`)。
3. 运行 eslint:`parse.ts` / `parse.test.ts`。
4. 运行 CRLF / BOM / tab 检查:3 个改动文件。
5. 运行过滤类型检查:先 `node node_modules/vue-tsc/bin/vue-tsc.js --version` 哨兵,再**必须**运行 `node node_modules/vue-tsc/bin/vue-tsc.js --noEmit --incremental false`,只统计匹配 `packages[\\/]render-anim`(同时接受 `/` 与 `\`)的诊断行;全仓其它既有诊断与总退出码不参与判定。**若 vue-tsc 拒绝 `--incremental false`(`Unknown compiler option` / `TS5023` / `TS6379` / `may not disable incremental`),直接失败并上报,不得回退为不带该参数的 `--noEmit`。** 若运行后生成 `*.tsbuildinfo`,立即删除并断言仓库根目录无 `*.tsbuildinfo` 且 `git status --porcelain -uall` 无 `tsbuildinfo` 条目。
6. 运行综合静态门禁(复用 Task 3 的平衡括号参数门禁 + Task 2 的 logger 表比对 + 行为不变量):
- `parse.ts`:82–96 全在;每个 `logger.error` ≤3 参数;实参只含 `.toString()` 索引或允许的原因标签;无 `'-'` / 值形式 `String(value)`(不含 `.toString()`)/ `.message` / actual / expected;3 处 `try`;无 `throw` / `finally`;可空签名;可选字段与 `isRecord` 不变量;`new Blob` 在 `try` 外;位图越界先 `image.close()` 再 `logger.error(89, ...)`(compact `image.close();logger.error(89,`)且宽高在 close 前读取;纹理失败先 close(compact `image.close();logger.error(96,'texture-failed');`);92 按 `logger.error(92,frameIndex.toString(),objectIndex.toString(),` 顺序、94 按 `logger.error(94,frameIndex.toString(),i.toString(),` 顺序(帧索引在前、对象/音效索引在后、reason 最后);3 组 region;95 号守卫 compact 文本。
- `logger.json`:82–96 与计划表逐字一致、占位符数量正确、两两不同、非 `$1`-only;`1..81` / `2001..2008` / warn 与 Task 1 快照逐字一致。
- `parse.test.ts`:70 个 `it`;92–96 均为合法码,不得断言 92–95 缺失;含 `ERROR_PARAM_COUNTS` 与 arity 断言;无 `[9]` / `[10]` 尺寸断言(用 `/calls\[0\]\[(9|10)\]/` 判定);每个 `it` 有注释。
7. 记录所有真实输出(用例数、退出码、过滤结果),供 Task 6 写入 SUMMARY;若任一失败,停止并上报,不得进入 Task 6。
</action>
<verify>
<automated>node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts</automated>
<fails_when>退出码非 0,或输出未报告 70 passed;browserslist 的 stderr 提示属正常,不作为失败依据。</fails_when>
<automated>node node_modules/prettier/bin/prettier.cjs --check packages/render-anim/src/parse.ts packages/render-anim/src/__test__/parse.test.ts packages/common/src/logger.json</automated>
<fails_when>prettier 报告任一文件待格式化,或退出码非 0。</fails_when>
<automated>node node_modules/eslint/bin/eslint.js packages/render-anim/src/parse.ts packages/render-anim/src/__test__/parse.test.ts</automated>
<fails_when>eslint 打印任一 error / warning,或退出码非 0。</fails_when>
<automated>node -e "const fs=require('fs');const files=['packages/render-anim/src/parse.ts','packages/render-anim/src/__test__/parse.test.ts','packages/common/src/logger.json'];const fail=[];files.forEach(f=>{const b=fs.readFileSync(f);const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;if(lf!==crlf||tabs||bom)fail.push(f+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 3 files are CRLF, no tabs, no BOM');"</automated>
<fails_when>任一改动文件出现非 CRLF 换行、制表符或 BOM(打印实际值,退出码 1)。</fails_when>
<automated>node -e "const{spawnSync}=require('child_process');const r=spawnSync(process.execPath,['node_modules/vue-tsc/bin/vue-tsc.js','--version'],{encoding:'utf8'});if(r.status!==0){console.error('vue-tsc sentinel failed: '+(r.stderr||r.stdout));process.exit(1);}console.log('OK: vue-tsc sentinel '+String(r.stdout).trim());"</automated>
<fails_when>`vue-tsc --version` 哨兵无法启动(退出码非 0)(打印 stderr / stdout,退出码 1)。</fails_when>
<automated>node -e "const{spawnSync}=require('child_process');const r=spawnSync(process.execPath,['node_modules/vue-tsc/bin/vue-tsc.js','--noEmit','--incremental','false'],{encoding:'utf8',maxBuffer:1e8});const out=((r.stdout||'')+(r.stderr||'')).split(/\r?\n/);const rejected=out.filter(l=>/Unknown compiler option|TS5023|TS6379|may not disable incremental/i.test(l));if(rejected.length){console.error('vue-tsc rejected --incremental false:\n'+rejected.join('\n'));process.exit(1);}const hits=out.filter(l=>/packages[\\/]render-anim/.test(l));if(hits.length){console.error('render-anim diagnostics:\n'+hits.join('\n'));process.exit(1);}console.log('OK: 0 ts diagnostics under packages/render-anim (vue-tsc exit '+r.status+')');"</automated>
<fails_when>`vue-tsc --noEmit --incremental false` 被拒绝(直接失败,不回退),或出现任何匹配 `packages[\\/]render-anim` 的诊断行(打印这些行,退出码 1);生成物必须清理干净。</fails_when>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const root=fs.readdirSync('.').filter(f=>f.endsWith('.tsbuildinfo'));if(root.length){console.error('tsbuildinfo left in repo root: '+root.join(', '));process.exit(1);}const st=execSync('git status --porcelain -uall',{encoding:'utf8'}).split(/\r?\n/).filter(l=>l.indexOf('tsbuildinfo')!==-1);if(st.length){console.error('tsbuildinfo in git status: '+st.join(' | '));process.exit(1);}console.log('OK: no *.tsbuildinfo in repo root and none in git status');"</automated>
<fails_when>仓库根目录仍存在 `*.tsbuildinfo`,或 `git status` 出现含 `tsbuildinfo` 的条目(打印实际条目,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const src=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const SQ=String.fromCharCode(39);const key='logger.error(';const calls=[];let idx=0;while(true){const p=src.indexOf(key,idx);if(p<0)break;let i=p+key.length,depth=1,args='',quote=false;while(i<src.length&&depth>0){const c=src[i];if(quote){if(c==='\\'){args+=c+src[i+1];i+=2;continue;}if(c===SQ)quote=false;args+=c;i++;continue;}if(c===SQ){quote=true;args+=c;i++;continue;}if(c==='('){depth++;args+=c;i++;continue;}if(c===')'){depth--;if(depth===0){i++;break;}args+=c;i++;continue;}args+=c;i++;}calls.push(args);idx=i;}const allowed=new Set(['buffer-too-short','length-mismatch','invalid-count','table-overflow','not-array','count-mismatch','not-object','invalid-x','invalid-y','invalid-width','invalid-height','objects-not-array','sound-not-array','not-tuple','invalid-field-count','invalid-index','invalid-scale','invalid-opacity','invalid-mirror','invalid-rotate','invalid-ratio','invalid-blend','invalid-name','invalid-volume','invalid-pitch','invalid-json','decode-failed','texture-failed']);const fail=[];calls.forEach((a,n)=>{const parts=[];let depth=0,q=false,buf='';for(let i=0;i<a.length;i++){const c=a[i];if(q){if(c==='\\'){buf+=c+(a[i+1]||'');i++;continue;}if(c===SQ)q=false;buf+=c;continue;}if(c===SQ){q=true;buf+=c;continue;}if(c==='(')depth++;if(c===')')depth--;if(c===','&&depth===0){parts.push(buf.trim());buf='';continue;}buf+=c;}if(buf.trim())parts.push(buf.trim());const code=parts[0];if(!/^(8[2-9]|9[0-6])$/.test(code))fail.push('call '+n+' unknown code '+code);if(parts.length<1||parts.length>4)fail.push('call '+n+' arity '+(parts.length-1)+' params (>3)');for(const raw of parts.slice(1)){const p=raw.trim();if(new RegExp('^[A-Za-z_][A-Za-z0-9_]*\\.toString\\(\\)$').test(p))continue;if(new RegExp('^'+SQ+'[a-z][a-z-]*'+SQ+'$').test(p)){if(!allowed.has(p.slice(1,-1)))fail.push('call '+n+' unknown reason '+p);continue;}fail.push('call '+n+' invalid param '+p);}});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: '+calls.length+' logger calls: <=3 params, index .toString() or allowed kebab reason only, no values');"</automated>
<fails_when>综合参数门禁失败(调用超过 3 参数、参数不是索引 `.toString()` 或允许的原因、出现值 / `'-'` / 值形式 `String(value)` / `.message`、code 越界)(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const p=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const fail=[];if((p.match(/#region/g)||[]).length!==3||(p.match(/#endregion/g)||[]).length!==3)fail.push('region count');if((p.match(/try\s*\{/g)||[]).length!==3)fail.push('try count');if(/\bthrow\b/.test(p))fail.push('throw');if(/\bfinally\b/.test(p))fail.push('finally');if(p.indexOf('Promise<IAnimationParsedData | null>')===-1)fail.push('signature');for(const need of ['object[5] !== undefined','object[6] !== undefined','item.volume !== undefined','item.pitch !== undefined','value !== null','new Blob','if (!isRecord(meta))','image.close()'])if(p.indexOf(need)===-1)fail.push('missing '+need);const compact=p.replace(/\s+/g,'');if(compact.indexOf('try{image=awaitcreateImageBitmap(webpBlob);}catch{')===-1)fail.push('decode catch');if(compact.indexOf('try{texture=newTexture(image);}catch{')===-1)fail.push('texture catch');if(compact.indexOf('if(!isRecord(meta)){logger.error(95,'+String.fromCharCode(39)+'not-object'+String.fromCharCode(39)+');returnnull;}returnmeta;')===-1)fail.push('95 guard');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: parse.ts behavior invariants and structure intact');"</automated>
<fails_when>行为不变量或结构门禁失败(region / try / throw / finally / 签名 / 可选字段 / isRecord / Blob / close / unbound catch / 95 守卫)(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const SQ=String.fromCharCode(39);const fail=[];if(/\bString\s*\(/.test(t))fail.push('String(value) present');if(t.indexOf('.message')!==-1)fail.push('.message present');if(t.indexOf(SQ+'-'+SQ)!==-1)fail.push('dash placeholder present');const c=t.replace(/\s+/g,'');const close=c.indexOf('image.close();logger.error(89,');if(close===-1)fail.push('image.close() before logger.error(89, ...) missing');const w=c.indexOf('image.width'),h=c.indexOf('image.height');if(w===-1||h===-1||w>close||h>close)fail.push('image dimensions not read before close for bounds check');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: no String(value)/message/dash; image.close() precedes logger.error(89, ...); dimensions read before close');"</automated>
<fails_when>`parse.ts` 仍含值形式 `String(value)`(`.toString()` 不算)/ `.message` / `'-'`,或 `image.close()` 不在 `logger.error(89, ...)` 之前、宽高未在 close 前读取(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const c=t.replace(/\s+/g,'');const needle='image.close();logger.error(96,'+String.fromCharCode(39)+'texture-failed'+String.fromCharCode(39)+');';if(c.indexOf(needle)===-1){console.error('texture close-before-log missing (expected compact: '+needle+')');process.exit(1);}console.log('OK: texture path closes image before logging 96 texture-failed');"</automated>
<fails_when>纹理失败路径缺少 compact `image.close();logger.error(96,'texture-failed');`(close 必须在记日志之前;独立于越界 `image.close();logger.error(89,` gate)(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/parse.ts','utf8');const c=t.replace(/\s+/g,'');const fail=[];if(c.indexOf('logger.error(92,frameIndex.toString(),objectIndex.toString(),')===-1)fail.push('92 arg order (frame,objectIndex,reason) missing');if(c.indexOf('logger.error(94,frameIndex.toString(),i.toString(),')===-1)fail.push('94 arg order (frame,sound index i,reason) missing');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 92/94 pass frame index first, object/sound index second, reason third');"</automated>
<fails_when>92 未按 `logger.error(92,frameIndex.toString(),objectIndex.toString(),` 顺序、94 未按 `logger.error(94,frameIndex.toString(),i.toString(),` 顺序(帧索引在前、对象/音效索引在后、reason 最后)(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const base=JSON.parse(fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-57-logger-baseline.json','utf8'));const D=String.fromCharCode(36);const generic='Cannot parse animation: '+D+'1.';const msgs=[];const fail=[];for(let c=82;c<=96;c++){const m=j.error[c];if(typeof m!=='string'){fail.push('missing '+c);continue;}msgs.push(m);if(m===generic)fail.push('generic message '+c);}if(new Set(msgs).size!==msgs.length)fail.push('duplicate messages');Object.keys(base.error).forEach(k=>{const n=+k;if(n>=82&&n<=91)return;if(j.error[k]!==base.error[k])fail.push('error '+k+' changed');});if(JSON.stringify(j.warn)!==JSON.stringify(base.warn))fail.push('warn changed');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 82..96 distinct specific messages; 1..81 / 2001..2008 / warn unchanged');"</automated>
<fails_when>`logger.json` 的 82–96 缺失 / 重复 / 泛化,或既有码段 / warn 与快照不一致(打印原因,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const counts={82:1,83:0,84:0,85:1,86:1,87:1,88:2,89:1,90:0,91:2,92:3,93:1,94:3,95:1,96:1};const D=String.fromCharCode(36);const re=new RegExp('['+D+'][0-9]+','g');const fail=[];Object.keys(counts).forEach(k=>{const msg=j.error[k]||'';const used=new Set();(msg.match(re)||[]).forEach(m=>used.add(+m.slice(1)));const nums=[...used].sort((a,b)=>a-b);const max=nums.length?nums[nums.length-1]:0;if(nums.length!==counts[k]||max!==counts[k])fail.push('code '+k+' uses '+nums.length+' params (max '+max+'), expected '+counts[k]);});if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: placeholder counts match the parser call sites');"</automated>
<fails_when>任一 82–96 消息的 `$n` 数量与规范不符,或占位跳号(打印实际与期望,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const BT=String.fromCharCode(96);const plan=fs.readFileSync('.planning/phases/09-minimum-browser-runnable/09-57-PLAN.md','utf8').replace(/\r\n/g,'\n');const log=JSON.parse(fs.readFileSync('packages/common/src/logger.json','utf8'));const digits=s=>s.length>0&&s.split('').every(ch=>ch>='0'&&ch<='9');const rows=plan.split('\n').map(l=>l.trim()).filter(l=>l.indexOf('|')===0).map(l=>l.split('|').map(s=>s.trim()));const expected={};rows.forEach(all=>{const c=all.filter((s,i)=>i>0&&i<all.length-1);if(c.length!==3||!digits(c[0]))return;const n=+c[0];if(n<82||n>96)return;const cell=c[1];if(cell.length>2&&cell.slice(0,1)===BT&&cell.slice(-1)===BT)expected[n]=cell.slice(1,-1);});const fail=[];for(let n=82;n<=96;n++){if(!expected[n])fail.push('plan table row missing for '+n);else if(log.error[n]!==expected[n])fail.push('message mismatch for '+n+' (json='+JSON.stringify(log.error[n])+' plan='+JSON.stringify(expected[n])+')');}const msgs=Object.keys(expected).map(k=>expected[k]);if(new Set(msgs).size!==msgs.length)fail.push('duplicate messages between 82..96');if(msgs.some(m=>m===('Cannot parse animation: '+String.fromCharCode(36)+'1.')))fail.push('generic placeholder-only message present');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: 82..96 messages match the plan table verbatim, distinct, non-generic');"</automated>
<fails_when>82–96 任一消息与计划表不是逐字一致、15 条消息出现重复,或存在 `Cannot parse animation: $1.` 泛化消息(打印差异,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const t=fs.readFileSync('packages/render-anim/src/__test__/parse.test.ts','utf8');const fail=[];if((t.match(/^\s*it\s*\(/gm)||[]).length!==70)fail.push('it count');if(/calls\[0\]\[(9|10)\]/.test(t))fail.push('old dimension assertion remains');if(t.indexOf('ERROR_PARAM_COUNTS')===-1)fail.push('ERROR_PARAM_COUNTS');if(!/calls\[0\]\.length\s*===\s*ERROR_PARAM_COUNTS\[[^\]]+\]\s*\+\s*1/.test(t))fail.push('arity assertion');if(fail.length){console.error(fail.join('; '));process.exit(1);}console.log('OK: parse.test has 70 tests, no old dimension assertions, arity map present');"</automated>
<fails_when>`parse.test.ts` 不是 70 个用例、仍保留旧尺寸断言,或缺 arity 映射 / 断言(打印原因,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- targeted vitest 报告 70 passed。
- prettier `--check`、eslint、CRLF / BOM / tab 对 3 个改动文件全部通过。
- `vue-tsc --version` 哨兵通过,`--noEmit --incremental false` 过滤 `packages/render-anim` 诊断 0 行;参数被拒即失败(不回退);仓库根目录无 `*.tsbuildinfo`、git status 无 `tsbuildinfo`。
- 综合参数门禁:所有 `logger.error` ≤3 参数,实参只有 `.toString()` 索引或允许的原因标签,无任何值。
- 行为不变量:3 组 region、3 处 `try`、无 `throw` / `finally`、可空签名、可选字段 / `isRecord` 不变量、`new Blob` 在 `try` 外、`image.close()` 在 `logger.error(89, ...)` 之前且宽高先读、纹理失败先 close(compact `image.close();logger.error(96,'texture-failed');` 精确匹配)、92/94 帧索引在前的 compact 顺序断言通过、无绑定 catch、95 号守卫。
- `logger.json` 82–96 与计划表逐字一致、占位符数量 1/0/0/1/1/1/2/1/0/2/3/1/3/1/1、互异、非泛化;`1..81` / `2001..2008` / warn 与快照一致。
- `parse.test.ts` 70 用例、无旧尺寸断言、含 arity 断言。
- 本任务未写任何仓库文件(`*.tsbuildinfo` 若生成已在收尾删除)。
</acceptance_criteria>
<done>vitest 70 passed、prettier、eslint、CRLF / BOM、过滤 vue-tsc(`--incremental false`,被拒即失败、不回退)与综合静态门禁全部通过(含纹理失败先 close 与 92/94 帧索引在前的 compact 断言);真实输出已记录,未写任何仓库文件。</done>
</task>
<task type="auto">
<name>Task 6: 范围 / 哈希复核并写 `09-57-SUMMARY.md`(文件清单、映射、测试数量、风格说明、偏差)</name>
<dependencies>Task 5(全部门禁通过)</dependencies>
<files>.planning/phases/09-minimum-browser-runnable/09-57-SUMMARY.md</files>
<read_first>
- 本计划的 `<success_criteria>` 与「覆盖审计」(SUMMARY 必须覆盖的条目)
- `(process.env.TEMP||'.')/gsd-09-57-status.txt`、`gsd-09-57-hashes.txt`、`gsd-09-57-logger-baseline.json`(Task 1 基线)
- `packages/render-anim/src/parse.ts`、`parse.test.ts`、`packages/common/src/logger.json`(Task 2–4 产物)
- Task 5 记录的真实输出(用例数、prettier / eslint / vue-tsc / CRLF 结果)
- `.planning/phases/09-minimum-browser-runnable/09-56-SUMMARY.md`(SUMMARY 结构与 frontmatter 风格参考)
- `AGENTS.md` / `dev.md`(CRLF、无 BOM)
</read_first>
<action>
本任务只写 `09-57-SUMMARY.md`,不改任何代码文件。
1. **写 SUMMARY 前的范围闸门(必须在写文件之前内联执行):** 要求 `addedIn` 为空、`removedIn` / `addedOut` / `removedOut` / `extra` / `missing` 为空,**且显式断言 `09-57-SUMMARY.md` 尚不存在**(`fs.existsSync` 为 false,且 `git status --porcelain -uall` 中没有任何 `09-57-SUMMARY.md` 条目)。仓库根目录不得存在任何 `*.tsbuildinfo`。任一不符,停下上报,不写 SUMMARY。
2. **写 SUMMARY 前的哈希闸门:** 9 条基线(均为完整仓库相对路径)中**排除 `.planning/phases/09-minimum-browser-runnable/09-57-PLAN.md`**,只比较其余 8 条;其中只允许 `packages/render-anim/src/parse.ts`、`packages/render-anim/src/__test__/parse.test.ts`、`packages/common/src/logger.json` 的哈希变化,`packages/render-anim/src/animater.ts` / `packages/render-anim/src/__test__/animater.test.ts` / `packages/render-anim/src/types.ts` / `packages/render-anim/src/index.ts` / `packages/render-anim/package.json` 哈希不变。预期变化集合恰为这 3 个目标文件。
3. **写 `09-57-SUMMARY.md`**:UTF-8 无 BOM、CRLF、4 空格缩进的 Markdown。frontmatter 至少包含 `phase: 09-minimum-browser-runnable`、`plan: 57`、`subsystem: render-anim`、`tags`、`requires`、`provides`、`affects`、`actuals`(tokens / tasks / commits: 0)、`tech-stack`、`key-files`(modified)、`key-decisions`、`patterns-established`、`duration`、`completed`、`status: complete`。正文至少包含:
- **本次范围**:只改 3 个文件 + 本 SUMMARY;`animater.ts` / `types.ts` / `index.ts` / `package.json` 未动;不跑游戏 / 浏览器 / dev server;**0 次提交**;09-57 / 波次 6 / `depends_on: 09-56` 的编号说明。
- **文件清单**:逐个列出 3 个改动文件与本 SUMMARY。
- **错误码映射(09-56 → 09-57)**:逐条说明 82–91 的旧参数布局如何收敛到 82–96 的原因 + 索引布局;92–95 从「已删除」重新变为合法码(92 对象 / 93 标量 / 94 音效 / 95 元数据),96 为图像失败。
- **测试数量**:parse 实测 70 用例(改写前后均为 70);记录 `ERROR_PARAM_COUNTS` 新映射与 `expectFailure` arity 断言。
- **风格说明**:说明 82–96 与既有 logger 风格一致(具体上下文 + reason / 索引,无值),并指出反例 `Cannot parse animation: $1.` 不存在。
- **行为不变说明**:无绑定 catch、删除 `reason`、位图越界先 close、纹理失败先 close、`validateBitmapBounds` 仍读图像宽高做判定但不写日志。
- **96 号字面量(内容门禁依赖)**:SUMMARY 正文必须逐字包含 `decode-failed` 与 `texture-failed` 两个字符串(分别对应解码失败与纹理失败路径),不得只写中文描述。
- **明确未改项**:09-56 jsDoc / 注释 / region / 类级 jsDoc / 单画布;提前返回、`validateMeta` 嵌套、可选字段 `!== undefined`、`isRecord` 的 `value !== null`。
- **门禁结果**:真实输出摘要(vitest 用例数、prettier / eslint / CRLF / BOM、过滤 `packages[\\/]render-anim` 的 vue-tsc、综合静态门禁、哈希闸门)。
- **偏差**:如有(例如测试局部辅助函数命名、用例注释调整、用例数量差异),逐条记录;无偏差则写「无」。
- **未校准估算**:`confidence: low`、`tokens: 80000`(7 个任务 / 80k 仅为 advisory 建议值,不作为拆分依据、不阻断执行)。
4. **写后的范围闸门:** `added` 恰为 `?? .planning/phases/09-minimum-browser-runnable/09-57-SUMMARY.md`;`extra` / `missing` / `removedIn` / `addedOut` / `removedOut` 为空。
5. 不写 RESEARCH / VALIDATION;不改 `STATE.md` / `ROADMAP.md` / `09-CONTEXT.md` / 09-56 计划与摘要;不执行任何 git 写命令。
</action>
<verify>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const sumPath='.planning/phases/09-minimum-browser-runnable/09-57-SUMMARY.md';const base=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-57-status.txt','utf8').split(/\r?\n/).filter(l=>l.length>0);const cur=execSync('git status --porcelain -uall',{encoding:'utf8'}).split(/\r?\n/).filter(l=>l.length>0);if(fs.existsSync(sumPath)){console.error('SUMMARY already exists before write');process.exit(1);}if(cur.some(l=>l.indexOf('09-57-SUMMARY.md')!==-1)){console.error('SUMMARY already present in git status');process.exit(1);}const inScope=l=>{const p=l.slice(3);return p.indexOf('packages/render-anim/')===0||p.indexOf('packages/common/src/logger.json')===0||p.indexOf('.planning/phases/09-minimum-browser-runnable/')===0;};const added=cur.filter(l=>base.indexOf(l)===-1);const removed=base.filter(l=>cur.indexOf(l)===-1);const addedIn=added.filter(inScope);const addedOut=added.filter(l=>!inScope(l));const removedIn=removed.filter(inScope);const removedOut=removed.filter(l=>!inScope(l));const pre=addedIn.filter(l=>l.indexOf('09-57-SUMMARY.md')===-1);if(pre.length||removedIn.length||addedOut.length||removedOut.length){console.error('range drift');process.exit(1);}console.log('OK: SUMMARY absent; no status change other than the summary itself');"</automated>
<fails_when>`09-57-SUMMARY.md` 在写前已存在或已出现在 git status,或出现 SUMMARY 之外的新增 / 删除条目(打印分组,退出码 1)。</fails_when>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const p=(process.env.TEMP||'.')+'/gsd-09-57-hashes.txt';const plan='.planning/phases/09-minimum-browser-runnable/09-57-PLAN.md';const base=fs.readFileSync(p,'utf8').replace(/\r\n/g,'\n').trim().split('\n').filter(Boolean).filter(l=>l.split(' ')[0]!==plan);const now=base.map(l=>{const f=l.split(' ')[0];return f+' '+execSync('git hash-object '+f,{encoding:'utf8'}).trim();});const changed=now.filter(l=>base.indexOf(l)===-1);const expected=['packages/render-anim/src/parse.ts','packages/render-anim/src/__test__/parse.test.ts','packages/common/src/logger.json'];const names=changed.map(l=>l.split(' ')[0]);const missing=expected.filter(f=>names.indexOf(f)===-1);const extra=names.filter(n=>expected.indexOf(n)===-1);console.log('changed:\n'+changed.join('\n'));if(base.length!==8||missing.length||extra.length){console.error('unexpected changed set; missing='+missing.join(',')+' extra='+extra.join(','));process.exit(1);}console.log('OK: PLAN excluded; exactly the 3 intended files changed among the 8 compared baselines');"</automated>
<fails_when>排除 `.planning/phases/09-minimum-browser-runnable/09-57-PLAN.md` 后变化的文件不是恰好 3 个目标文件(含 `animater.ts` / `animater.test.ts` / `types.ts` / `index.ts` / `package.json` 被改动),或比较基线行数不是 8(打印差异,退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const f='.planning/phases/09-minimum-browser-runnable/09-57-SUMMARY.md';const s=fs.readFileSync(f,'utf8');const need=['09-57','parse.ts','parse.test.ts','logger.json','82','96','92','95','ERROR_PARAM_COUNTS','decode-failed','texture-failed','vitest','prettier','eslint','vue-tsc','0 次提交','偏差','未校准','70','风格'];const miss=need.filter(n=>s.indexOf(n)===-1);if(miss.length){console.error('missing '+miss.join(','));process.exit(1);}console.log('OK: summary content present');"</automated>
<fails_when>SUMMARY 缺少文件清单 / 错误码映射 / 行为变更 / 明确未改项 / 测试数量 / 风格说明 / 门禁结果 / 偏差 / 未校准估算 / 0 提交等关键内容(打印缺失项,退出码 1)。</fails_when>
<automated>node -e "const{execSync}=require('child_process'),fs=require('fs');const base=fs.readFileSync((process.env.TEMP||'.')+'/gsd-09-57-status.txt','utf8').split(/\r?\n/).filter(l=>l.length>0);const cur=execSync('git status --porcelain -uall',{encoding:'utf8'}).split(/\r?\n/).filter(l=>l.length>0);const summary='?? .planning/phases/09-minimum-browser-runnable/09-57-SUMMARY.md';const added=cur.filter(l=>base.indexOf(l)===-1);const removed=base.filter(l=>cur.indexOf(l)===-1);const inScope=l=>{const p=l.slice(3);return p.indexOf('packages/render-anim/')===0||p.indexOf('packages/common/src/logger.json')===0||p.indexOf('.planning/phases/09-minimum-browser-runnable/')===0;};const addedIn=added.filter(inScope);const addedOut=added.filter(l=>!inScope(l));const removedIn=removed.filter(inScope);const removedOut=removed.filter(l=>!inScope(l));const extra=addedIn.filter(l=>l!==summary);const missing=addedIn.indexOf(summary)===-1?[summary]:[];if(extra.length||missing.length||removedIn.length||addedOut.length||removedOut.length){console.error('post-write range drift');process.exit(1);}console.log('OK: post-write range is exactly the summary');"</automated>
<fails_when>写后 `addedIn` 不是恰好 `09-57-SUMMARY.md`,或出现 `extra` / `missing` / `removedIn` / `addedOut` / `removedOut`(退出码 1)。</fails_when>
<automated>node -e "const fs=require('fs');const b=fs.readFileSync('.planning/phases/09-minimum-browser-runnable/09-57-SUMMARY.md');const s=b.toString('utf8');const lf=(s.match(/\n/g)||[]).length;const crlf=(s.match(/\r\n/g)||[]).length;const tabs=(s.match(/\t/g)||[]).length;const bom=b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF;const ok=lf===crlf&&tabs===0&&!bom;console.log((ok?'OK':'FAIL')+' lf='+lf+' crlf='+crlf+' tabs='+tabs+' bom='+bom);process.exit(ok?0:1);"</automated>
<fails_when>SUMMARY 出现非 CRLF 换行、制表符或 BOM(打印 `FAIL`,退出码 1)。</fails_when>
</verify>
<acceptance_criteria>
- 写 SUMMARY 前的范围闸门在 `<action>` 第 1 步内联执行:除 SUMMARY 自身外无新增 / 删除条目,且显式断言 `09-57-SUMMARY.md` 尚不存在;仓库根目录无 `*.tsbuildinfo`。
- 哈希闸门:排除 `.planning/phases/09-minimum-browser-runnable/09-57-PLAN.md` 后比较 8 条基线(完整仓库相对路径),只有 3 个目标文件变化;`animater.ts` / `animater.test.ts` / `types.ts` / `index.ts` / `package.json` 不变。
- `09-57-SUMMARY.md` 已写入(UTF-8 无 BOM + CRLF),覆盖文件清单、测试数量(70)、82–91 → 82–96 映射与 92–96 重新启用、风格说明、行为不变说明、明确未改项、门禁真实输出、偏差、未校准估算。
- 写后范围闸门:`added` 恰为 `09-57-SUMMARY.md`;0 次提交;未运行游戏 / 浏览器 / dev server / `pnpm install`。
</acceptance_criteria>
<done>写前范围闸门与哈希闸门通过(只有 3 个目标文件变化);`09-57-SUMMARY.md` 已写入并覆盖文件清单、测试数量、错误码映射、风格说明、行为不变说明、明确未改项、门禁结果、偏差与未校准估算;写后范围闸门通过;0 次提交。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 动画二进制 → 解析器 | `.animate` 文件是不可信输入;`parse.ts` 内校验,失败只记日志并返回 `null` |
| 解析器 → 日志系统 | 失败原因编码为 82–96 的固定消息;调用点只传原因标签 / 索引,不把任何具体值或文件内容塞进参数 |
| logger.json 码段 → 全仓调用点 | 82–96 的重新划分会改变码段含义;必须与 `parse.ts` / 测试同步,否则会命中 `logger.error(16)` 兜底 |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|----------|----------|-------------|-----------------|
| T-57-01 | Tampering | `parse.ts` 校验条件 | high | mitigate | 本计划只改 logger 实参;Task 3 / Task 5 门禁断言 3 处 `try`、无 `throw` / `finally`、可空签名、可选字段 `!== undefined`、`isRecord` 的 `value !== null` 与 `validateMeta` 嵌套不变 |
| T-57-02 | Tampering | `logger.json` 码段 | high | mitigate | Task 2 / Task 6 用 Task 1 快照深比较:`1..81`、`2001..2008` 与整个 `warn` 段(含 `213` / `1001`)逐字不变;82–96 十五条消息逐字比对计划表、两两不同、禁止 `$1`-only |
| T-57-03 | Information Disclosure | `parse.ts` 日志参数 | medium | mitigate | 用户规则:诊断只传原因 + 索引;Task 3 / Task 5 的平衡括号门禁断言每个实参只能是 `.toString()` 索引或允许的原因标签,从而排除 `String(value)`、`.message`、尺寸 / 坐标 / 图像维度与任何具体值 |
| T-57-04 | Denial of Service | 资源释放 | medium | mitigate | 保留「位图越界先 `image.close()` 再记日志」「纹理创建失败先 `image.close()`」;无绑定 catch 不吞异常之外的额外分支 |
| T-57-05 | Tampering | 注释 / jsDoc 误改 | medium | mitigate | 不修改 09-56 的 jsDoc / 注释 / region / 类级 jsDoc / 单画布;Task 5 断言 3 组 region 与行为不变量;不得修改 `animater.ts` |
| T-57-SC | Tampering | 依赖安装 | high | mitigate | 不新增任何依赖、不执行 `pnpm install`、不访问 registry、不改锁文件 |
</threat_model>
<verification>
- **logger 表**:`logger.json` error 82–96 十五条具体消息逐字匹配计划表、两两不同、非 `$1`-only;`1..81` / `2001..2008` / `warn`(含 `213` / `1001`)与 Task 1 快照逐字一致;无新增 `1000+`。
- **logger 调用点**:`parse.ts` 每个 `logger.error` ≤3 参数;实参只有 `.toString()` 索引或允许的小写连字符原因标签;无 `'-'` / 值形式 `String(value)`(不含 `.toString()`)/ `.message` / actual / expected / 尺寸 / 坐标 / 图像维度值;82–96 全部有调用点。
- **行为不变量**:3 组 region、3 处 `try`、无 `throw` / `finally`、可空签名、可选字段 `!== undefined`、`isRecord` 的 `value !== null`、`new Blob` 在 `try` 外、位图越界先 close、纹理失败先 close、两处无绑定 `catch {`、95 号守卫 compact 文本精确。
- **参数顺序 / close 顺序(机器校验)**:纹理失败路径 compact `image.close();logger.error(96,'texture-failed');` 精确存在(独立于越界 `image.close();logger.error(89,` gate);92 为 `logger.error(92,frameIndex.toString(),objectIndex.toString(),`、94 为 `logger.error(94,frameIndex.toString(),i.toString(),`(帧索引在前、对象/音效索引在后、reason 最后);测试侧至少各有一个 92 / 94 用例断言 `calls[0][1]` / `calls[0][2]` / `calls[0][3]`。
- **测试**:`parse.test.ts` 只覆盖 82–96、注释同步、`ERROR_PARAM_COUNTS` 与 arity 断言、`catch{` 与 95 号守卫、新增无值实参断言、不得对 92–95 作缺失断言(92–96 均为合法码)、旧 `[9]` / `[10]` 尺寸断言已删除;恰 70 用例;targeted vitest 70 passed。
- **格式 / lint / 类型**:prettier `--check`、eslint、CRLF / BOM / tab 对 3 个改动文件通过;`vue-tsc --version` 哨兵通过,`--noEmit --incremental false` 过滤 `packages[\\/]render-anim` 诊断 0 行(**必须 `--incremental false`;被拒即失败,不回退**);仓库根目录无 `*.tsbuildinfo`、git status 无 `tsbuildinfo`;SUMMARY 记录真实结果。
- **范围 / 哈希**:Task 5 前后无新增状态条目(含无 `*.tsbuildinfo`);Task 6 写后仅新增 `09-57-SUMMARY.md`;Task 6 哈希闸门排除 `.planning/phases/09-minimum-browser-runnable/09-57-PLAN.md` 后比较 8 条基线(完整仓库相对路径),只有 3 个目标文件变化。
- **明确不做**:不运行游戏 / 浏览器 / dev server / `pnpm install`;不做真实 WebP 素材与像素 E2E;不改 09-56 jsDoc / 注释 / 单画布;不修改 `animater.ts` / `types.ts` / `index.ts` / `package.json`;不执行 git 写命令,0 次提交。
</verification>
<success_criteria>
- [ ] Task 0 已向用户完整汇报 82–96 表、调用点参数、行为不变量、保留 09-56 成果、测试更新预期(含 70 用例与 arity 映射)、门禁形态与影响范围,并等待用户针对本计划回复「可以执行」后才继续。
- [ ] `logger.json` error 重写为 82–96 的 15 条具体消息(占位 1/0/0/1/1/1/2/1/0/2/3/1/3/1/1,两两不同、无泛化消息);`1..81`、`2001..2008` 与整个 `warn` 段(含 `213` / `1001`)逐字不变;无新增 `1000+`。
- [ ] `parse.ts` 每个 `logger.error` ≤3 参数,实参只有索引 `.toString()` 或允许的原因标签;无 `'-'` / 值形式 `String(value)`(不含 `.toString()`)/ `.message` / 任何具体值;`validateBitmapBounds` 中 `image.close()` 在 `logger.error(89, ...)` 之前且宽高仍在 close 前读取;纹理失败路径 compact `image.close();logger.error(96,'texture-failed');` 精确存在;92 为 `frameIndex.toString(), objectIndex.toString(), reason`、94 为 `frameIndex.toString(), i.toString(), reason` 顺序(帧索引在前、对象/音效索引在后、reason 最后)。
- [ ] `parse.ts` 行为不变量全部保持:3 处 `try`、无 `throw` / `finally`、可空签名、可选字段 / `isRecord` 判断、`new Blob` 在 `try` 外、位图越界先 close、纹理失败先 close、无绑定 catch、95 号守卫。
- [ ] 09-56 的 jsDoc / 行内注释 / 3 组 region / 类级 jsDoc / 单画布实现逐字保留;未修改 `animater.ts` / `types.ts` / `index.ts` / `package.json`。
- [ ] `parse.test.ts` 期望码、注释、`ERROR_PARAM_COUNTS`、arity 断言、`catch{`、95 号守卫、无值实参断言全部同步;至少一个 92 与一个 94 用例断言 `calls[0][1]` / `calls[0][2]` / `calls[0][3]` 为帧索引 / 对象或音效索引 / reason;不对 92–95 作缺失断言(92–96 均为合法码);旧尺寸断言已删除;恰 70 用例且每个 `it` 有注释。
- [ ] targeted vitest 70 passed;prettier / eslint / CRLF / BOM / 过滤 vue-tsc(`--incremental false`,被拒即失败、不回退)全部通过;无 `*.tsbuildinfo`。
- [ ] 只写 4 个 `files_modified` 路径;0 次提交;SUMMARY 覆盖文件清单、映射、测试数量、风格说明、行为不变说明、明确未改项、门禁结果与偏差。
</success_criteria>
<output>
Create `.planning/phases/09-minimum-browser-runnable/09-57-SUMMARY.md` when done
</output>
@@ -0,0 +1,149 @@
---
phase: 09-minimum-browser-runnable
plan: 57
subsystem: render-anim
tags:
- render-anim
- animation
- logger
- error-codes
- low-cardinality
- vitest
requires:
- 09-56 parseRenderAnimation parser diagnostics with logger.error 82..91 and single-canvas animater
provides:
- parse.ts logger.error call sites narrowed to reason label plus matching index
- logger.json error codes 82..96 with specific messages
- parse.test.ts expected codes, arity map and no-value static guard
affects:
- packages/render-anim/src/parse.ts
- packages/render-anim/src/__test__/parse.test.ts
- packages/common/src/logger.json
actuals:
tokens: 15000
tasks: 7
commits: 0
tech-stack:
patterns:
- logger.error only receives a kebab-case reason label and/or a numeric index via toString()
- at most three parameters per logger.error call, no concrete values
- logger.json error 82..96 with $n arity 1/0/0/1/1/1/2/1/0/2/3/1/3/1/1
key-files:
modified:
- packages/render-anim/src/parse.ts
- packages/render-anim/src/__test__/parse.test.ts
- packages/common/src/logger.json
- .planning/phases/09-minimum-browser-runnable/09-57-SUMMARY.md
key-decisions:
- parser diagnostics carry only a reason label plus the matching index; concrete values are dropped
- 92 and 94 pass frameIndex first, object/sound index second, reason last; $1 frame, $2 item index, $3 reason
- bitmap out-of-bounds and texture failures close the image before logging
- the two catch blocks are unbound (catch { ... }) and the old reason variable is removed
- 09-56 jsDoc, inline comments, 3 regions, class-level jsDoc and the single-canvas animater stay untouched
patterns-established:
- multi-line logger.error 92..96 calls keep one argument per line to satisfy printWidth 80
- the no-value static guard extracts balanced-paren arguments inline in the existing static-guard it
duration: 约 15 分钟
completed: 2026-11-09T21:25:00+08:00
status: complete
---
# Phase 09 Plan 57: 动画解析器 logger 去参数化 Summary
把 `@motajs/render-anim` 的 `parse.ts` 解析器诊断从「大量具体值」收紧为「错误原因 + 对应索引」,并把 `logger.json` 的 error 段重写为 82–96 共 15 条具体消息。
## 本计划范围
`files_modified` 共 4 个路径:
- `packages/render-anim/src/parse.ts`
- `packages/render-anim/src/__test__/parse.test.ts`
- `packages/common/src/logger.json`
- `.planning/phases/09-minimum-browser-runnable/09-57-SUMMARY.md`
本计划编号为 09-57(09-01..09-56 已占用),波次 6,`depends_on: 09-56`。只写上述 3 个目标文件与本 SUMMARY;`animater.ts` / `types.ts` / `index.ts` / `package.json` 只验证不改(哈希基线一致);不跑游戏 / 浏览器 / dev server / `pnpm install`;不执行 git 写命令,**0 次提交**。Task 0 汇报关卡已由用户「可以执行」通过,本摘要记录 Task 1–6 的执行结果。
## 文件清单
| 文件 | 变更 |
|------|------|
| `packages/render-anim/src/parse.ts` | 39 处 `logger.error` 收敛为 82–96 的「原因 + 索引」,至多 3 参数;两个 catch 改为无绑定并删除 `reason` |
| `packages/render-anim/src/__test__/parse.test.ts` | 期望码 82–96、注释同步、`ERROR_PARAM_COUNTS` 与 arity 断言、无值实参静态闸门、92/94 参数顺序断言;仍 70 用例 |
| `packages/common/src/logger.json` | error 82–96 共 15 条具体消息;`1..81` / `2001..2008` / `warn`(含 213 / 1001)逐字未变 |
| `.planning/phases/09-minimum-browser-runnable/09-57-SUMMARY.md` | 本摘要 |
## 错误码映射(09-56 → 09-57)
09-56 的 82–91 每条携带大量具体值(buffer 长度、签名、尺寸、x/y/w/h、图像宽高、JSON 大小、异常 message 等);09-57 把它们重新划分为 82–96 的「具体上下文 + reason: '$n' / 索引」,每条消息两两不同:
| 新码 | 触发位置(只传原因 / 索引) |
|------|------------------------------|
| 82 | 头部过短 `buffer-too-short` / 长度不符 `length-mismatch` |
| 83 | 签名非法(0 参) |
| 84 | 版本不支持(0 参) |
| 85 | sprite 表非法 `invalid-count` / `table-overflow` |
| 86 | 单个 sprite 宽或高 < 1(索引) |
| 87 | 位图列表非法 `not-array` / `count-mismatch` |
| 88 | 位图项非法(索引 + `not-object` / `invalid-x` / `invalid-y` / `invalid-width` / `invalid-height`) |
| 89 | 解码后位图越界(索引) |
| 90 | 帧列表非法(0 参) |
| 91 | 帧项非法(帧索引 + `not-object` / `objects-not-array` / `sound-not-array`) |
| 92 | 对象非法(帧索引 + 对象索引 + 原因) |
| 93 | 标量字段非法 `invalid-ratio` / `invalid-blend` |
| 94 | 音效非法(帧索引 + 音效索引 + 原因) |
| 95 | 元数据非法 `invalid-json` / `not-object` |
| 96 | 图像失败 `decode-failed` / `texture-failed` |
- 92–95 从 09-56 的「已删除」重新作为合法码加入(92 对象 / 93 标量 / 94 音效 / 95 元数据),96 为图像失败。
- 92 / 94 固定帧索引在前、对象 / 音效索引在后、原因最后(消息 `$1` 帧、`$2` 对象 / 音效索引、`$3` 原因)。
- `1..81`、`2001..2008` 与整个 `warn` 段(含并发 `213` 与既有 `1001`)逐字未变;未新增任何 `1000+` 码。
## 测试数量
- `parse.test.ts`:70 个用例(改写前后均为 70,未新增 / 删除)。
- `ERROR_PARAM_COUNTS` 更新为 `82:1, 83:0, 84:0, 85:1, 86:1, 87:1, 88:2, 89:1, 90:0, 91:2, 92:3, 93:1, 94:3, 95:1, 96:1`。
- `expectFailure` 保留首参错误码断言,并断言 `loggerMock.error.mock.calls[0].length === ERROR_PARAM_COUNTS[code] + 1`。
- 至少一个 92 用例与一个 94 用例分别断言 `calls[0][1]` / `calls[0][2]` / `calls[0][3]` 为帧索引 / 对象或音效索引 / 原因。
## 风格说明
新 82–96 消息与 `logger.json` 既有风格一致——「具体上下文 + `reason: '$n'` / 索引,无具体值」,参照 warn 44、error 63、warn 179。反例 `Cannot parse animation: $1.` 这类泛化消息不存在(静态门禁逐字比对计划表并检查两两不同)。
## 行为不变说明
- 两个 catch 改为无绑定 `catch { ... }`,删除 `reason` 局部变量;解码失败只记 `decode-failed`,纹理失败只记 `texture-failed`。
- 位图越界仍先 `image.close()` 再记日志(新 89 号只传索引,旧 `'out-of-bounds'` 原因与尺寸断言已删除,改为断言索引 `'0'`)。
- 纹理创建失败仍先 `image.close()` 再记日志。
- `validateBitmapBounds` 仍在 `close()` 前读取 `image.width` / `image.height` 用于越界判定,只是不再写入日志。
- 校验逻辑、提前返回、`validateMeta` 嵌套、可选字段 `!== undefined`、`isRecord` 的 `value !== null`、`parseRenderAnimation` 可空签名、3 处窄 `try/catch`、无 `throw` / `finally`、`new Blob` 在 `try` 外全部保持。
## 明确未改项
- 09-56 的 jsDoc / 行内注释 / 3 组功能性 `#region` / 类级 jsDoc / 单画布实现逐字保留。
- 未修改 `animater.ts` / `types.ts` / `index.ts` / `package.json`(哈希基线一致)。
- 未新增 / 重命名任何公开、受保护、私有方法、字段或导出命名;测试未新增具名辅助函数(无值实参提取内联在既有静态闸门 `it` 内)。
## 门禁结果
- `node node_modules/vitest/vitest.mjs run packages/render-anim/src/__test__/parse.test.ts`:70 passed。
- `prettier --check`:`parse.ts` / `parse.test.ts` / `logger.json` 三个改动文件全部通过。
- `eslint`:`parse.ts` / `parse.test.ts` 无 error / warning。
- CRLF / 无 BOM / 无 tab:3 个改动文件全部通过。
- `vue-tsc --version` 哨兵通过(Version 6.0.3);`--noEmit --incremental false` 过滤 `packages[\\/]render-anim` 诊断为 0 行(全仓其它包既有诊断导致进程退出码 2,不参与判定);仓库根目录无 `*.tsbuildinfo`,`git status` 无 `tsbuildinfo` 条目。
- 综合静态门禁:`parse.ts` 82–96 全在;39 处 `logger.error` 均 ≤3 参数,实参只有 `.toString()` 索引或允许的原因标签;无 `'-'` / 值形式 `String(...)` / `.message` / actual / expected;3 组 region、3 处 try、无 throw / finally、可空签名、可选字段与 `isRecord` 不变量、`new Blob` 在 try 外、越界先 close、纹理失败先 close、92/94 帧索引在前的 compact 断言全部通过。
- `logger.json` 82–96 与计划表逐字一致、占位符数量 1/0/0/1/1/1/2/1/0/2/3/1/3/1/1、两两不同、非泛化;`1..81` / `2001..2008` / warn 与 Task 1 快照逐字一致。
- 哈希闸门:排除 `09-57-PLAN.md` 后比较 8 条基线,恰有 3 个目标文件(`parse.ts` / `parse.test.ts` / `logger.json`)变化,其余 5 个只读文件不变。
- 写后范围闸门:`git status` 仅新增本 `09-57-SUMMARY.md`,无其它新增 / 删除条目。
## 偏差
1. **无值实参静态闸门的 82–96 存在性断言改写(内联、范围内)**:初始以 `source.includes('logger.error(' + code)` 断言 82–96 全在,但 92 / 94 的调用因超过 printWidth 采用多行 `logger.error(\n 92,` 形式,字面量 `logger.error(92` 不连续,导致该断言误判失败。已改为空白容忍的正则 `new RegExp('logger\\.error\\(\\s*' + code + '\\b')` 判定,语义等价且覆盖多行调用。这是本计划自身测试断言的实现修正,不改变 `parse.ts` 行为与计划意图。
2. **执行方式**:源码 / 测试 / logger 的批量改写由执行子代理以确定性脚本内联完成(每次替换均断言恰好匹配一处),未偏离 `files_modified` 范围。除此之外计划命令均可按原样执行,未发现计划命令缺陷,未触发行为 / 代码歧义。
## 未校准估算
`confidence: low`、`tokens: 80000`(7 个任务 / 80k 仅为 advisory 建议值,不作为拆分或阻断依据)。`actuals.tokens` 为粗略 chars/4 估算,非精确计量。
## 可见跳过
spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip)。