macOS: WKWebView 页面 JS 定时器在窗口遮挡时疑似被暂停（AppNap）——常驻监测类应用需要反制

[turinglambdaai]

场景

gPTP Studio 是监测类工具：前端靠 setInterval 周期上报页面状态 + canvas 像素采样做 agent 验证。实测（macOS 15 arm64，WKWebView 窗口被其他窗口完全遮挡时）：

• 页面加载时的一次性 JS 全部正常执行（fetch API 正常、cookie 正常）
• setInterval 的后续 tick 长时间不触发（>30s），窗口置前后恢复
• 后端 SSE 持续在推（curl 可见事件流），说明只是 WebKit 侧冻结

影响

后台被遮挡时 UI 与后端状态脱节；监测类工具的 "后台也在看" 预期不成立。

建议反制

open-window 阶段对进程做一次 App Nap 豁免：

[[NSProcessInfo processInfo] beginActivityWithOptions:
    NSProcessInfoActivityUserInitiated | NSProcessInfoActivityIdleSystemSleep
    reason:"monitoring UI"];

以及/或 WKWebView 配置 preferences.windowOcclusionDetection = NO（对应 WKPreferences 私有/平台差异需确认），macOS 上经 objc FFI 可达。

附注

• 文档化也行："遮挡窗口时前端定时器会被暂停" 写进 honest gaps，避免使用方误判
• 复现项目：turinglambdaai/gptp-studio（api/dev/verify 端点即为此设计的验证钩子）