feat(onboarding): 强制走完新手引导，开发版本可跳过

[ocsin1]

• close [Bug] 点击空白处会跳过教程 #238

正文:

• 屏蔽 ESC、遮罩点击、× 按钮，引导必须走完最后一步才视为完成； 中途关闭软件不写入 completed，下次启动重新弹出

• 开发模式（import.meta.env.DEV 或 isDebugVersion）下在 popover 左侧注入「跳过（DEV）」按钮，非开发版完全不渲染

• 以及修复 WelcomeDialog 异步加载窗口期内教程抢先弹出后被公告盖住的 竞态(测 maaend 的 api 测出来的,加载超过 600 ms 容易触发)：加载中渲染一个不可见的 z-50 占位，让 hasActiveModal 能 正确感知决策未完成

效果演示 :

Demo.Video.mp4

Summary by Sourcery

在强制完成新手引导教程的同时，增加仅用于开发环境的跳过选项，并防止教程在欢迎对话框之前过早开始。

New Features:

• 要求用户完成所有新手引导步骤后才视为完成，在正常构建中移除引导流程中的关闭/跳过控件。
• 在新手引导气泡中添加仅限开发模式使用的跳过按钮，允许开发者绕过教程。
• 暴露更多 driver.js 气泡的类型定义，以支持自定义气泡渲染钩子和导航按钮。

Bug Fixes:

• 确保在所有提前返回的路径中正确清除欢迎对话框的加载状态，防止其被阻塞或被新手引导教程覆盖。
• 在欢迎对话框加载期间渲染一个不可见但具有高 z-index 的占位元素，使新手引导能够正确检测到活动模态窗口，从而不会抢先于它显示。

Enhancements:

• 通过移除“设备资源加载完成后自动完成引导”的行为，简化新手引导完成逻辑。
• 调整新手引导气泡样式以对齐新的跳过按钮，并为开发环境中的跳过标签在所有支持的语言中添加本地化字符串。

Original summary in English

Summary by Sourcery

Enforce completion of the onboarding tutorial while adding a development-only skip option and preventing the tutorial from racing ahead of the welcome dialog.

New Features:

• Require users to complete all onboarding steps before it is considered finished, removing close/skip controls from the tour in normal builds.
• Add a development-mode-only skip button to the onboarding popover, allowing developers to bypass the tutorial.
• Expose additional driver.js popover typing to support custom popover render hooks and navigation buttons.

Bug Fixes:

• Ensure the welcome dialog loading state is cleared correctly in all early-return paths, preventing it from blocking or being overlaid by the onboarding tutorial.
• Render an invisible high-z-index placeholder while the welcome dialog is loading so onboarding correctly detects an active modal and does not preempt it.

Enhancements:

• Simplify onboarding completion logic by removing auto-completion when device resources finish loading.
• Adjust onboarding popover styling to align the new skip button, and add localized strings for the development skip label in all supported languages.

Original summary in English

Summary by Sourcery

在强制完成新手引导教程的同时，增加仅用于开发环境的跳过选项，并防止教程在欢迎对话框之前过早开始。

New Features:

• 要求用户完成所有新手引导步骤后才视为完成，在正常构建中移除引导流程中的关闭/跳过控件。
• 在新手引导气泡中添加仅限开发模式使用的跳过按钮，允许开发者绕过教程。
• 暴露更多 driver.js 气泡的类型定义，以支持自定义气泡渲染钩子和导航按钮。

Bug Fixes:

• 确保在所有提前返回的路径中正确清除欢迎对话框的加载状态，防止其被阻塞或被新手引导教程覆盖。
• 在欢迎对话框加载期间渲染一个不可见但具有高 z-index 的占位元素，使新手引导能够正确检测到活动模态窗口，从而不会抢先于它显示。

Enhancements:

• 通过移除“设备资源加载完成后自动完成引导”的行为，简化新手引导完成逻辑。
• 调整新手引导气泡样式以对齐新的跳过按钮，并为开发环境中的跳过标签在所有支持的语言中添加本地化字符串。

