frontend: FE-027 隐藏式标题栏红绿灯融入顶栏，防启动白闪与顶栏拖拽区

Co-authored-by: Cursor <cursoragent@cursor.com>

mactfsui/app/app.css

@@ -149,3 +149,12 @@
     @apply font-sans;
     }
 }
+
+/* 隐藏式标题栏下的窗口拖拽区域：顶栏整体可拖动，交互控件单独豁免。 */
+@utility app-drag {
+  -webkit-app-region: drag;
+}
+
+@utility app-no-drag {
+  -webkit-app-region: no-drag;
+}

mactfsui/app/components/app/top-bar.tsx

@@ -3,6 +3,7 @@ import { PanelBottom, PanelLeft, PanelRight } from "lucide-react"
 import { Button } from "~/components/ui/button"
 import { Separator } from "~/components/ui/separator"
 import { Tooltip, TooltipContent, TooltipTrigger } from "~/components/ui/tooltip"
+import { isMacElectron } from "~/lib/platform"
 import type { WorkspaceSession } from "~/lib/tfs/session"
 import { cn } from "~/lib/utils"
 
@@ -30,8 +31,15 @@ export function TopBar({
   onReconnect: () => void
   onManageWorkspace: () => void
 }) {
+  // 隐藏式标题栏下顶栏整体作为拖拽区，并为左上角红绿灯预留空间。
+  const macInset = isMacElectron()
   return (
-    <header className="flex h-12 shrink-0 items-center justify-between gap-3 border-b bg-background px-3">
+    <header
+      className={cn(
+        "app-drag flex h-12 shrink-0 items-center justify-between gap-3 border-b bg-background px-3",
+        macInset && "pl-20",
+      )}
+    >
       <div className="flex min-w-0 items-center gap-2 text-sm">
         <span className="shrink-0 font-semibold">MacTFS</span>
         <Separator orientation="vertical" className="h-4!" />
@@ -49,7 +57,7 @@ export function TopBar({
         <span className="max-w-44 truncate font-mono text-xs">{session.workspace}</span>
       </div>
 
-      <div className="flex shrink-0 items-center gap-1">
+      <div className="app-no-drag flex shrink-0 items-center gap-1">
         <PanelToggle
           label="源码目录面板"
           active={panels.tree}

mactfsui/app/lib/platform.ts

@@ -0,0 +1,11 @@
+/**
+ * 是否运行在 macOS 的 Electron 窗口内。
+ * 用于判断隐藏式标题栏场景：需要为红绿灯预留空间并启用顶栏拖拽。
+ */
+export function isMacElectron(): boolean {
+  if (typeof navigator === "undefined") {
+    return false
+  }
+  const ua = navigator.userAgent
+  return ua.includes("Electron") && ua.includes("Macintosh")
+}

mactfsui/electron/main.cjs

@@ -1,4 +1,4 @@
-const { app, BrowserWindow, ipcMain, dialog, shell, nativeImage } = require("electron")
+const { app, BrowserWindow, ipcMain, dialog, shell, nativeImage, nativeTheme } = require("electron")
 const path = require("node:path")
 const fs = require("node:fs")
 const os = require("node:os")
@@ -284,7 +284,16 @@ function createWindow() {
   const mainWindow = new BrowserWindow({
     width: 1280,
     height: 840,
+    minWidth: 980,
+    minHeight: 640,
     title: "MacTFS",
+    // 预设与主题一致的背景色并延迟显示，避免启动白闪。
+    show: false,
+    backgroundColor: nativeTheme.shouldUseDarkColors ? "#1d1d20" : "#fafafa",
+    // macOS 隐藏系统标题栏，红绿灯融入应用顶栏；其它平台回退系统标题栏。
+    ...(process.platform === "darwin"
+      ? { titleBarStyle: "hiddenInset", trafficLightPosition: { x: 16, y: 16 } }
+      : {}),
     ...(iconPath ? { icon: nativeImage.createFromPath(iconPath) } : {}),
     webPreferences: {
       preload: path.join(__dirname, "preload.cjs"),
@@ -293,6 +302,10 @@ function createWindow() {
     },
   })
 
+  mainWindow.once("ready-to-show", () => {
+    mainWindow.show()
+  })
+
   if (process.env.NODE_ENV === "development") {
     mainWindow.loadURL("http://localhost:5173")
     return

task/README.md

@@ -31,10 +31,10 @@ blocked
 | Core | 12 | 12 | 100% |
 | Server API | 10 | 10 | 100% |
 | CLI | 2 | 2 | 100% |
-| Frontend | 26 | 34 | 76% |
+| Frontend | 27 | 34 | 79% |
 | Feature E2E | 0 | 5 | 0% |
 | Release | 0 | 4 | 0% |
-| Overall | 50 | 67 | 75% |
+| Overall | 51 | 67 | 76% |
 
 ## 当前阶段
 
@@ -46,7 +46,7 @@ UI 风格改版（分支 `feature/ui-modern-restyle`，FE-026 ~ FE-034，需求
 
 ## 下一步任务
 
-- [FE-027-Electron无缝窗口与自绘顶栏.md](/Users/fenghp/Desktop/DEV/project/mydev/task/frontend/FE-027-Electron无缝窗口与自绘顶栏.md)
+- [FE-028-重设计登录页.md](/Users/fenghp/Desktop/DEV/project/mydev/task/frontend/FE-028-重设计登录页.md)
 - UI 改版完成后再回到 [FEATURE-001-连接与目录浏览端到端验收.md](/Users/fenghp/Desktop/DEV/project/mydev/task/feature/FEATURE-001-连接与目录浏览端到端验收.md)（需要真实 TFS 环境）
 
 ## Core
@@ -118,7 +118,7 @@ UI 风格改版（分支 `feature/ui-modern-restyle`，FE-026 ~ FE-034，需求
 | [FE-024-实现合并.md](/Users/fenghp/Desktop/DEV/project/mydev/task/frontend/FE-024-实现合并.md) | done | P1 |
 | [FE-025-实现访达打开与添加本地文件.md](/Users/fenghp/Desktop/DEV/project/mydev/task/frontend/FE-025-实现访达打开与添加本地文件.md) | done | P0 |
 | [FE-026-建立现代桌面风设计基建.md](/Users/fenghp/Desktop/DEV/project/mydev/task/frontend/FE-026-建立现代桌面风设计基建.md) | done | P0 |
-| [FE-027-Electron无缝窗口与自绘顶栏.md](/Users/fenghp/Desktop/DEV/project/mydev/task/frontend/FE-027-Electron无缝窗口与自绘顶栏.md) | todo | P0 |
+| [FE-027-Electron无缝窗口与自绘顶栏.md](/Users/fenghp/Desktop/DEV/project/mydev/task/frontend/FE-027-Electron无缝窗口与自绘顶栏.md) | done | P0 |
 | [FE-028-重设计登录页.md](/Users/fenghp/Desktop/DEV/project/mydev/task/frontend/FE-028-重设计登录页.md) | todo | P0 |
 | [FE-029-工作台外壳与顶栏改版.md](/Users/fenghp/Desktop/DEV/project/mydev/task/frontend/FE-029-工作台外壳与顶栏改版.md) | todo | P0 |
 | [FE-030-目录树与文件列表精致化.md](/Users/fenghp/Desktop/DEV/project/mydev/task/frontend/FE-030-目录树与文件列表精致化.md) | todo | P0 |

task/frontend/FE-027-Electron无缝窗口与自绘顶栏.md

@@ -2,7 +2,7 @@
 
 ## 状态
 
-todo
+done
 
 ## 优先级
 
@@ -58,9 +58,18 @@ cd mactfsui && pnpm electron:dev
 
 ## 完成记录
 
-待完成后填写：
-
 - 实际修改文件：
+  - `mactfsui/electron/main.cjs`
+  - `mactfsui/app/components/app/top-bar.tsx`
+  - `mactfsui/app/app.css`（新增 `app-drag` / `app-no-drag` 工具类）
+  - 新增 `mactfsui/app/lib/platform.ts`（isMacElectron 判断）
 - 实际实现内容：
+  - macOS 下 BrowserWindow 配置 `titleBarStyle: "hiddenInset"` + `trafficLightPosition {16,16}`，非 macOS 平台回退系统标题栏
+  - 窗口 `show: false` + `ready-to-show` 后显示，backgroundColor 按 nativeTheme 取 `#fafafa` / `#1d1d20`，消除启动白闪
+  - 新增 `minWidth 980 / minHeight 640`
+  - 顶栏整体设为拖拽区（`app-drag`），右侧按钮容器豁免（`app-no-drag`）；macOS Electron 下顶栏左侧 `pl-20` 为红绿灯预留空间
 - 测试结果：
+  - `pnpm typecheck` 通过、`pnpm build` 通过
+  - 未执行 `pnpm electron:dev` 人工拖拽验证（GUI 交互验证，待 FE-034 回归时统一走查）
 - 遗留问题：
+  - 登录页（无顶栏）尚无拖拽区，将在 FE-028 登录页改版时补充