Native macOS visual evidence

Native macOS visual evidence 是一套把原生 macOS 应用的 owner-facing 窗口截图当作可审计交付物的合同。它要求截图来自当前源码构建并运行的真实 .app，并且可以沿着 PID、bundle identifier、Accessibility role/title 语义和唯一 WindowServer window ID 回溯到目标窗口；PNG 只是证据载体，不是验收本身。这个 Topic 处理窗口身份、场景矩阵、fixture 隔离、外观覆盖、资产生命周期和 PR 证据索引，不处理 app bundle 如何构建、Keychain 如何开关、签名/公证或发布渠道，那些职责属于 macOS app Topic（topics/macos-app/TOPIC.md）。

应用内部的 cacheDisplay、PDF 或 bitmap preview、按标题猜窗口、合成 demo window、全屏截图再裁剪，均不能证明真实桌面窗口状态。它们可以作为历史排障材料，但不得混入当前正向矩阵。浏览器、Storybook 和 Web UI 使用自己的 visual-evidence 约定；本 Topic 只接受 WindowServer 中属于目标应用进程的窗口。

当 PR 改动菜单栏 popover、设置窗口、对话框、状态面板或其他 macOS owner-facing surface，且需要把外观或布局变化放进 Spec/PR 时，使用本 Topic。项目必须能提供 source-built .app、稳定的 Demo 入口和可检查的窗口语义；若只改 CLI、daemon、内部渲染器或网页，不应加载它。

默认只纳入 changed-surface matrix：每个条目写清 scene、目标窗口 role/title 语义、逻辑尺寸、数据 fixture 和支持的 appearance。项目声明支持 Light/Dark 时，两种外观都要覆盖；full-app 只有 release 或长期 Spec 明确要求时才加入。无窗口的菜单栏状态、系统桌面和其他进程不属于证据范围。

• 先建立严格的窗口身份链：从当前源码构建启动 isolated Demo，读取 PID 与 bundle identifier，再用 AX 语义筛选窗口，最后要求同一 PID 只得到一个可成像 WindowServer ID。只要缺失、歧义、尺寸错误或 identity 不一致，就让场景失败；禁止 title-only 猜测和跨进程拾取（projects/spotibind.md）。
• 每次运行使用固定且脱敏的 fixture，并将配置、数据、缓存、日志和 PNG 输出分离到 run root。网络、Keychain、登录、媒体和硬件动作要被关闭或模拟；清理只针对已验证 PID，不能用宽泛的进程名或桌面状态（assets/templates/native-macos-visual-evidence-contract.md）。
• 捕获命令保持单一：screencapture -x -l <window-id>。不要把 full-screen、窗口列表第一项、标题匹配或“截图后裁剪”当作 fallback；失败应阻断 PR 资产生成，而不是返回一张看似完整的图（assets/templates/native-macos-ui-capture-checklist.md）。
• 资产归属在下游项目：最终 PNG 放入 docs/specs/<topic>/assets/，文件名包含场景和 appearance，并在 PR 中记录窗口语义、logical size、fixture fingerprint、commit 和生成者。Topic package 只维护合同模板，避免把某个应用的视觉外观误当成通用素材。
• 本机真实 WindowServer 捕获必须由目标项目逐次授权并在受控用户会话中执行；CI 只验证 build、fixture isolation、probe 静态合同、PNG 基本属性和单元测试，不申请桌面权限，也不把 Linux 截图当成 macOS 证据。SpotiBind 的 shell/static gate 展示了这条边界（projects/spotibind.md）。
• review 时逐项核对 changed-surface matrix 是否覆盖了本次 owner-facing 变化，Light/Dark 是否与产品支持范围一致，错误场景是否保持 smoke-only，旧资产是否清楚标注为历史反例。macOS app Topic 仍负责 build/run、platform capability 和 packaging；本 Topic 只负责“这张图是否证明了那个窗口”。

• projects/spotibind.md 是混合样本：settings window 具备完整的 bundle/AX/WindowServer probe，可作为严格正向证据；menu-bar MenuBarExtra(.window) popover 当前只绑定 PID、bundle、WindowServer ID 和几何约束，缺少 AX role/title，因此保留为迁移输入，不能作为严格正向 surface。该 snapshot 的可见性为 private，只暴露仓库相对证据路径。
• projects/televy-backup.md 是迁移对照样本：较新的脚本已经开始绑定 PID 与具体窗口，但历史 UI snapshot 仍使用 PDF/bitmap caching、可见窗口枚举和宽泛匹配。它说明“能生成 PNG”不等于“能证明目标窗口”，后续项目任务应按本 Topic 的严格合同逐步迁移。
• docs/specs/native-macos-visual-evidence/ 保存长期 REQ/VER 合同；topics/native-macos-visual-evidence/assets/templates/ 保存项目可复制的 contract 与 checklist，不承诺一个适用于所有 app 的捕获脚本。

• 用应用内 bitmap 或 PDF 预览替代 WindowServer 截图，会把渲染器状态误认为真实窗口层级。修复方式是保留渲染预览为 debug-only，并补上同一 PID 的 AX 与 WindowServer identity probe。
• 只按标题或第一扇窗口匹配，会在菜单栏 popover、隐藏设置窗或多场景 Demo 中捕获错误 surface。修复方式是固定 role/title 语义、bundle identity、PID 和唯一 ID，并在歧义时 fail closed。
• 把全屏截图、桌面截图或裁剪后的图片当作窗口证据，会掩盖窗口尺寸、遮挡和外观问题。修复方式是只调用带明确 window ID 的 screencapture -x -l，输出失败就阻断场景。
• Demo 读取真实用户配置、Keychain 或网络服务，会使截图不可复现并带出敏感状态。修复方式是固定脱敏 fixture、隔离根目录和副作用开关，并把清理范围锁定到已验证 PID。
• 把所有窗口、错误状态和历史资产都塞入矩阵，会造成 PR 噪音并模糊改动范围。修复方式是只提交 changed owner-facing surfaces；错误场景做 smoke-only，旧图片仅作迁移反例。
• 在 CI 中申请真实桌面权限或把模拟窗口当作 macOS 证据，会让门禁既不安全也不可移植。修复方式是将真实捕获留给逐次授权的本机流程，CI 只跑静态合同、构建、fixture 和单元门禁。

• projects/spotibind.md
• projects/televy-backup.md
• data/topics/native-macos-visual-evidence.json
• topics/macos-app/TOPIC.md
• docs/specs/native-macos-visual-evidence/SPEC.md
• docs/specs/native-macos-visual-evidence/IMPLEMENTATION.md
• docs/specs/native-macos-visual-evidence/HISTORY.md
• topics/native-macos-visual-evidence/assets/templates/native-macos-visual-evidence-contract.md
• topics/native-macos-visual-evidence/assets/templates/native-macos-ui-capture-checklist.md