# MEXP09B 像素 payload

## 用户目标

以 `coder2@mindraw` 身份领取统一台账 `P-20260701-mexp09b-target-frame-pixel-payload` 的 `MD-MEXP09B-01`，补齐 Mindraw 侧 target Frame 像素输入能力：当用户给 agent 一个 `mindraw://localhost?documentId=...&elementId=<frameId>` Frame link，目标 Frame 内放真实截图时，Mindraw App API 必须能提供只包含目标 Frame 的真实 PNG / bitmap payload，使后续 m4c / vision-capable agent 能像收到目标 Frame PNG 一样看图。

## 已完成事项

- 在 Mindraw read API 新增 `targetFramePixelPayload="read"` capability。
- 新增 JSON-RPC 方法 `mindraw.app.get_target_frame_pixel_payload`。
- 新增 `mindrawGetTargetFramePixelPayload()`，输入 `documentId`、可选 `packagePath`、`sourceFrameId` 或 `elementId`。
- 输出 target Frame-only PNG payload：MIME、尺寸、byteLength、SHA256、Frame bounds、生成时间、`pixelsIncluded=true`、`bytesIncluded=true`。
- 输出 `pixelScopeAudit`：targetFrameOnly、source snapshot hash、rasterizer、outside text / image / pixel exclusion、no OCR、no document visual fallback。
- 如果不能生成 PNG 像素，返回 `TARGET_FRAME_PIXEL_PAYLOAD_REQUIRED`；非 Frame 返回 `TARGET_NOT_FRAME`；缺失 target 返回 `TARGET_NOT_FOUND`。
- 更新 runtime discovery：Rust transport capability 文件和 supported methods 均声明 `mindraw.app.get_target_frame_pixel_payload` 与 `targetFramePixelPayload="read"`。
- 新增 QA 报告：`02-P/qa/mindraw-mexp09b-target-frame-pixel-payload-check.md` 和 `.json`。
- 回写 `02-P/plan-progress.markdown` 的 `MD-MEXP09B-01` 与 Progress Log。
- 同步 `CHANGELOG.md`、`CODEGRAPH.md`、`INDEX.md`。

## 核心事实 / 变更快照

- 变更对象：Mindraw App API Frame visual read contract。
- 事实来源：
  - `src/lib/mindrawAppReadApi.ts`
  - `src/lib/mindrawAppApiTransport.ts`
  - `src-tauri/src/app_api_transport.rs`
  - `02-P/qa/mindraw-mexp09b-target-frame-pixel-payload-check.md`
- 变更前：
  - MEXP09 只有 `visualContext.snapshot` SVG metadata / dataURL。
  - Gate package 仍出现 `bytesIncluded=false`、`pixelsIncluded=false`、`auxiliaryOcr.available=false`。
  - 不能支撑“vision-capable agent 已收到目标 Frame PNG 像素”。
- 变更后：
  - Capability：`targetFramePixelPayload="read"`。
  - JSON-RPC：`mindraw.app.get_target_frame_pixel_payload`。
  - Success DTO：`payload.kind="target-frame-png-pixel-payload"`、`mimeType="image/png"`、`pixelsIncluded=true`、`bytesIncluded=true`、`width`、`height`、`byteLength`、`sha256`、`dataURL`、`pixelScopeAudit`。
  - No-Go：`TARGET_FRAME_PIXEL_PAYLOAD_REQUIRED`，不得退回 OCR-only、文本摘要、SVG metadata only 或 document visual scan。
- 范围边界：
  - 本轮不改 m4c consumer。
  - 不改 `~/plugins/mindraw`。
  - 不打 DMG，不安装或覆盖 `/Applications/Mindraw.app`。
  - 长期 QA / 台账不保存 raw PNG bytes。
- 验证证据：
  - `npm test -- --run src/lib/mindrawAppReadApi.test.ts src/lib/mindrawAppApiTransport.test.ts` PASS，2 files / 19 tests。
  - `cargo test --manifest-path src-tauri/Cargo.toml app_api_transport` PASS，5 Rust tests。
  - `npm run build` PASS。
  - `git diff --check` PASS。

## 文件变更

- `src/lib/mindrawAppReadApi.ts`
- `src/lib/mindrawAppReadApi.test.ts`
- `src/lib/mindrawAppApiTransport.ts`
- `src/lib/mindrawAppApiTransport.test.ts`
- `src-tauri/src/app_api_transport.rs`
- `02-P/qa/mindraw-mexp09b-target-frame-pixel-payload-check.md`
- `02-P/qa/mindraw-mexp09b-target-frame-pixel-payload-check.json`
- `02-P/plan-progress.markdown`
- `CHANGELOG.md`
- `CODEGRAPH.md`
- `INDEX.md`

## 可复用命令 / Runbook

用途：复验 Mindraw MEXP09B target Frame pixel payload contract。

前置条件：在 `/Users/ar/Projects/ExcalidrawX`，源码包含 `MD-MEXP09B-01` 改动；无需启动 App、无需 DMG、无需 m4c。

设置命令：

```bash
cd /Users/ar/Projects/ExcalidrawX
npm test -- --run src/lib/mindrawAppReadApi.test.ts src/lib/mindrawAppApiTransport.test.ts
cargo test --manifest-path src-tauri/Cargo.toml app_api_transport
npm run build
node -e "JSON.parse(require('fs').readFileSync('02-P/qa/mindraw-mexp09b-target-frame-pixel-payload-check.json','utf8')); console.log('QA_JSON_OK')"
git diff --check
```

验证步骤：上述命令分别应显示 Vitest 2 files / 19 tests PASS、Rust 5 tests PASS、build PASS、`QA_JSON_OK`、`git diff --check` 无输出。

清理 / 恢复命令：无临时系统状态；本轮未启动 App、未安装 App、未创建 DMG。

搜索关键词：`MD-MEXP09B-01`、`targetFramePixelPayload`、`mindraw.app.get_target_frame_pixel_payload`、`TARGET_FRAME_PIXEL_PAYLOAD_REQUIRED`、`pixelsIncluded=true`、`bytesIncluded=true`。

## 未决问题

- m4c 仍需在 `M4C-MEXP09B-01` 中消费 PNG payload，并把像素输入交给 vision-capable agent / model。
- PM Gate 仍需用真实 Frame 内截图验证 agent 能描述 UI 细节，且 Frame 外 sentinel 不进入结果。
- 当前 PNG 是从 Mindraw controlled target Frame-only visual snapshot 经 browser canvas 栅格化，不是 OS compositor screenshot；复杂 Excalidraw 渲染 fidelity 仍应由后续 m4c consumer QA / PM Gate 覆盖。

## 后续建议

- PM 可派发 `M4C-MEXP09B-01`。
- 在 MEXP09B Gate 通过前，不恢复 MEXP09 value DMG 或 MEXP10 plugin Gate 的旧视觉价值口径。