Desktop welcome window material
桌面欢迎窗口材质
The desktop welcome design blurs the desktop behind its entire window. Chromium backdrop filters only sample content inside the renderer. Credential setup also needs an explicit startup owner so a native skip is not followed by a second Web dialog.
English
Problem
The desktop welcome design blurs the desktop behind its entire window. Chromium backdrop filters only sample content inside the renderer. Credential setup also needs an explicit startup owner so a native skip is not followed by a second Web dialog.
Decision
The Electron welcome window owns native material and window controls. Its independently bundled React renderer supplies the entry, account sign-in states and API-key form. It shares the StateDot loading component with the Web UI without booting the Web plugin graph. The Desktop build emits local JavaScript and CSS under lib/welcome, included in packaged applications; the document keeps its network-denying content security policy. A narrow preload supplies typed shell copy, a write-only key operation, and a skip operation; IPC rejects other windows and subframes. Each sandboxed preload is bundled independently because Electron’s restricted require cannot load sibling chunks. The Electron main process authenticates through the shared Web launch URL and resolves the official provider's reference through the existing settings and credential RPC methods. The thin Web wrapper owns the HTTP server; onboarding adds no Host endpoint or child IPC operation. Responses contain metadata or a safe outcome, never a key or private provider diagnostics.
Cold startup opens the entry when neither an account credential nor a model API key is configured. Saving enters the workspace after persistence succeeds; skipping enters without saving a draft or a credential-entry completion flag. The next process launch checks credentials again. The Desktop preload marker suppresses the automatic Web credential step and welcome notice; settings and explicit API-key editing remain available. The Desktop onboarding reference owns the separate device-local introduction after account login. Other native shells can disable only the credential step through the Models Host plugin's credentialOnboarding page-injection value. The module graph carries package identities rather than arbitrary Host config, so a Host row alone does not configure its Client half. The account provider supplies login and sign-out state while preserving independently stored API keys.
The generated project follows declared workspace dependencies because pnpm’s hoist index alone can omit configured plugins.
Desktop reads the shared locale.preference before opening the welcome window. The Client awaits an isolated preload read of that preference and the same OS language order before mounting, then reports resolved locale changes to the shell. Only an explicit Settings selection writes the preference; automatic detection stays provisional. The shell ships English and Simplified Chinese dictionaries, so a Client-only language pack falls back to a supported OS language in native windows.
The welcome flow shares the Desktop backend controller with startup recovery. The main recovery document loads offscreen while the Host starts; a failure reveals it, and successful startup chooses the welcome window or workspace after reading credentials and locale. Recovery actions retain the controller’s serialized retries and awaited child shutdown. The application preload exposes recovery controls only to shell documents and the locale bridge only to application documents.
Alternatives considered
A CSS-only backdrop filter. It cannot blur other application windows or the desktop, so it cannot provide the required native effect.
Persisting a credential-entry completion flag. A native credential skip is valid only for the current process; retaining it would suppress the next cold-start choice while the user still has no credentials. The account introduction's separate completion flag does not bypass this authentication decision.
Keeping both native and Web credential dialogs. Their separate completion state would ask for a key twice after a native skip. The composition assigns credential onboarding to one owner.
Drawing replacement traffic lights. Native controls preserve platform window behavior and accessibility. Their dimensions and outer window corners follow the OS rather than reproducing Figma geometry exactly.
Separate preview callbacks. A visual-only skip cannot demonstrate entry into the workspace and can hide broken startup dependencies. The preview uses the same callbacks and Host as the product.
Consequences
Native blur strength and font fallback vary by system. The main window uses the shared sidebar vibrancy; full-window onboarding retains a transparent renderer without an additional tint. Windows compositing needs platform QA. Owner-local text expectations cover both pages and locales, and built-Host acceptance covers credential persistence across restarts. Account sign-out preserves independent API keys. Onboarding presentation produces no Session events.
中文
问题
桌面欢迎界面的设计要求整个窗口模糊其背后的桌面。Chromium 背景滤镜只能采样渲染器内部的内容。凭证配置还需要明确的启动归属，避免跳过原生引导后又出现 Web 弹窗。
决策
Electron 欢迎窗口负责原生材质和窗口控件。独立打包的 React 渲染器提供入口、账号登录状态和 API Key 表单。它与 Web UI 共用 StateDot 加载组件，不启动 Web 插件图。Desktop 构建将本地 JavaScript 和 CSS 输出到 lib/welcome，并纳入应用安装包；文档继续使用禁止网络访问的内容安全策略。窄接口 preload 提供强类型桌面文案、仅写密钥操作和跳过操作；IPC 拒绝其他窗口和子 frame。每个沙箱 preload 都独立打包，因为 Electron 受限的 require 无法加载同目录中的拆分模块。Electron 主进程通过共享 Web 启动 URL 认证，并通过现有设置和凭证 RPC 方法解析官方提供方的引用。Web 薄壳负责 HTTP 服务；引导不增加 Host 端点或子进程 IPC 操作。响应只包含元数据或安全结果，不包含密钥或提供方的私有诊断。
冷启动在账号凭证与模型 API Key 均未配置时打开入口。保存会在持久化成功后进入工作区；跳过会直接进入，不保存草稿或凭证入口完成标记。下次进程启动时会重新检查凭证。Desktop preload 标记抑制自动 Web 凭证步骤和欢迎须知；设置与显式 API Key 编辑仍然可用。Desktop 引导参考负责账号登录后独立的设备本地介绍流程。其他原生壳可以通过 Models Host 插件注入页面的 credentialOnboarding 值仅禁用凭证步骤。模块图传递的是包标识，而不是任意 Host 配置，因此单独配置 Host 行不会配置其 Client 半部。账号提供方提供登录与退出登录状态，同时保留独立存储的 API Key。
生成的开发项目沿已声明的 workspace 依赖建立链接，因为单独依赖 pnpm 的提升索引会漏掉配置插件。
Desktop 在打开欢迎窗口前读取共享的 locale.preference。Client 在挂载前等待隔离 preload 返回该偏好和同一系统语言顺序，之后将解析后的语言变更通知桌面壳。只有设置中的明确选择会写入偏好；自动检测保持临时状态。桌面壳自带英文和简体中文词典，因此仅在 Client 中提供的语言包会在原生窗口回退到受支持的系统语言。
欢迎流程与启动恢复共用 Desktop 后端控制器。Host 启动期间，主窗口在屏幕外加载恢复文档；失败时显示该文档，成功后读取凭证和语言，再选择欢迎窗口或工作区。恢复操作保留控制器的串行重试与等待子进程退出的行为。应用 preload 只向壳文档提供恢复控件，只向应用文档提供语言桥接。
考虑过的替代方案
仅使用 CSS 背景滤镜。 它无法模糊其他应用窗口或桌面，因此不能提供所需的原生效果。
持久化凭证入口完成标记。 跳过原生凭证入口只对当前进程有效；保留标记会在用户仍无凭证时抑制下次冷启动选择。账号介绍流程的独立完成标记不会绕过此认证判断。
同时保留原生与 Web 凭证弹窗。 两者独立的完成状态会在跳过原生引导后再次要求输入密钥。组合将凭证引导交给单一归属方。
绘制替代红绿灯。 原生控件保留平台窗口行为和无障碍能力。它们的尺寸与窗口外部圆角遵循操作系统，不严格复制 Figma 几何参数。
独立的预览回调。 纯视觉预览中的跳过无法证明能进入工作区，还会掩盖启动依赖缺失。预览使用与产品相同的回调和 Host。
后果
原生模糊强度和字体回退因系统而异。主窗口沿用共享的 sidebar vibrancy；全窗引导保持渲染器透明，不额外叠加底色。Windows 合成效果需要平台验证。所属目录内的文本预期覆盖两页和两种语言，构建后 Host 的验收覆盖凭证跨重启持久化。账号退出登录保留独立的 API Key。引导展示不会生成 Session 事件。