diff --git a/docs/github-tracking/issue-98-startup-visible-ready.md b/docs/github-tracking/issue-98-startup-visible-ready.md new file mode 100644 index 00000000..40e357a1 --- /dev/null +++ b/docs/github-tracking/issue-98-startup-visible-ready.md @@ -0,0 +1,74 @@ +## 现象 / Symptom + +Windows 冷启动路径里,`visible` 与 `ready` 目前是脱钩的:主窗口可以先被用户看见,但 global hotkey / runtime lifecycle 还在后台异步安装。 + +这不是单纯的 UI 小闪烁,而是 startup lifecycle ownership 不统一: + +- `main` 在配置层默认 `visible:false` +- backend 负责 `show_main_window()` / tray reopen / single-instance focus +- frontend `App.tsx` 又在 mount 后主动 `currentWindow.show()` +- Windows 路径下 `gate` 初始值直接是 `ready` + +### 证据 / Evidence + +- `openless-all/app/src-tauri/tauri.conf.json:17-30` + - `main.visible = false` +- `openless-all/app/src-tauri/src/lib.rs:314-356` + - backend 明确拥有 `show_main_window()` / `hide_main_window()` 生命周期入口 +- `openless-all/app/src-tauri/src/lib.rs:158-163` + - hotkey listener 与 QA hotkey listener 在 setup 后异步启动 +- `openless-all/app/src/App.tsx:23-52` + - Windows 路径初始化时直接 `gate='ready'` + - mount 后又在 `requestAnimationFrame` 里调用 `currentWindow.show()` +- [2026-05-02-platform-lifecycle-audit.md](/D:/Users/cooper/Practice-Project/202604/openless/docs/2026-05-02-platform-lifecycle-audit.md) + - 审计已将该问题归类为 startup lifecycle ownership 偏差 + +### 5 Whys / 根因分析 + +1. 为什么用户会看到一个看似 ready 的窗口,但热键/运行态未必已经 ready? + - 因为窗口可见时机和 runtime readiness 时机不是一个 source of truth。 +2. 为什么这两个时机分离了? + - 因为 backend 和 frontend 同时持有 `main` visibility 的一部分控制权。 +3. 为什么 Windows 上更明显? + - 因为 Windows 启动路径跳过了 macOS 那种明确的 permission gate / startup shell,正式 UI 更早暴露。 +4. 为什么这偏离了 macOS 的原始设计意图? + - 原始意图是“用户看见主窗口时,它已经进入可用或可解释的阶段”;Windows 当前更像“窗口先到,能力后到”。 +5. 为什么之前没被系统性识别? + - 现有 smoke 主要验证“进程活着 + 稍后日志出现 hotkey installed”,没有验证“first visible frame == operationally ready”。 + +### 平台边界 / Platform Scope + +- 直接症状范围:当前主要在 Windows 冷启动观察到。 +- 问题层面:startup lifecycle ownership、window visibility contract、runtime readiness contract。 +- 全平台风险判断:这是全平台架构层风险,但 Windows 因跳过 startup gate、前端主动 show,最先表现为真实用户问题。 + +### 认领 / Ownership + +- owner intent:`@Cooper-X-Oak` +- 对应 draft PR:待创建 + +### 当前状态 / Current status + +- startup lifecycle 主线修复已生效 +- 最新测试入口改为 frontend-managed first show,不再用 backend immediate show 污染结果 +- 人工冷启动体验反馈:几乎没有问题,人眼很难分辨 +- 当前建议:保留 draft,继续观察 first-paint / startup latency,而不是继续扩大主修补丁 + +## 影响 / Impact + +- 用户会把尚未 ready 的窗口误判为已经 ready +- 会放大“热键没反应 / 运行态未安装”的首屏困惑 +- 让后续任何 Windows 启动问题更难分辨是 UI 问题、hotkey 问题,还是 lifecycle contract 问题 + +## 建议接受标准 / Proposed Acceptance Criteria + +- [ ] `main` 窗口的首次可见时机只由一个 owner 控制 +- [ ] first visible frame 与 runtime readiness 的关系被明确定义并可验证 +- [ ] Windows 冷启动下,用户首次看到主窗口时,至少处于明确的 `startup` 或 `ready` 状态,而不是 ambiguous ready +- [ ] 增加一条启动 smoke:覆盖 `visible`、`hotkey installed`、`first usable state` 的先后顺序 + +## TODO / 不确定项 + +- 是否应把 `main` visibility 完全收回 backend,frontend 只负责内容 gate +- 是否要把现有 `issue #143` 的 first-paint 问题作为本 issue 的下游视觉子问题处理,还是继续分票并行跟踪 +建议 issue 标题:`[tauri][windows] 冷启动时 visible 与 ready 脱钩` diff --git a/docs/github-tracking/pr-145-cold-start-first-paint.md b/docs/github-tracking/pr-145-cold-start-first-paint.md new file mode 100644 index 00000000..27bfc582 --- /dev/null +++ b/docs/github-tracking/pr-145-cold-start-first-paint.md @@ -0,0 +1,40 @@ +## 摘要 + +Closes #98 +References #143 + +这个 draft PR 继续承接 Windows cold-start first paint 生命周期问题,但状态已经从“纯问题定义”推进到“主线修复已见效、继续观察”。 + +本轮最新结论: + +- 之前可见的一闪,主要与测试入口使用 backend immediate show 有关 +- 冷启动脚本改成 frontend-managed first show 后,首屏体验明显更顺 +- 实测主观体验是“几乎没有问题,人眼很难分辨” +- 但为了避免把 startup latency 优化和 lifecycle contract 修复混成一团,这条 PR 仍保持 draft +- `#143` 更适合作为已收敛的 first-paint 症状票;当前主线 closure 由 `#98` 承接 + +## 修复 / 新增 / 改进 + +- 保持 draft 角色,继续跟踪 `created -> shown -> first stable paint -> ready` +- 记录测试入口从 backend immediate show 切换到 frontend-managed first show 的影响 +- 作为后续 cold-start visual smoke 与更细粒度 startup latency 优化的承接入口 + +## 兼容 + +- 不包含:主窗口圆角 / 外框 / 其他视觉适配 +- 对现有用户 / 本地环境 / 构建流程的影响:继续只聚焦 startup lifecycle 主线 + +## 测试计划 + +- [x] 命令:`powershell -ExecutionPolicy Bypass -File openless-all/app/scripts/windows-cold-start.ps1 -PreferDebug -ShowMain` +- [x] 结果:能够走 frontend-managed first show +- [x] 证据路径:本地命令输出 + +- [x] 命令:3 秒与 8 秒冷启动截图对比 +- [x] 结果:3 秒可见 startup shell;修正测试入口后正式首屏体验显著改善 +- [x] 证据路径:`artifacts-cold-start-screenshot.png`、`artifacts-cold-start-screenshot-8s.png`、`artifacts-cold-start-screenshot-front-managed.png` + +- [x] 命令:人工主观回归 +- [x] 结果:冷启动过程“几乎没有问题,至少人眼很难分辨” +- [x] 证据路径:当前线程回归记录 +关联 issue 建议标题:`[ui][windows] 冷启动前几秒出现 UI flash 和 layout drift`