Merge branch 'feature/workspace-fullscreen' into feature/refactor-ts

Author: pallyoung

docs/help/desktop-guide.md

@@ -27,6 +27,7 @@
 - 终端面板切换按钮
 - 文件面板切换按钮
 - 设置按钮
+- 全屏按钮
 
 ### 左侧面板
 
@@ -138,6 +139,12 @@
 
 按 `F` 键进入专注模式，会隐藏左侧面板和底部终端面板，只保留中央工作区。按 `Escape` 退出专注模式。
 
+### 原生全屏
+
+点击设置按钮右侧的全屏按钮可进入浏览器原生全屏。处于全屏时，同一位置的按钮会切换为退出全屏，按 `Escape` 也可以退出。
+
+如果同时开启了专注模式和原生全屏，`Escape` 会先退出原生全屏，再退出专注模式。
+
 ## 常见问题
 
 **Q：如何找回被关闭的面板？**

docs/help/mobile-guide.md

@@ -22,6 +22,7 @@
 
 - 工作区名称（点击打开工作区抽屉，可切换工作区）
 - 设置入口
+- 全屏入口（仅在浏览器支持原生全屏时显示）
 
 ### 当前 Agent 区域
 
@@ -76,6 +77,8 @@
 - 移动端适合"查看"为主，复杂的文件编辑和 Agent 管理建议在桌面端完成
 - 手机键盘弹出时会压缩底部 Dock 区域，操作时注意布局变化
 - 终端操作在小屏幕上可能不便，建议仅在需要时查看
+- 如果浏览器支持原生全屏，可点击顶部栏右侧的全屏按钮进入；再次点击同一位置的按钮可退出
+- 某些移动端浏览器不支持原生全屏，此时不会显示该按钮
 
 ## 常见问题
 

packages/web/src/features/focus-mode/components/focus-mode.test.tsx

@@ -0,0 +1,46 @@
+import { fireEvent, render } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import { describe, expect, it } from "vitest";
+import { focusModeAtom } from "../../workspace/atoms";
+import { FocusMode } from "./focus-mode";
+
+function renderFocusModeWithStore(initialFocusMode: boolean) {
+  const store = createStore();
+  store.set(focusModeAtom, initialFocusMode);
+
+  render(
+    <Provider store={store}>
+      <FocusMode />
+    </Provider>
+  );
+
+  return store;
+}
+
+describe("FocusMode escape priority", () => {
+  it("does not close focus mode while native fullscreen is active", () => {
+    Object.defineProperty(document, "fullscreenElement", {
+      configurable: true,
+      get: () => document.body,
+    });
+
+    const store = renderFocusModeWithStore(true);
+
+    fireEvent.keyDown(window, { key: "Escape" });
+
+    expect(store.get(focusModeAtom)).toBe(true);
+  });
+
+  it("still exits focus mode when fullscreen is not active", () => {
+    Object.defineProperty(document, "fullscreenElement", {
+      configurable: true,
+      get: () => null,
+    });
+
+    const store = renderFocusModeWithStore(true);
+
+    fireEvent.keyDown(window, { key: "Escape" });
+
+    expect(store.get(focusModeAtom)).toBe(false);
+  });
+});

packages/web/src/features/focus-mode/components/focus-mode.tsx

