fix(web): restore debounced terminal resize after hydration

Author: pallyoung

e2e/specs/session-hydrate-refresh.spec.ts

@@ -12,6 +12,10 @@ const BACKEND_HTTP_URL = `http://${HOST}:${SERVER_PORT}`;
 const BASE_URL = `http://${HOST}:${WEB_PORT}`;
 const INTERRUPTED_SESSION_ID = "sess-hydrate-interrupted";
 const UNAVAILABLE_SESSION_ID = "sess-hydrate-unavailable";
+type TerminalTraceEntry = {
+  terminalId?: string;
+  event?: string;
+};
 let sandboxDir: string;
 let workspaceDir: string;
 let dbPath: string;
@@ -192,6 +196,65 @@ test.describe("session hydrate refresh acceptance", () => {
     await expect(unavailableTextarea).toHaveAttribute("readonly", "");
   });
 
+  test("desktop terminals refit once per terminal after rapid viewport resize", async ({
+    page,
+  }) => {
+    const traces: TerminalTraceEntry[] = [];
+
+    page.on("console", (message) => {
+      if (message.type() !== "debug") {
+        return;
+      }
+
+      void Promise.all(message.args().map((arg) => arg.jsonValue().catch(() => undefined))).then(
+        (args) => {
+          if (args[0] !== "[terminal-trace]") {
+            return;
+          }
+
+          const entry = args[1];
+          if (entry && typeof entry === "object") {
+            traces.push(entry as TerminalTraceEntry);
+          }
+        }
+      );
+    });
+
+    await page.addInitScript(() => {
+      window.localStorage.setItem("coderStudio.terminalTrace", "1");
+    });
+
+    await page.goto("/workspace");
+    await expect(page.getByTestId("workspace-resolving-shell")).toHaveCount(0, { timeout: 20000 });
+    await expect(page.locator(".session-card.agent-pane")).toHaveCount(2, { timeout: 20000 });
+
+    await expect
+      .poll(() => new Set(traces.map((entry) => entry.terminalId).filter(Boolean)).size)
+      .toBe(2);
+
+    await page.waitForTimeout(300);
+
+    const terminalCount = new Set(traces.map((entry) => entry.terminalId).filter(Boolean)).size;
+    const initialFitCount = traces.filter((entry) => entry.event === "fit").length;
+    const initialObserverCount = traces.filter((entry) => entry.event === "resize-observer").length;
+
+    await page.setViewportSize({ width: 1180, height: 800 });
+    await page.setViewportSize({ width: 1020, height: 800 });
+
+    await expect
+      .poll(() => traces.filter((entry) => entry.event === "resize-observer").length)
+      .toBeGreaterThan(initialObserverCount);
+
+    await expect
+      .poll(() => traces.filter((entry) => entry.event === "fit").length)
+      .toBe(initialFitCount + terminalCount);
+
+    await page.waitForTimeout(250);
+    expect(traces.filter((entry) => entry.event === "fit")).toHaveLength(
+      initialFitCount + terminalCount
+    );
+  });
+
   test("mobile restores the server-backed active session after refresh", async ({ browser }) => {
     const context = await browser.newContext({
       viewport: { width: 430, height: 932 },

packages/web/src/features/terminal-panel/__tests__/xterm-host.test.tsx

@@ -4174,6 +4174,175 @@ describe("XtermHost", () => {
     global.cancelAnimationFrame = originalCancelAnimationFrame;
   });
 
+  it("attaches the resize observer after desktop hydration is granted", async () => {
+    const store = createStore();
+    const sendCommand = vi.fn().mockImplementation((op: string) => {
+      if (op === "terminal.snapshot") {
+        return Promise.resolve({ status: "unsupported" });
+      }
+
+      if (op === "terminal.replay") {
+        return Promise.resolve({ status: "ok", seq: 0 });
+      }
+
+      return Promise.resolve({ status: "ok" });
+    });
+    const subscribe = vi.fn(() => vi.fn());
+    const observe = vi.fn();
+    const disconnect = vi.fn();
+    const originalResizeObserver = global.ResizeObserver;
+    const originalRequestAnimationFrame = global.requestAnimationFrame;
+    const originalCancelAnimationFrame = global.cancelAnimationFrame;
+
+    hydrationCoordinatorMocks.autoGrant = false;
+    mockTerminal.cols = 120;
+    mockTerminal.rows = 32;
+
+    class ResizeObserverMock {
+      observe = observe;
+      unobserve = vi.fn();
+      disconnect = disconnect;
+
+      constructor(_callback: ResizeObserverCallback) {}
+    }
+
+    global.ResizeObserver = ResizeObserverMock as unknown as typeof ResizeObserver;
+
+    global.requestAnimationFrame = vi.fn((callback: FrameRequestCallback) => {
+      callback(16);
+      return 1;
+    }) as typeof requestAnimationFrame;
+    global.cancelAnimationFrame = vi.fn() as typeof cancelAnimationFrame;
+
+    store.set(wsClientAtom, {
+      sendCommand,
+      subscribe,
+    } as never);
+
+    render(
+      <Provider store={store}>
+        <XtermHost terminalId="hydration-resize-terminal" workspaceId="test-workspace" />
+      </Provider>
+    );
+
+    expect(mockTerminal.open).not.toHaveBeenCalled();
+    expect(observe).not.toHaveBeenCalled();
+
+    await act(async () => {
+      hydrationCoordinatorMocks.resolveGranted();
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    await waitFor(() => {
+      expect(mockTerminal.open).toHaveBeenCalledTimes(1);
+    });
+
+    expect(observe).toHaveBeenCalledTimes(1);
+    expect(disconnect).not.toHaveBeenCalled();
+
+    global.ResizeObserver = originalResizeObserver;
+    global.requestAnimationFrame = originalRequestAnimationFrame;
+    global.cancelAnimationFrame = originalCancelAnimationFrame;
+  });
+
+  it("debounces resize-observer fits until resize settles", async () => {
+    const store = createStore();
+    const fontsReady = new Promise<void>(() => {});
+    Object.defineProperty(document, "fonts", {
+      configurable: true,
+      value: {
+        ready: fontsReady,
+      },
+    });
+    const sendCommand = vi.fn().mockImplementation((op: string) => {
+      if (op === "terminal.snapshot") {
+        return Promise.resolve({ status: "unsupported" });
+      }
+
+      if (op === "terminal.replay") {
+        return Promise.resolve({ status: "ok", seq: 0 });
+      }
+
+      return Promise.resolve({ status: "ok" });
+    });
+    const subscribe = vi.fn(() => vi.fn());
+    const originalResizeObserver = global.ResizeObserver;
+    const originalRequestAnimationFrame = global.requestAnimationFrame;
+    const originalCancelAnimationFrame = global.cancelAnimationFrame;
+    let resizeObserverCallback: ResizeObserverCallback | null = null;
+
+    hydrationCoordinatorMocks.autoGrant = false;
+    mockTerminal.cols = 120;
+    mockTerminal.rows = 32;
+
+    class ResizeObserverMock {
+      observe = vi.fn();
+      unobserve = vi.fn();
+      disconnect = vi.fn();
+
+      constructor(callback: ResizeObserverCallback) {
+        resizeObserverCallback = callback;
+      }
+    }
+
+    global.ResizeObserver = ResizeObserverMock as unknown as typeof ResizeObserver;
+
+    global.requestAnimationFrame = vi.fn((callback: FrameRequestCallback) => {
+      callback(16);
+      return 1;
+    }) as typeof requestAnimationFrame;
+    global.cancelAnimationFrame = vi.fn() as typeof cancelAnimationFrame;
+
+    store.set(wsClientAtom, {
+      sendCommand,
+      subscribe,
+    } as never);
+
+    render(
+      <Provider store={store}>
+        <XtermHost terminalId="debounced-resize-terminal" workspaceId="test-workspace" />
+      </Provider>
+    );
+
+    await act(async () => {
+      hydrationCoordinatorMocks.resolveGranted();
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(resizeObserverCallback).toBeTypeOf("function");
+
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+
+    mockFitAddon.fit.mockClear();
+
+    act(() => {
+      resizeObserverCallback?.([], {} as ResizeObserver);
+      resizeObserverCallback?.([], {} as ResizeObserver);
+      resizeObserverCallback?.([], {} as ResizeObserver);
+    });
+
+    act(() => {
+      vi.advanceTimersByTime(149);
+    });
+
+    expect(mockFitAddon.fit).not.toHaveBeenCalled();
+
+    act(() => {
+      vi.advanceTimersByTime(1);
+    });
+
+    expect(mockFitAddon.fit).toHaveBeenCalledTimes(1);
+
+    global.ResizeObserver = originalResizeObserver;
+    global.requestAnimationFrame = originalRequestAnimationFrame;
+    global.cancelAnimationFrame = originalCancelAnimationFrame;
+    vi.useRealTimers();
+  });
+
   it("waits for websocket connection before initial resize sync and snapshot recovery", async () => {
     const store = createStore();
     const snapshotChunk = new TextEncoder().encode("snapshot after connect\n");

packages/web/src/features/terminal-panel/views/shared/xterm-host.tsx

@@ -1612,7 +1612,7 @@ export function XtermHost({
         resizeDebounceRef.current = null;
       }
     };
-  }, [scheduleFit, terminalId]);
+  }, [hydrationState.kind, scheduleFit, terminalId]);
 
   /**
    * Focus terminal when it becomes active