feat(run): add TerminalView xterm.js component for the PTY transport

- TerminalView.tsx: xterm.js component with WebSocket attachment to /ws-pty/:runId - Test: validates WS connection URL, incoming terminal data, and outgoing keystrokes - Added ResizeObserver stub to test-setup.ts for jsdom environment
2026-08-12 10:19:10 +07:00
parent 872c698132
commit 9b8d9bbe39
3 changed files with 168 additions and 0 deletions
@@ -0,0 +1,77 @@
+/**
+ * @file TerminalView.tsx
+ * @description Renders one lane's live terminal — a real `xterm.js` instance
+ * attached via WebSocket to the server's `/ws-pty/:runId` path (see
+ * server/lib/pty-attach.js), which is itself a `node-pty`-backed
+ * `tmux attach-session`. Binary WS frames are raw PTY bytes in both
+ * directions; a JSON text frame carries the initial `resize` on mount and
+ * the server's one-shot `exit` notice when the pane process ends.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+import { useEffect, useRef } from "react";
+import { Terminal } from "@xterm/xterm";
+import { FitAddon } from "@xterm/addon-fit";
+import "@xterm/xterm/css/xterm.css";
+
+interface TerminalViewProps {
+  runId: string;
+  wsBaseUrl: string;
+}
+
+export function TerminalView({ runId, wsBaseUrl }: TerminalViewProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const term = new Terminal({ convertEol: true, fontSize: 13, cursorBlink: true });
+    const fit = new FitAddon();
+    term.loadAddon(fit);
+    if (containerRef.current) term.open(containerRef.current);
+    fit.fit();
+
+    const ws = new WebSocket(`${wsBaseUrl}/ws-pty/${encodeURIComponent(runId)}`);
+
+    ws.onopen = () => {
+      ws.send(JSON.stringify({ type: "resize", cols: term.cols, rows: term.rows }));
+    };
+    ws.onmessage = (event) => {
+      if (typeof event.data === "string") {
+        // Binary PTY output arrives as text here too (the browser WS API
+        // decodes non-Blob/ArrayBuffer frames as strings) — a JSON control
+        // frame is the only thing that starts with `{"type"`.
+        if (event.data.startsWith('{"type"')) {
+          try {
+            const msg = JSON.parse(event.data);
+            if (msg.type === "exit") {
+              term.write(`\r\n[session ended, exit code ${msg.code}]\r\n`);
+            }
+            return;
+          } catch {
+            /* not JSON — fall through and render as PTY output */
+          }
+        }
+        term.write(event.data);
+      }
+    };
+
+    const dataDisposable = term.onData((data) => {
+      if (ws.readyState === WebSocket.OPEN) ws.send(data);
+    });
+
+    const resizeObserver = new ResizeObserver(() => {
+      fit.fit();
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: "resize", cols: term.cols, rows: term.rows }));
+      }
+    });
+    if (containerRef.current) resizeObserver.observe(containerRef.current);
+
+    return () => {
+      resizeObserver.disconnect();
+      dataDisposable.dispose();
+      ws.close();
+      term.dispose();
+    };
+  }, [runId, wsBaseUrl]);
+
+  return <div ref={containerRef} className="h-full w-full" data-testid="terminal-view" />;
+}
@@ -0,0 +1,84 @@
+/**
+ * @file TerminalView.test.tsx
+ * @description Tests for the xterm.js-backed terminal view: verifies it opens
+ * a WS connection to the right URL, writes incoming binary frames to the
+ * mocked terminal, and forwards typed input as outgoing binary frames.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { TerminalView } from "../TerminalView";
+
+const writeMock = vi.fn();
+const onDataHandlers: Array<(d: string) => void> = [];
+const openMock = vi.fn();
+const disposeMock = vi.fn();
+
+vi.mock("@xterm/xterm", () => ({
+  Terminal: vi.fn().mockImplementation(() => ({
+    open: openMock,
+    write: writeMock,
+    onData: (fn: (d: string) => void) => {
+      onDataHandlers.push(fn);
+      return { dispose: vi.fn() };
+    },
+    dispose: disposeMock,
+    loadAddon: vi.fn(),
+  })),
+}));
+vi.mock("@xterm/addon-fit", () => ({
+  FitAddon: vi.fn().mockImplementation(() => ({ fit: vi.fn() })),
+}));
+
+class MockWebSocket {
+  static instances: MockWebSocket[] = [];
+  url: string;
+  sent: unknown[] = [];
+  onopen: (() => void) | null = null;
+  onmessage: ((e: { data: unknown }) => void) | null = null;
+  onclose: (() => void) | null = null;
+  constructor(url: string) {
+    this.url = url;
+    MockWebSocket.instances.push(this);
+  }
+  send(data: unknown) {
+    this.sent.push(data);
+  }
+  close() {
+    this.onclose?.();
+  }
+}
+// @ts-expect-error test override
+global.WebSocket = MockWebSocket;
+
+describe("TerminalView", () => {
+  beforeEach(() => {
+    MockWebSocket.instances = [];
+    onDataHandlers.length = 0;
+    writeMock.mockClear();
+    openMock.mockClear();
+  });
+
+  afterEach(cleanup);
+
+  it("opens a WS connection to the run's ws-pty path", () => {
+    render(<TerminalView runId="ccam-lane-1" wsBaseUrl="ws://localhost:4820" />);
+    expect(MockWebSocket.instances).toHaveLength(1);
+    expect(MockWebSocket.instances[0].url).toBe("ws://localhost:4820/ws-pty/ccam-lane-1");
+  });
+
+  it("writes incoming WS data to the terminal", () => {
+    render(<TerminalView runId="ccam-lane-1" wsBaseUrl="ws://localhost:4820" />);
+    const ws = MockWebSocket.instances[0];
+    ws.onopen?.();
+    ws.onmessage?.({ data: "hello" });
+    expect(writeMock).toHaveBeenCalledWith("hello");
+  });
+
+  it("forwards terminal keystrokes as outgoing WS sends", () => {
+    render(<TerminalView runId="ccam-lane-1" wsBaseUrl="ws://localhost:4820" />);
+    const ws = MockWebSocket.instances[0];
+    onDataHandlers[0]("ls -la\r");
+    expect(ws.sent).toEqual(["ls -la\r"]);
+  });
+});