2026-07-01 MEXP09 视觉上下文

用户目标

以 coder2@mindraw 身份领取统一台账 P-20260701-mexp09-frame-visual-context 的 MD-MEXP09-01，完成 Mindraw 侧 target Frame visual snapshot / visual context contract。边界：不做 H8/formal release，不重打 DMG，不修 Stitch，不做 m4c consumer，不领取 M4C-* / PM-* / H*。

核心事实

• Frame link / live frame context 的 AI/App API 读取语义继续固定为 frame-only。
• UI 任务主上下文必须是目标 Frame visual snapshot；OCR-only 不可作为完成路径。
• 本轮实现采用受控 SVG visual snapshot：在 mindrawGetLiveFrameContext() 的 target Frame 过滤之后，仅用目标 Frame 内元素和内部图片 dataURL 生成 SVG，避免整图截图、整份 .mindraw promptable read 或 document visual scan。
• 非 Frame target / missing target 仍分别返回 TARGET_NOT_FRAME / TARGET_NOT_FOUND。

变更快照

• src/lib/mindrawAppReadApi.ts
• 新增 visualContext / visualScopeAudit DTO。
• visualContext.kind="target-frame-visual-snapshot"，snapshot 包含 mimeType="image/svg+xml"、尺寸、byte size、hash 和 dataURL。
• DTO 明确 ocrOnly=false、ocrTextIsNotFullVisualContext=true、ocrOnlyFallbackAllowed=false、fallbackToDocumentVisualScan=false、outsideFramePixelsExcluded=true。
• src/lib/mindrawAppReadApi.test.ts
• fixture 增加 Frame 外 pixel sentinel #ff00ff。
• 断言 decoded SVG snapshot 包含目标 Frame 内 text / image，不包含 Frame 外文本、Frame 外 image dataURL 或 pixel sentinel。
• src/lib/mindrawAppApiTransport.test.ts
• 验证 JSON-RPC transport 透传 visualContext / visualScopeAudit。
• 新增 QA：
• 02-P/qa/mindraw-mexp09-frame-visual-context-check.md
• 02-P/qa/mindraw-mexp09-frame-visual-context-check.json
• 同步 02-P/plan-progress.markdown、INDEX.md、CODEGRAPH.md、CHANGELOG.md。

验证结果

• npm test -- --run src/lib/mindrawAppReadApi.test.ts src/lib/mindrawAppApiTransport.test.ts：PASS，2 files / 15 tests。
• npm run build：PASS。保留既有字体 URL、Tauri dialog import、chunk size 警告。
• git diff --check：PASS。

未决问题

• 首版 visual snapshot 是 Mindraw scene 元素生成的受控 SVG，不是 native compositor bitmap capture。复杂 Excalidraw 渲染保真需要 m4c consumer / PM Gate 继续评估。
• PM-MEXP09-GATE 仍由 PM 复核；本轮只允许 PM 派发或恢复 M4C-MEXP09-01 visual context consumer retry。

后续建议

• PM 派发 / 恢复 m4c consumer 时，应要求 m4c 只在 visualContext.snapshot 可用、ocrOnly=false、ocrOnlyFallbackAllowed=false、documentVisualFallbackUsed=false、outsideFramePixelsExcluded=true 时进入 UI 视觉任务。
• 若 m4c 或真实用户 Frame 发现 SVG 与真实画布显示存在关键偏差，再拆新的 MD-* 做 native crop / compositor capture 评估。