@@ -84,6 +84,10 @@ export function FocusMode() {
 
       // Escape key exits focus mode
       if (e.key === "Escape" && focusMode) {
+        if (document.fullscreenElement) {
+          return;
+        }
+
         e.preventDefault();
         setFocusMode(false);
       }

packages/web/src/features/topbar/index.test.tsx

@@ -130,4 +130,51 @@ describe("TopBar", () => {
     expect(screen.getByRole("button", { name: "Hide Terminal" })).toHaveClass("topbar-btn--active");
     expect(screen.getByRole("button", { name: "Show Files" })).toHaveClass("topbar-btn--muted");
   });
+
+  it("renders the fullscreen toggle immediately to the right of settings when supported", () => {
+    const store = createStore();
+    store.set(localeAtom, "en");
+    store.set(workspacesLoadStateAtom, "ready");
+
+    render(
+      <Provider store={store}>
+        <TopBar
+          fullscreenController={{
+            supported: true,
+            isFullscreen: false,
+            enterFullscreen: vi.fn(),
+            exitFullscreen: vi.fn(),
+            toggleFullscreen: vi.fn(),
+          }}
+        />
+      </Provider>
+    );
+
+    const settingsButton = screen.getByTestId("settings-open");
+    const fullscreenButton = screen.getByRole("button", { name: "Enter Fullscreen" });
+
+    expect(settingsButton.nextElementSibling).toBe(fullscreenButton);
+  });
+
+  it("hides the fullscreen toggle when the controller reports unsupported", () => {
+    const store = createStore();
+    store.set(localeAtom, "en");
+    store.set(workspacesLoadStateAtom, "ready");
+
+    render(
+      <Provider store={store}>
+        <TopBar
+          fullscreenController={{
+            supported: false,
+            isFullscreen: false,
+            enterFullscreen: vi.fn(),
+            exitFullscreen: vi.fn(),
+            toggleFullscreen: vi.fn(),
+          }}
+        />
+      </Provider>
+    );
+
+    expect(screen.queryByRole("button", { name: "Enter Fullscreen" })).toBeNull();
+  });
 });

packages/web/src/features/topbar/index.tsx

@@ -12,11 +12,17 @@ import { useNavigate } from "react-router-dom";
 import { commandPaletteOpenAtom } from "../../atoms/app-ui";
 import { orderedWorkspacesAtom, resolvedActiveWorkspaceIdAtom } from "../../atoms/workspaces";
 import { useTranslation } from "../../lib/i18n";
+import type { WorkspaceFullscreenController } from "../workspace/actions/use-workspace-fullscreen";
 import { sidebarCollapsedAtom, terminalPanelVisibleAtom } from "../workspace/atoms";
+import { WorkspaceFullscreenButton } from "../workspace/components/workspace-fullscreen-button";
 import { WorkspaceLaunchModal } from "../workspace/views/shared/workspace-launch-modal";
 import { ConnectionStatus } from "./components/connection-status";
 import { WorkspaceTab } from "./components/tab";
 
+interface TopBarProps {
+  fullscreenController?: WorkspaceFullscreenController;
+}
+
 /**
  * TopBar Component
  *
@@ -25,7 +31,7 @@ import { WorkspaceTab } from "./components/tab";
  *   - Left: Workspace tabs + Add button
  *   - Right: ConnectionStatus, Quick Actions, Terminal toggle, Files toggle, Settings
  */