Original summary in English

Summary by Sourcery

Enforce completion of the onboarding tutorial while adding a development-only skip option and preventing the tutorial from racing ahead of the welcome dialog.

New Features:

• Require users to complete all onboarding steps before it is considered finished, removing close/skip controls from the tour in normal builds.
• Add a development-mode-only skip button to the onboarding popover, allowing developers to bypass the tutorial.
• Expose additional driver.js popover typing to support custom popover render hooks and navigation buttons.

Bug Fixes:

• Ensure the welcome dialog loading state is cleared correctly in all early-return paths, preventing it from blocking or being overlaid by the onboarding tutorial.
• Render an invisible high-z-index placeholder while the welcome dialog is loading so onboarding correctly detects an active modal and does not preempt it.

Enhancements:

• Simplify onboarding completion logic by removing auto-completion when device resources finish loading.
• Adjust onboarding popover styling to align the new skip button, and add localized strings for the development skip label in all supported languages.

[sourcery-ai]

Hey - 我在这里给出了一些总体反馈：

• 在 OnboardingOverlay 的 onPopoverRender 中，你给动态创建的按钮添加了点击监听器，但从未移除它；建议在合适的时机清理这个监听器（例如在销毁时，或者通过复用同一个按钮实例），以避免在弹出层重新渲染时产生潜在的内存泄漏或重复的事件处理。
• 在自动连接的 effect 中，你将 tourFinishedRef.current 设为 true，同时在该 effect 和 onDestroyed 中都调用了 setOnboardingCompleted(true)；建议将这一逻辑整合到单一的位置更新，这样可以让引导完成的副作用路径更加简单、易于理解。

给 AI 代理的提示

Please address the comments from this code review:

## Overall Comments
- In `OnboardingOverlay`'s `onPopoverRender`, you are attaching a click listener to a dynamically created button but never removing it; consider cleaning up the listener (e.g., on destroy or by reusing a single button instance) to avoid potential leaks or duplicate handlers if the popover is re-rendered.
- `tourFinishedRef.current` is set to `true` in the auto-connect effect and you also call `setOnboardingCompleted(true)` both there and in `onDestroyed`; consider consolidating this so onboarding completion is updated in a single place to keep the side-effect path simpler and easier to reason about.

---

Sourcery 对开源项目是免费的——如果你觉得我们的代码审查有帮助，欢迎帮忙分享 ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{帮我变得更有用！请在每条评论上点 👍 或 👎，我会根据你的反馈改进后续的代码审查。}

Original comment in English

Hey - I've left some high level feedback:

• In OnboardingOverlay's onPopoverRender, you are attaching a click listener to a dynamically created button but never removing it; consider cleaning up the listener (e.g., on destroy or by reusing a single button instance) to avoid potential leaks or duplicate handlers if the popover is re-rendered.
• tourFinishedRef.current is set to true in the auto-connect effect and you also call setOnboardingCompleted(true) both there and in onDestroyed; consider consolidating this so onboarding completion is updated in a single place to keep the side-effect path simpler and easier to reason about.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In `OnboardingOverlay`'s `onPopoverRender`, you are attaching a click listener to a dynamically created button but never removing it; consider cleaning up the listener (e.g., on destroy or by reusing a single button instance) to avoid potential leaks or duplicate handlers if the popover is re-rendered.
- `tourFinishedRef.current` is set to `true` in the auto-connect effect and you also call `setOnboardingCompleted(true)` both there and in `onDestroyed`; consider consolidating this so onboarding completion is updated in a single place to keep the side-effect path simpler and easier to reason about.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

Hey - 我已经审查了你的更改，一切看起来都很棒！

---

Sourcery 对开源项目是免费的——如果你觉得我们的评审有帮助，欢迎分享给更多人 ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{帮我变得更有用！请在每条评论上点 👍 或 👎，我会根据你的反馈持续改进评审质量。}

Original comment in English

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}