feat: add Minecraft launch transition animation (cover/logo phases)

README.md

@@ -1,4 +1,3 @@
-
 <div align="center">
   <img src="./apps/app/icons/128x128.png" width="128" height="128" alt="Starlight Launcher Logo" />
   <h1>Starlight Launcher</h1>
@@ -73,3 +72,310 @@ Starlight Launcher 的进步离不开社区的反馈与贡献。
 参与社区和贡献代码前，也请先阅读[行为准则 (CODE_OF_CONDUCT.md)](CODE_OF_CONDUCT.md)。
 
 ---
+
+# 🌟 启动过渡动画（本次改动）
+
+> 本节记录「游戏启动时窗口平滑过渡」功能的完整实现，供后续维护、移植与继续开发使用。
+> **生效平台：仅 Windows**（其他平台为空实现，行为与改动前一致）。
+
+## 一、功能目标
+
+消除「点击启动 → MC 游戏窗口突然弹出 → 把启动器挤走」的割裂感，用一套完整的窗口动画把这段过渡变得顺滑。
+
+启动一个实例后，会经历以下动画序列：
+
+```
+点击「启动实例」
+      ↓
+① 纯色遮罩出现（启动器主题色，无图）—— 立刻盖住后续所有抖动
+      ↓
+② 启动器放大到全屏（0.4s 动画，全程置顶 + 聚焦）
+      ↓
+③ 全屏后，遮罩上渐显 Mojang SVG logo（0.5s）
+      ↓
+④ 等待 MC 游戏窗口出现（最多 60 秒，期间遮罩一直盖着）
+      ↓
+⑤ 缩小前：遮罩背景色 → Mojang 红 (#db1f29) + 渐隐 logo（0.5s）
+      ↓
+⑥ 启动器缩放到 MC 窗口的位置和大小（0.4s）
+      ↓
+⑦ 等待 1 秒（让游戏稳定，遮罩仍在）
+      ↓
+⑧ 整体淡出透明（0.5s）→ 聚焦游戏窗口 → 启动器最小化
+      ↓
+进入轻量模式（隐藏到系统托盘）
+```
+
+**设计要点**：
+
+- **遮罩提前**：纯色遮罩在放大**之前**就出现，所以放大和缩小时的窗口抖动都被盖住，用户看不到。
+- **缩放与淡出串行**：先缩放完成，再淡出，不再同步进行（早期版本两者同步，观感差）。
+- **动画放慢**：缩放 0.4s（早期 0.2s 太快），淡出 0.5s。
+- **修复重开透明**：最小化后重置窗口透明度，并且恢复时用轻量模式**重建全新窗口**，彻底杜绝「重新打开启动器一片透明、需要点击/拖动才恢复」的问题。
+- **轻量模式接管**：过渡动画结束后，统一进入轻量模式（隐藏到托盘），不再分别判断用户的「轻量模式 / 启动后隐藏」设置，避免冲突。
+
+## 二、改动文件总览
+
+| 文件 | 改动类型 | 说明 |
+|---|---|---|
+| `apps/app/src/mc_transition.rs` | **新建** | 核心模块（约 470 行），负责窗口查找、四段动画、遮罩/淡出协调 |
+| `apps/app/src/main.rs` | 修改 | 声明模块 + 注册 4 个 Tauri 命令 |
+| `apps/app/src/lightweight_mode.rs` | 修改 | `launched` 分支接入过渡，并统一进轻量模式 |
+| `apps/app/Cargo.toml` | 修改 | windows crate 增加 `Win32_Graphics_Gdi` feature |
+| `apps/app-frontend/src/App.vue` | 修改 | 遮罩三阶段、淡出、透明度重置等前端逻辑 |
+| `apps/app-frontend/public/mojang-logo.svg` | 新建 | 过渡遮罩上显示的 Mojang logo |
+| `packages/app-lib/.env` | 新建 | 从 `.env.prod` 复制，提供编译期环境变量（非功能改动） |
+
+## 三、各文件详细说明
+
+### 1. `apps/app/src/mc_transition.rs`（新建 · 核心）
+
+> 搜索定位关键词：`mc_transition`
+
+**关键常量**：
+
+| 常量 | 值 | 含义 |
+|---|---|---|
+| `FIND_RETRIES` | 120 | 等待 MC 窗口的最大轮询次数 |
+| `FIND_INTERVAL_MS` | 500 | 每次轮询间隔（120 × 500ms = 60 秒） |
+| `ANIM_DURATION_MS` | 400 | 放大/缩小动画时长（0.4s） |
+| `ANIM_STEPS` | 50 | 动画帧数（400ms / 50 = 8ms 一帧） |
+| `FADE_TIMEOUT_MS` | 700 | 等待前端淡出的超时兜底 |
+
+**静态变量（跨 await 传信号）**：
+
+- `FADE_DONE` — 等前端淡出完成
+- `COVER_DONE` — 等纯色遮罩出现
+- `LOGO_IN_DONE` — 等 logo 渐显完成
+- `LOGO_OUT_DONE` — 等 logo 渐隐 + 变红完成
+
+**关键函数**：
+
+| 函数 | 关键词 | 作用 |
+|---|---|---|
+| `pub async fn run(app, pid, maximize)` | `run() invoked` | 主入口，串联全部 8 步 |
+| `async fn animate_resize(...)` | `animate_resize` | 分帧移动 + 缩放窗口 |
+| `fn ease_in_out(t)` | `ease_in_out` | 缓入缓出曲线 |
+| `win_impl::find_window(pid)` | `find_cb` / `FOUND_HWND` | 按 pid 枚举顶层窗口 |
+| `win_impl::covers_monitor(raw)` | `covers_monitor` | 判断窗口是否铺满显示器 |
+| `win_impl::get_rect(raw)` | `get_rect` | 取窗口矩形 |
+| `win_impl::focus(raw)` | `SetForegroundWindow` | 把焦点交给游戏 |
+| `win_impl::dump_pid_windows(pid)` | `dump_pid_windows` | **调试用**：列出 pid 下所有窗口 |
+| `#[tauri::command] mc_transition_fade_done` | — | 前端淡出完成回调 |
+| `#[tauri::command] mc_transition_cover_ready` | — | 遮罩出现完成回调 |
+| `#[tauri::command] mc_transition_logo_in_done` | — | logo 渐显完成回调 |
+| `#[tauri::command] mc_transition_logo_out_done` | — | logo 渐隐完成回调 |
+
+**⚠️ 三个关键设计约束（改代码前必读）**：
+
+1. **HWND 不能跨 await 持有**。
+   `HWND` 是裸指针，非 `Send`，一旦跨 `await` 持有，async 块就不是 `Send`，无法被 `tauri::async_runtime::spawn`。
+   → 因此全程用 `usize` 保存窗口句柄（变量 `mc_raw`），只在同步的 win32 调用里通过 `to_hwnd()` 临时转回。
+   搜索关键词：`to_hwnd`、`FOUND_HWND`
+
+2. **`BOOL` 的导入路径**。
+   `windows` crate 0.61 中，`BOOL` 位于 `windows::core::BOOL`，**不在** `Win32::Foundation`。
+   搜索关键词：`use windows::core::BOOL`
+
+3. **窗口尺寸过滤阈值**。
+   `find_cb` 里只认宽高都 > 50 的可见窗口，用来排除工具窗口 / 0 尺寸窗口。
+
+**⚠️ 调试代码仍在（上线前需清理）**：
+
+- `fn dbg(msg)` —— 把日志直接写入 `%USERPROFILE%\mc_transition_debug.log`，绕过 tracing 配置
+- 全文件多处 `dbg(...)` 调用
+- 等待窗口期间每 2 秒调用一次 `dump_pid_windows`
+- 搜索关键词：`fn dbg(`、`mc_transition_debug.log`、`dump_pid_windows`
+
+### 2. `apps/app/src/main.rs`
+
+- 第 25 行附近：`mod mc_transition;`
+- `invoke_handler` 的 `generate_handler!` 宏内注册 4 个命令：
+
+```rust
+mc_transition::mc_transition_fade_done,
+mc_transition::mc_transition_cover_ready,
+mc_transition::mc_transition_logo_in_done,
+mc_transition::mc_transition_logo_out_done,
+```
+
+- 搜索关键词：`mod mc_transition`、`mc_transition_fade_done`
+
+### 3. `apps/app/src/lightweight_mode.rs`
+
+`process_event` 中 `None if payload.event == "launched"` 分支（约 250 行起）：
+
+- 新增调用：`crate::mc_transition::run(&app, payload.pid, payload.maximize_window).await;`
+- 过渡完成后**统一**进入轻量模式：`state.enter(&app)`
+- **删除**了原来分别判断 `settings.enter_lightweight_mode_on_game_launch` 与 `settings.hide_on_process_start` 的逻辑
+- 搜索关键词：`crate::mc_transition::run`、`launched`、`enter lightweight mode after transition`
+
+**执行顺序**：
+```
+maximize_minecraft_window（若用户勾选最大化）
+  → mc_transition::run（完整过渡动画）
+  → state.enter()（隐藏到托盘）
+```
+
+### 4. `apps/app/Cargo.toml`
+
+`[target."cfg(windows)".dependencies.windows]` 的 features 中新增：
+
+```toml
+"Win32_Graphics_Gdi",
+```
+
+> 原因：`GetMonitorInfoW` / `MonitorFromWindow` / `MONITORINFO` 属于 GDI 模块，不加会编译失败。
+
+- 搜索关键词：`Win32_Graphics_Gdi`
+
+### 5. `apps/app-frontend/src/App.vue`
+
+**变量声明**（约 376~381 行）：
+
+```ts
+let unlistenMcTransitionFadeout: (() => void) | undefined
+let unlistenMcTransitionFocus: (() => void) | undefined
+let unlistenMcTransitionCover: (() => void) | undefined
+let unlistenMcTransitionLogoIn: (() => void) | undefined
+let unlistenMcTransitionLogoOut: (() => void) | undefined
+let unlistenMcTransitionReset: (() => void) | undefined
+```
+
+**`onMounted` 内注册的监听**（约 500 行起）：
+
+| 监听事件 | 作用 |
+|---|---|
+| `mc-transition-fadeout` | `#app` 设 `opacity: 0` + 500ms 过渡，510ms 后回调 `mc_transition_fade_done` |
+| `mc-transition-cover-show` | 动态创建遮罩 div（主题色背景 + 隐藏的 logo），渐显后回调 `mc_transition_cover_ready` |
+| `mc-transition-logo-in` | logo 渐显（opacity 0→1），520ms 后回调 `mc_transition_logo_in_done` |
+| `mc-transition-logo-out` | 遮罩背景 → `#db1f29` + logo 渐隐，520ms 后回调 `mc_transition_logo_out_done` |
+| `mc-transition-reset-opacity` | 重置 `#app` 透明度 + 移除遮罩 |
+
+**透明度重置（修复重开透明）**——三重兜底：
+- `window` 的 `focus` 事件
+- `document` 的 `visibilitychange` 事件
+- Tauri 的 `getCurrentWindow().onFocusChanged`
+
+任一触发即调用 `resetLauncherOpacity()`，把 `#app` 的 opacity 清空。
+
+**`onUnmounted` 内清理**（约 674 行起）：6 个 `unlistenMcTransition*.?.()`
+
+- 搜索关键词：`unlistenMcTransitionFadeout`、`mc-transition-fadeout`、`mc_transition_fade_done`、`mcCoverEl`、`resetLauncherOpacity`
+
+**遮罩实现细节**：
+
+遮罩是**运行时动态创建**的 DOM（不是 Vue template），避免改动庞大的 template 结构：
+
+```ts
+mcCoverEl = document.createElement('div')   // 固定定位、铺满、主题色背景、最高 z-index
+mcCoverImg = document.createElement('img')  // /mojang-logo.svg，初始 opacity 0
+```
+
+- 遮罩 id：`mc-transition-cover`
+- 背景色：`var(--color-brand, #db1f29)`（跟随启动器主题色）
+- logo 宽度：42%，最大 640px
+
+### 6. `apps/app-frontend/public/mojang-logo.svg`（新建）
+
+过渡遮罩上显示的 Mojang 官方 logo（矢量图）。
+
+## 四、实测记录
+
+调试日志 `%USERPROFILE%\mc_transition_debug.log` 中的一次完整流程实录：
+
+```
+run() invoked pid=3088 maximize=false
+try#0 ... try#38  candidates: []                 <- MC 窗口约 20 秒后才出现
+FOUND hwnd=0x3b03da try#40 covers=false
+...
+```
+
+**关键发现**：
+- **MC 窗口需要约 20 秒才出现**（带 mod 的实例更慢），所以等待轮询必须足够长（当前 60s）。
+- 早期版本只等 5 秒，导致「启动器毫无变化」的假象——实际是超时静默放弃了。
+
+## 五、编译与运行（Windows）
+
+### 前置准备
+
+```bat
+:: 1. 子模块（本项目不是 git 仓库，需手动 clone）
+git clone https://github.com/Cubitect/cubiomes.git apps/app/vendor/cubiomes
+git clone https://github.com/Axolotl-Launcher/blockbench-skin-standalone.git third-party/blockbench
+
+:: 2. 环境变量（或把 .env.prod 复制为 packages/app-lib/.env）
+set "PATH=%USERPROFILE%\.cargo\bin;%PATH%"
+set "MODRINTH_URL=https://modrinth.com/"
+set "MODRINTH_API_BASE_URL=https://api.modrinth.com/"
+set "MODRINTH_ARCHON_BASE_URL=https://archon.modrinth.com/"
+set "MODRINTH_API_URL=https://api.modrinth.com/v2/"
+set "MODRINTH_API_URL_V3=https://api.modrinth.com/v3/"
+set "MODRINTH_SOCKET_URL=wss://api.modrinth.com/"
+set "MODRINTH_LAUNCHER_META_URL=https://launcher-meta.modrinth.com/"
+```
+
+### 构建
+
+```bat
+:: 前端
+pnpm install
+pnpm --filter @modrinth/app-frontend run build
+
+:: 后端 debug（产物 target/debug/theseus_gui.exe，约 155 MB）
+cargo build -p theseus_gui
+
+:: 后端 release（产物 target/release/theseus_gui.exe，约 75 MB）
+cargo build -p theseus_gui --release
+```
+
+### 已知坑
+
+| 坑 | 现象 | 解决 |
+|---|---|---|
+| 子模块缺失 | `build.rs` panic：`Blockbench skin editor submodule is missing` | 手动 clone 两个子模块 |
+| 资源路径校验 | `resource path resources\blockbench-skin doesn't exist` | 构建会自动生成；若报错手动建空目录 |
+| 环境变量缺失 | `environment variable MODRINTH_API_URL not defined` | 见上方环境变量，或复制 `.env` |
+| 数据库迁移冲突 | `migration ... was previously applied but is missing` | 删除 `%APPDATA%\cool.starlight.launcher\release\app.db` 后重启 |
+| exe 被占用 | `failed to remove file ...theseus_gui.exe`（拒绝访问） | `taskkill /F /IM theseus_gui.exe` 后重编 |
+| `pnpm app:build` 失败 | 找不到 cargo | 那会走完整 `tauri build` 打包；只构建前端请用 `--filter @modrinth/app-frontend` |
+
+## 六、待办 / TODO
+
+| # | 事项 | 优先级 | 关键词 |
+|---|---|---|---|
+| 1 | **清理调试代码**：删 `fn dbg` + 所有 `dbg(...)` + `dump_pid_windows` 调用 | 高 | `fn dbg(`、`mc_transition_debug.log` |
+| 2 | 等待窗口超时（60s）可做成可配置 / 事件驱动 | 中 | `FIND_RETRIES` |
+| 3 | 多显示器场景未充分测试（已按窗口所在屏取显示器） | 中 | `monitor_rect` |
+| 4 | 前端淡出若卡顿靠 700ms 兜底 | 低 | `FADE_TIMEOUT_MS` |
+| 5 | `SetForegroundWindow` 可能被系统拒绝，未做失败重试 | 低 | `focus` |
+| 6 | 未来若做 macOS / Linux 支持：需 `CGWindowListCopyWindowInfo` / X11（Wayland 基本不可行） | 低 | `#[cfg(target_os]` |
+
+## 七、快速搜索索引
+
+| 想找什么 | 搜这个关键词 |
+|---|---|
+| 核心模块 | `mc_transition` |
+| 过渡主流程 | `pub async fn run(app` |
+| 八步流程标记 | `step 1` ~ `step 8` |
+| 找 MC 窗口 | `find_window`、`find_cb` |
+| 全屏判定 | `covers_monitor` |
+| 缩放动画 | `animate_resize`、`ANIM_DURATION_MS` |
+| 缓动曲线 | `ease_in_out` |
+| 纯色遮罩事件 | `mc-transition-cover-show` |
+| logo 渐显事件 | `mc-transition-logo-in` |
+| logo 渐隐/变红事件 | `mc-transition-logo-out` |
+| 淡出事件 | `mc-transition-fadeout` |
+| 透明度重置事件 | `mc-transition-reset-opacity` |
+| 前端回调命令 | `mc_transition_cover_ready`、`mc_transition_logo_in_done`、`mc_transition_logo_out_done`、`mc_transition_fade_done` |
+| 接入点 | `crate::mc_transition::run` |
+| 透明度重置函数 | `resetLauncherOpacity` |
+| 遮罩 DOM | `mc-transition-cover`、`mcCoverEl` |
+| 调试日志（待删） | `fn dbg(`、`mc_transition_debug.log` |
+| 调试日志文件 | `%USERPROFILE%\mc_transition_debug.log` |
+| windows feature | `Win32_Graphics_Gdi` |
+| 数据库冲突 | `previously applied but is missing` |
+
+---
+
+_文档结束。功能已跑通，上线前记得清理调试代码喵。_