-export const TopBar: FC = () => {
+export const TopBar: FC<TopBarProps> = ({ fullscreenController }) => {
   const t = useTranslation();
   const navigate = useNavigate();
   const workspaceList = useAtomValue(orderedWorkspacesAtom);
@@ -95,6 +101,12 @@ export const TopBar: FC = () => {
         >
           <Settings size={14} />
         </button>
+        <WorkspaceFullscreenButton
+          controller={fullscreenController}
+          className="topbar-btn"
+          iconSize={14}
+          dataTestId="workspace-fullscreen-open"
+        />
       </div>
       {workspaceLaunchOpen ? (
         <WorkspaceLaunchModal onClose={() => setWorkspaceLaunchOpen(false)} />

packages/web/src/features/workspace/actions/use-workspace-fullscreen.test.tsx

@@ -0,0 +1,189 @@
+import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { useRef } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { useWorkspaceFullscreen } from "./use-workspace-fullscreen";
+
+function installFullscreenApi() {
+  let fullscreenElement: Element | null = null;
+
+  const requestFullscreen = vi.fn().mockImplementation(function (this: HTMLElement) {
+    fullscreenElement = this;
+    document.dispatchEvent(new Event("fullscreenchange"));
+    return Promise.resolve();
+  });
+
+  const exitFullscreen = vi.fn().mockImplementation(async () => {
+    fullscreenElement = null;
+    document.dispatchEvent(new Event("fullscreenchange"));
+  });
+
+  Object.defineProperty(document, "fullscreenEnabled", {
+    configurable: true,
+    value: true,
+  });
+
+  Object.defineProperty(document, "fullscreenElement", {
+    configurable: true,
+    get: () => fullscreenElement,
+  });
+
+  Object.defineProperty(document, "exitFullscreen", {
+    configurable: true,
+    value: exitFullscreen,
+  });
+
+  Object.defineProperty(HTMLElement.prototype, "requestFullscreen", {
+    configurable: true,
+    value: requestFullscreen,
+  });
+
+  return {
+    requestFullscreen,
+    exitFullscreen,
+    setFullscreenElement(next: Element | null) {
+      fullscreenElement = next;
+      document.dispatchEvent(new Event("fullscreenchange"));
+    },
+  };
+}
+
+function clearFullscreenApi() {
+  Object.defineProperty(document, "fullscreenEnabled", {
+    configurable: true,
+    value: false,
+  });
+
+  Object.defineProperty(document, "fullscreenElement", {
+    configurable: true,
+    get: () => null,
+  });
+
+  Object.defineProperty(document, "exitFullscreen", {
+    configurable: true,
+    value: undefined,
+  });
+
+  Object.defineProperty(HTMLElement.prototype, "requestFullscreen", {
+    configurable: true,
+    value: undefined,
+  });
+}
+
+function HookHarness() {
+  const targetRef = useRef<HTMLDivElement>(null);
+  const controller = useWorkspaceFullscreen(targetRef);
+
+  return (
+    <div>
+      <div ref={targetRef} data-testid="fullscreen-target" />
+      <output data-testid="supported">{String(controller.supported)}</output>
+      <output data-testid="fullscreen">{String(controller.isFullscreen)}</output>
+      <button
+        type="button"
+        onClick={() => {
+          void controller.enterFullscreen();
+        }}
+      >
+        enter
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          void controller.exitFullscreen();
+        }}
+      >
+        exit
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          void controller.toggleFullscreen();
+        }}
+      >
+        toggle
+      </button>
+    </div>
+  );
+}
+
+describe("useWorkspaceFullscreen", () => {
+  afterEach(() => {
+    clearFullscreenApi();
+    vi.restoreAllMocks();
+  });
+
+  it("reports unsupported when the browser fullscreen api is unavailable", async () => {
+    clearFullscreenApi();
+
+    render(<HookHarness />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("supported")).toHaveTextContent("false");
+    });
+    expect(screen.getByTestId("fullscreen")).toHaveTextContent("false");
+  });
+
+  it("enters and exits fullscreen against the target element", async () => {
+    const api = installFullscreenApi();
+
+    render(<HookHarness />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("supported")).toHaveTextContent("true");
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "enter" }));
+
+    await waitFor(() => {
+      expect(api.requestFullscreen).toHaveBeenCalledTimes(1);
+      expect(screen.getByTestId("fullscreen")).toHaveTextContent("true");
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "exit" }));
+
+    await waitFor(() => {
+      expect(api.exitFullscreen).toHaveBeenCalledTimes(1);
+      expect(screen.getByTestId("fullscreen")).toHaveTextContent("false");
+    });
+  });
+
+  it("tracks fullscreenchange even when the browser exits fullscreen outside the button", async () => {
+    const api = installFullscreenApi();
+
+    render(<HookHarness />);
+
+    const target = await screen.findByTestId("fullscreen-target");
+
+    act(() => {
+      api.setFullscreenElement(target);
+    });
+
+    expect(screen.getByTestId("fullscreen")).toHaveTextContent("true");
+
+    act(() => {
+      api.setFullscreenElement(null);
+    });
+
+    expect(screen.getByTestId("fullscreen")).toHaveTextContent("false");
+  });
+
+  it("leaves the state in enter mode when requestFullscreen rejects", async () => {
+    installFullscreenApi();
+    const requestError = new Error("fullscreen denied");
+    const requestSpy = vi
+      .spyOn(HTMLElement.prototype, "requestFullscreen")
+      .mockRejectedValue(requestError);
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    render(<HookHarness />);
+
+    fireEvent.click(screen.getByRole("button", { name: "toggle" }));
+
+    await waitFor(() => {
+      expect(requestSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy).toHaveBeenCalledWith("Failed to enter fullscreen", requestError);
+    });
+
+    expect(screen.getByTestId("fullscreen")).toHaveTextContent("false");
+  });
+});