# Web Window Transparency Construct

最后更新：2026-03-20  
状态：规范性（Normative）

本文档约束 Formax 桌面端（Electron + Web UI）窗口透明能力的实现方式。  
目标是让“透明开关、视觉分层、交互一致性”有唯一依据，避免重复返工。

## 目标和范围

在范围内：
- 透明状态模型（只允许 `off/on` 两态）
- 主进程和渲染进程职责边界（IPC）
- 页面视觉构造（整窗透明底 + 右侧白底圆角）
- 透明切换验收标准

不在范围内：
- 纯 Web 模式视觉方案
- 线程业务逻辑、菜单业务逻辑
- 透明以外的主题系统重构

## 相关实现锚点

- `packages/desktop-electron/src/main.ts`
- `packages/desktop-electron/src/preload.ts`
- `packages/desktop-electron/src/windowAppearanceState.ts`
- `packages/web-reference-react/src/app/ui/AppShell.tsx`
- `packages/web-reference-react/src/styles.css`

## 状态模型（必须两态）

- 透明状态只允许两种：
1. `off`：窗口不透明展示
2. `on`：窗口透明展示
- 不允许对外暴露第三种业务状态（例如 `css/native`）。
- 状态载荷保持：
1. `revision: number`
2. `windowTransparencyEnabled: boolean`

## 真值源与通信边界

- 透明状态唯一真值在主进程。
- 渲染进程只负责发请求与订阅状态，不自持独立真值。
- 切换流程固定为：
1. 渲染进程发送 `set-window-transparency`
2. 主进程更新状态并广播
3. 渲染进程按主进程返回值收敛展示
- 状态持久化只允许主进程执行。

## 视觉构造（核心）

- 透明 `on` 时，语义是整窗背景透明，不是“只透明左侧”。
- 右侧不透明感来自右侧自身白底表面层，而不是关掉整窗透明。
- 左侧容器链路（panel/host/topbar/bottombar）必须保持透明背景。
- 左侧视觉变化只由 Item 状态色承担（hover/active/selected）。
- 右侧白底容器使用左上角与左下角圆角。
- 圆角切出的区域应直接露出整窗透明底。
- 禁止使用额外“过渡条/渐变条/伪边框层”去遮交界。

## 分层建议

推荐按四层理解：
1. 窗口底层（桌面壁纸可见层，`on` 时透明）
2. 应用全局背景层（跟随透明状态）
3. 左侧布局承载层（透明容器，不承载底色）
4. 右侧内容实底层（白底，左上/左下圆角）

禁止再加独立“第五层过渡条”。

## 生命周期与交互要求

- 首次加载时，渲染进程要主动 `get-state` 并订阅广播。
- 连续快速切换允许排队，但最终展示必须和主进程最终 revision 一致。
- 切换生效不能依赖手动刷新页面。

## 验收清单

透明 `on` 时：
- 整窗底层透明
- 右侧白底仅左上/左下圆角
- 不出现白条、悬浮边框条、伪过渡条

透明 `off` 时：
- 不应透出桌面壁纸

连续切换 `off -> on -> off`：
- 不出现状态与视觉不一致
- 不需要刷新才能恢复正常

设置页、线程页、输入区都必须满足同样语义，不允许“某页正常某页断层”。

## 对齐 Codex.css 的使用原则

- 学的是策略，不是像素复刻。
- 透明态优先用“减法策略”：
1. 让已有层变透明或隐藏
2. 避免新增视觉补丁层
- 可有受控 transition，但不能做整高固定渐变条。
- 透明态色值优先固定 RGBA，不依赖主题 token 的连锁 `color-mix` 推导。
- 透明态应坚持单层着色原则：只在一个根容器施加半透明底色，避免 `root/body/#root` 叠色导致观感发糊。

## 变更流程

涉及透明能力、IPC 协议、圆角几何或分层关系时，按顺序执行：
1. 先改本 construct
2. 再改主进程/预加载/渲染实现
3. 最后补测试与回归证据

如果实现和本文件冲突，优先修实现，不修文案。
