remo-cli 2.2.0rc4__tar.gz → 2.2.0rc6__tar.gz

{remo_cli-2.2.0rc4 → remo_cli-2.2.0rc6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remo-cli
-Version: 2.2.0rc4
+Version: 2.2.0rc6
 Summary: Remote development environment CLI
 License-Expression: MIT
 License-File: LICENSE

{remo_cli-2.2.0rc4 → remo_cli-2.2.0rc6}/docs/web-session-interface.md

@@ -102,8 +102,12 @@ The SPA is a two-pane **web console**:
   row (or its `+` button) **adds** it to a responsive grid (1/2/3 columns by count). Clicking a grid
   tile solos it; **Esc** collapses the grid back to the focused terminal; number keys **1–9** jump to
   the numbered sessions (⌘ 1–9 add to the grid). Hidden terminals stay connected and keep their
-  scrollback. Each terminal header shows `provider · instance · region`, connection state, and
-  reconnect/close controls.
+  scrollback. Each terminal header shows `provider · instance · region`, connection state, and a
+  window-control cluster of the display modes — **▭ Normal** (single view), **⊞ Grid** (the grid, when
+  one is available), **⤢ Fullscreen** (the terminal fills the whole window — shell chrome hidden, plus
+  best-effort browser fullscreen), and **✕ Close** — with the current mode shown active. Press **f** to
+  toggle fullscreen on the focused terminal; **Esc** exits it. Fullscreen is a presentation overlay: it
+  never disturbs the single/grid layout underneath, so exiting returns to exactly where you were.
 
 **Session-row glyphs** (also shown in the rail legend):
 

{remo_cli-2.2.0rc4 → remo_cli-2.2.0rc6}/frontend/src/api/client.ts

@@ -101,11 +101,82 @@ interface ErrorEnvelope {
   error: TypedError;
 }
 
+// ---- Forward-auth (SSO proxy) re-authentication ----
+//
+// When remo-web is deployed behind a whole-app forward-auth proxy (Traefik
+// ForwardAuth + an OIDC IdP such as Authentik — e.g. a Hola app), an
+// unauthenticated or expired-session request is answered with a 302 to the
+// cross-origin IdP (`https://auth.example.com/application/o/authorize/...`). A
+// same-origin `fetch()` cannot complete that SSO round-trip, and remo-web's
+// strict `connect-src 'self'` CSP blocks following the redirect at all — so the
+// only way to restore the session is a TOP-LEVEL navigation, which re-triggers
+// the proxy's SSO flow (the browser CAN follow it through the IdP and back).
+//
+// `request()` uses `redirect: "manual"` so such a redirect surfaces as an opaque
+// response (`response.type === "opaqueredirect"`, status 0) instead of throwing
+// on the blocked cross-origin follow; we then reload the document to re-auth. A
+// sessionStorage cooldown prevents a reload loop when auth genuinely can't
+// complete. With no proxy (REMO_WEB_OPERATOR_AUTH=none) there are no redirects,
+// so this path never fires.
+
+const _REAUTH_KEY = "remo:last-reauth";
+const _REAUTH_COOLDOWN_MS = 10_000;
+
+/**
+ * Handle a forward-auth challenge on an XHR by re-authenticating through a
+ * top-level navigation. Never returns normally: it either navigates the whole
+ * document (throwing to halt the caller before the navigation lands) or, if we
+ * already tried to re-auth within the cooldown, throws a clear `auth_required`
+ * ApiError instead of looping.
+ */
+function reauthenticate(): never {
+  let last = 0;
+  try {
+    last = Number(sessionStorage.getItem(_REAUTH_KEY) ?? 0) || 0;
+  } catch {
+    last = 0;
+  }
+  const now = Date.now();
+  if (now - last < _REAUTH_COOLDOWN_MS) {
+    // We just reloaded to re-auth and are being challenged again — the SSO
+    // round-trip isn't restoring a usable session. Stop reloading; surface a
+    // clear error rather than looping.
+    throw new ApiError({
+      code: "auth_required",
+      message: "Sign-in is required, but the access proxy did not restore a session.",
+      retryable: false,
+      remediation:
+        "Sign in through your access proxy and reload. If this repeats, the " +
+        "forward-auth proxy may be misconfigured (its session cookie is not reaching this app).",
+    });
+  }
+  try {
+    sessionStorage.setItem(_REAUTH_KEY, String(now));
+  } catch {
+    // sessionStorage unavailable — navigate anyway.
+  }
+  // A full document request re-runs the proxy's SSO redirect chain (IdP round
+  // trip), unlike a fetch which cannot. The SPA reloads authenticated and
+  // subsequent XHRs return 200.
+  window.location.assign(window.location.href);
+  // location.assign() schedules the navigation asynchronously and lets sync
+  // code keep running; throw so the caller never treats this as data.
+  throw new ApiError({
+    code: "auth_challenge",
+    message: "Re-authenticating…",
+    retryable: false,
+    remediation: "",
+  });
+}
+
 async function request<T>(path: string, init?: RequestInit): Promise<T> {
   let response: Response;
   try {
     response = await fetch(path, {
       ...init,
+      // Catch a forward-auth proxy's cross-origin SSO redirect as an opaque
+      // response instead of a thrown CSP-blocked follow (see reauthenticate()).
+      redirect: "manual",
       headers: {
         "Content-Type": "application/json",
         ...(init?.headers ?? {}),
@@ -123,6 +194,14 @@ async function request<T>(path: string, init?: RequestInit): Promise<T> {
     });
   }
 
+  // A forward-auth session lapse: the proxy answered with a cross-origin 3xx,
+  // now an opaque redirect. Re-authenticate via a top-level navigation rather
+  // than surfacing a bogus "network_error"/CSP failure. The API itself never
+  // issues same-origin redirects, so this is unambiguously a proxy challenge.
+  if (response.type === "opaqueredirect") {
+    reauthenticate();
+  }
+
   if (!response.ok) {
     let envelope: ErrorEnvelope | undefined;
     try {
@@ -355,6 +434,12 @@ export async function closeTerminal(terminalId: string): Promise<void> {
  *
  * This function only constructs and returns the socket; connection-lifecycle
  * and control-frame handling live in `terminal/TerminalConnection.ts`.
+ *
+ * Forward-auth note: a raw WebSocket upgrade cannot itself distinguish a proxy
+ * SSO redirect/401 from an ordinary failure. It does not need to — every attach
+ * (and reconnect) first calls `createTerminal()`, which goes through
+ * `request()` and so triggers the top-level SSO re-auth (see `reauthenticate`)
+ * whenever the session has lapsed, before/at the point the socket is opened.
  */
 export function openTerminalSocket(terminalId: string, token: string): WebSocket {
   const wsProtocol = window.location.protocol === "https:" ? "wss:" : "ws:";

{remo_cli-2.2.0rc4 → remo_cli-2.2.0rc6}/frontend/src/components/AppShell.css

@@ -32,6 +32,13 @@
   display: flex;
 }
 
+/* Fullscreen terminal: the shell collapses to just the pane. The rail/divider/
+ * backbar are already withheld from render (see AppShell); here we drop the top
+ * bar so the maximized terminal fills the whole viewport. */
+.app-shell--maximized .topbar {
+  display: none;
+}
+
 .app-rail {
   flex: none;
   flex-direction: column;

{remo_cli-2.2.0rc4 → remo_cli-2.2.0rc6}/frontend/src/components/AppShell.tsx

@@ -5,6 +5,7 @@
 
 import { useCallback, useEffect, useMemo, useState, type PointerEvent } from "react";
 import type { SessionTarget } from "../api/client";
+import { exitBrowserFullscreen } from "../lib/fullscreen";
 import { useDiscovery } from "../state/discovery";
 import { useHealth } from "../state/health";
 import { settingsActions, useSettings } from "../state/settings";
@@ -42,6 +43,36 @@ export function AppShell(): JSX.Element {
     return () => window.removeEventListener("resize", onResize);
   }, []);
 
+  // A terminal is fullscreen when the overlay id still resolves to an attached
+  // card; that both hides the shell chrome (class below) and drives browser
+  // fullscreen. Entering browser fullscreen is requested from the click/keypress
+  // gesture (WorkspacePane / keyboard); here we own the two exit paths:
+  //   (a) whenever the overlay clears through ANY path, leave browser fullscreen;
+  //   (b) when the user leaves browser fullscreen natively (Esc/F11), clear the
+  //       overlay so the shell chrome comes back.
+  const maximized =
+    workspace.maximizedId !== null && workspace.attached.includes(workspace.maximizedId);
+  const restore = workspace.restore;
+
+  useEffect(() => {
+    if (!maximized) {
+      exitBrowserFullscreen();
+    }
+  }, [maximized]);
+
+  useEffect(() => {
+    if (typeof document === "undefined") {
+      return undefined;
+    }
+    const onChange = (): void => {
+      if (!document.fullscreenElement && maximized) {
+        restore();
+      }
+    };
+    document.addEventListener("fullscreenchange", onChange);
+    return () => document.removeEventListener("fullscreenchange", onChange);
+  }, [maximized, restore]);
+
   const filters: RailFilters = useMemo(
     () => ({ search, providerFilter, sessionOnly }),
     [search, providerFilter, sessionOnly],
@@ -136,9 +167,11 @@ export function AppShell(): JSX.Element {
   );
 
   const paneHasContent = workspace.attached.length > 0;
-  const railHidden = narrow ? paneHasContent : settings.railCollapsed;
+  // Fullscreen collapses the shell to just the maximized terminal: rail and
+  // divider gone, top bar hidden by the .app-shell--maximized class.
+  const railHidden = maximized || (narrow ? paneHasContent : settings.railCollapsed);
   const paneHidden = narrow && !paneHasContent;
-  const showDivider = !narrow && !settings.railCollapsed;
+  const showDivider = !narrow && !settings.railCollapsed && !maximized;
 
   // "Loading" until the first discovery has produced instances — either before
   // the first poll (lastRefreshedAt null) or while a refresh is still in flight
@@ -151,7 +184,7 @@ export function AppShell(): JSX.Element {
   const noCredentials = health.checks.ssh_identity === "missing";
 
   return (
-    <div className="app-shell">
+    <div className={`app-shell${maximized ? " app-shell--maximized" : ""}`}>
       <TopBar
         showRailToggle={!narrow}
         railCollapsed={settings.railCollapsed}
@@ -165,7 +198,7 @@ export function AppShell(): JSX.Element {
         onShortcuts={onToggleShortcuts}
       />
 
-      {discovery.isRefreshing && (
+      {discovery.isRefreshing && !maximized && (
         <div className="app-refresh-bar">
           <div className="app-refresh-bar-fill" />
         </div>
@@ -203,7 +236,7 @@ export function AppShell(): JSX.Element {
         )}
 
         <div className="app-pane" style={{ display: paneHidden ? "none" : "flex" }}>
-          {narrow && paneHasContent && (
+          {narrow && paneHasContent && !maximized && (
             <div className="app-backbar">
               <button
                 type="button"

{remo_cli-2.2.0rc4 → remo_cli-2.2.0rc6}/frontend/src/components/ShortcutsModal.tsx

@@ -9,7 +9,8 @@ interface ShortcutsModalProps {
 const SHORTCUTS: { desc: string; key: string }[] = [
   { desc: "Open session 1–9 (single)", key: "1 – 9" },
   { desc: "Add session to grid", key: "⌘ 1–9" },
-  { desc: "Collapse grid to focused", key: "esc" },
+  { desc: "Fullscreen focused terminal", key: "f" },
+  { desc: "Exit fullscreen / collapse grid", key: "esc" },
   { desc: "Show this panel", key: "?" },
 ];
 

{remo_cli-2.2.0rc4 → remo_cli-2.2.0rc6}/frontend/src/components/TerminalCard.css

@@ -141,11 +141,49 @@
   background: var(--bg-btn-hover);
 }
 
-.terminal-card--grid .tc-btn--close {
+/* Window-control cluster: a tight row of square, icon-only mode buttons. */
+.tc-winctl {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+}
+
+.tc-btn--icon {
+  width: 26px;
+  height: 26px;
+  padding: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 13px;
+  line-height: 1;
+}
+
+.terminal-card--grid .tc-btn--icon {
   width: 22px;
   height: 22px;
-  padding: 0;
-  font-size: 10px;
+  font-size: 11px;
+}
+
+/* Current display mode: highlighted (and disabled — you can't re-enter it). */
+.tc-btn--active {
+  border-color: color-mix(in oklch, var(--accent) 55%, var(--border-strong));
+  background: color-mix(in oklch, var(--accent) 18%, transparent);
+  color: color-mix(in oklch, var(--accent) 82%, white);
+}
+
+/* Unavailable modes (e.g. Grid with no grid to show) read as inert. */
+.tc-btn--icon:disabled {
+  cursor: default;
+}
+.tc-btn--icon:disabled:not(.tc-btn--active) {
+  opacity: 0.4;
+}
+.tc-btn--icon:disabled:hover {
+  background: var(--bg-btn);
+}
+.tc-btn--active:disabled:hover {
+  background: color-mix(in oklch, var(--accent) 18%, transparent);
 }
 
 .tc-btn--accent {
@@ -193,9 +231,14 @@
     padding: 8px 13px;
     font-size: 13px;
   }
-  .terminal-card--grid .tc-btn--close {
-    width: 32px;
-    height: 32px;
-    font-size: 13px;
+  .tc-btn--icon,
+  .terminal-card--grid .tc-btn--icon {
+    width: 34px;
+    height: 34px;
+    padding: 0;
+    font-size: 15px;
+  }
+  .tc-winctl {
+    gap: 7px;
   }
 }

{remo_cli-2.2.0rc4 → remo_cli-2.2.0rc6}/frontend/src/components/TerminalCard.tsx

@@ -38,6 +38,9 @@ const STATE_LABELS: Record<TerminalConnectionState, string> = {
 };
 
 export type TerminalCardMode = "single" | "grid";
+/** Which of the mutually-exclusive display modes this card is currently in.
+ * Drives the window-control cluster's active/disabled state. */
+export type TerminalViewState = "normal" | "grid" | "fullscreen";
 
 interface TerminalCardProps {
   target: SessionTarget;
@@ -50,11 +53,17 @@ interface TerminalCardProps {
   isFocused: boolean;
   /** 1-based position label shown on a grid tile. */
   num?: number;
+  /** The display mode this card is currently in (window-control cluster state). */
+  viewState: TerminalViewState;
   onClose: () => void;
   /** Grid tile clicked → solo it (single view). */
   onSolo?: () => void;
-  /** Single view "Back to grid" — omitted when there's no grid to return to. */
-  onBackToGrid?: () => void;
+  /** Window-control "Normal": solo this terminal into the single view. */
+  onNormal: () => void;
+  /** Window-control "Grid": show the grid — omitted when none is available. */
+  onGrid?: () => void;
+  /** Window-control "Fullscreen": enter fullscreen, or exit if already in it. */
+  onToggleFullscreen: () => void;
   /** Called when the user clicks into the surface (focus this terminal). */
   onFocusRequest?: () => void;
   /** Called when output arrives while this card is hidden (rail activity dot). */
@@ -80,9 +89,12 @@ export function TerminalCard({
   isVisible,
   isFocused,
   num,
+  viewState,
   onClose,
   onSolo,
-  onBackToGrid,
+  onNormal,
+  onGrid,
+  onToggleFullscreen,
   onFocusRequest,
   onActivity,
   onEnded,
@@ -298,44 +310,81 @@ export function TerminalCard({
           {STATE_LABELS[connectionState]}
         </span>
         <div className="terminal-card-controls">
-          {mode === "single" && onBackToGrid && (
+          {needsManualReconnect && (
             <button
               type="button"
-              className="tc-btn"
-              title="Return to the grid you came from"
+              className="tc-btn tc-btn--accent"
+              data-testid={`terminal-reconnect-${target.id}`}
               onClick={(e) => {
                 e.stopPropagation();
-                onBackToGrid();
+                handleReconnect();
               }}
             >
-              ⊞ Grid
+              ↻ Reconnect
             </button>
           )}
-          {needsManualReconnect && (
+          {/* Window-control cluster: mutually-exclusive display modes (the
+           * current one shown active + disabled) plus close. Fullscreen toggles.
+           * Icons only; the label is the tooltip. */}
+          <div className="tc-winctl" role="group" aria-label="Terminal display mode">
             <button
               type="button"
-              className="tc-btn tc-btn--accent"
-              data-testid={`terminal-reconnect-${target.id}`}
+              className={`tc-btn tc-btn--icon${viewState === "normal" ? " tc-btn--active" : ""}`}
+              data-testid={`terminal-normal-${target.id}`}
+              title="Normal (single view)"
+              aria-label="Normal view"
+              aria-pressed={viewState === "normal"}
+              disabled={viewState === "normal"}
               onClick={(e) => {
                 e.stopPropagation();
-                handleReconnect();
+                onNormal();
               }}
             >
-              ↻ Reconnect
+              ▭
             </button>
-          )}
-          <button
-            type="button"
-            className="tc-btn tc-btn--close"
-            data-testid={`terminal-close-${target.id}`}
-            title="Close terminal — remote Zellij session stays alive"
-            onClick={(e) => {
-              e.stopPropagation();
-              handleClose();
-            }}
-          >
-            {mode === "grid" ? "✕" : "Close"}
-          </button>
+            <button
+              type="button"
+              className={`tc-btn tc-btn--icon${viewState === "grid" ? " tc-btn--active" : ""}`}
+              data-testid={`terminal-grid-${target.id}`}
+              title="Grid view"
+              aria-label="Grid view"
+              aria-pressed={viewState === "grid"}
+              disabled={viewState === "grid" || !onGrid}
+              onClick={(e) => {
+                e.stopPropagation();
+                onGrid?.();
+              }}
+            >
+              ⊞
+            </button>
+            <button
+              type="button"
+              className={`tc-btn tc-btn--icon${viewState === "fullscreen" ? " tc-btn--active" : ""}`}
+              data-testid={`terminal-fullscreen-${target.id}`}
+              title={viewState === "fullscreen" ? "Exit fullscreen" : "Fullscreen"}
+              aria-label={viewState === "fullscreen" ? "Exit fullscreen" : "Fullscreen"}
+              aria-pressed={viewState === "fullscreen"}
+              onClick={(e) => {
+                e.stopPropagation();
+                onToggleFullscreen();
+              }}
+            >
+              {viewState === "fullscreen" ? "⤡" : "⤢"}
+            </button>
+            <button
+              type="button"
+              className="tc-btn tc-btn--icon tc-btn--close"
+              data-testid={`terminal-close-${target.id}`}
+              title="Close terminal — remote Zellij session stays alive"
+              aria-label="Close terminal"
+              onClick={(e) => {
+                e.stopPropagation();
+                handleClose();
+              }}
+            >
+              ✕
+            </button>
+          </div>
         </div>
       </header>
 

{remo_cli-2.2.0rc4 → remo_cli-2.2.0rc6}/frontend/src/components/WorkspacePane.tsx

@@ -4,6 +4,7 @@
 
 import { useMemo } from "react";
 import type { SessionTarget } from "../api/client";
+import { requestBrowserFullscreen } from "../lib/fullscreen";
 import { useWorkspace } from "../state/workspace";
 import { TerminalCard } from "./TerminalCard";
 import "./WorkspacePane.css";
@@ -43,7 +44,7 @@ export function WorkspacePane({
   narrow,
 }: WorkspacePaneProps): JSX.Element {
   const workspace = useWorkspace();
-  const { attached, visible, focusedId, prevGrid } = workspace;
+  const { attached, visible, focusedId, prevGrid, maximizedId } = workspace;
 
   // Only attached ids that still resolve to a live target get a card.
   const attachedTargets = useMemo(
@@ -70,18 +71,40 @@ export function WorkspacePane({
     );
   }
 
-  const mode = visible.length <= 1 ? "single" : "grid";
+  // Fullscreen is an orthogonal overlay: it only takes effect when it still
+  // resolves to an attached card. When active, that one card fills the pane and
+  // the single↔grid layout underneath is left untouched (so exiting restores it).
+  const maximized =
+    maximizedId !== null && attached.includes(maximizedId) ? maximizedId : null;
+
+  // Cards render as single (full-bleed) while a card is maximized; otherwise the
+  // usual single↔grid split by how many are visible.
+  const mode = maximized || visible.length <= 1 ? "single" : "grid";
   const cols = gridColumns(visible.length, narrow);
   const rows = Math.max(1, Math.ceil(visible.length / cols));
-  const canBackToGrid = (prevGrid ?? []).filter((id) => attached.includes(id)).length > 1;
+  // The Grid control is available when a grid can be shown — either the visible
+  // set is already a grid (fullscreen opened over one) or a grid was remembered.
+  const canGrid =
+    visible.filter((id) => attached.includes(id)).length > 1 ||
+    (prevGrid ?? []).filter((id) => attached.includes(id)).length > 1;
 
   // 1-based position for each visible id (grid tile number badge).
   const visibleIndex = new Map(visible.map((id, i) => [id, i + 1]));
 
+  const toggleFullscreen = (id: string): void => {
+    if (maximized === id) {
+      workspace.restore();
+    } else {
+      workspace.maximize(id);
+      // Request from within this click gesture so the browser allows it.
+      requestBrowserFullscreen();
+    }
+  };
+
   return (
     <main className="workspace" data-testid="workspace">
       <div
-        className={`workspace-body workspace-body--${mode}`}
+        className={`workspace-body workspace-body--${mode}${maximized ? " workspace-body--maximized" : ""}`}
         style={
           mode === "grid"
             ? {
@@ -92,7 +115,8 @@ export function WorkspacePane({
         }
       >
         {attachedTargets.map((target) => {
-          const isVisible = visible.includes(target.id);
+          const isVisible = maximized ? target.id === maximized : visible.includes(target.id);
+          const viewState = maximized === target.id ? "fullscreen" : mode === "grid" ? "grid" : "normal";
           return (
             <TerminalCard
               key={target.id}
@@ -102,9 +126,12 @@ export function WorkspacePane({
               isVisible={isVisible}
               isFocused={focusedId === target.id}
               num={visibleIndex.get(target.id)}
+              viewState={viewState}
               onClose={() => workspace.closeTerm(target.id)}
               onSolo={mode === "grid" ? () => workspace.soloTile(target.id) : undefined}
-              onBackToGrid={mode === "single" && canBackToGrid ? workspace.backToGrid : undefined}
+              onNormal={() => workspace.soloTile(target.id)}
+              onGrid={canGrid ? workspace.backToGrid : undefined}
+              onToggleFullscreen={() => toggleFullscreen(target.id)}
               onFocusRequest={() => workspace.setFocused(target.id)}
               onActivity={() => workspace.markUnread(target.id)}
               onEnded={() => onTerminalEnded(target)}

remo_cli-2.2.0rc6/frontend/src/lib/fullscreen.ts

@@ -0,0 +1,38 @@
+// Best-effort browser (F11-style) fullscreen helpers.
+//
+// These are a thin, defensive wrapper over the Fullscreen API. The web-app's
+// "fullscreen" terminal mode is primarily an *app-viewport* takeover (the shell
+// hides its chrome via a CSS class keyed on `workspace.maximizedId`); requesting
+// true browser fullscreen on top of that is a best-effort enhancement:
+//
+//   - `requestBrowserFullscreen()` MUST be called from within a user-gesture
+//     handler (a click or keydown) — browsers reject it otherwise. On rejection
+//     the app-viewport takeover still stands, so the caller needs no fallback.
+//   - Exiting is centralized in AppShell (an effect keyed on `maximizedId`), so
+//     every exit path — the restore button, `f`, Esc, closing the card, or
+//     opening another session — funnels through `exitBrowserFullscreen()`.
+//
+// Both calls are idempotent: they guard on `document.fullscreenElement`, so
+// double-invoking (e.g. our exit effect firing after a native Esc already left
+// fullscreen) is a no-op and never loops.
+
+export function requestBrowserFullscreen(): void {
+  if (typeof document === "undefined") {
+    return;
+  }
+  const el = document.documentElement;
+  if (!document.fullscreenElement && el.requestFullscreen) {
+    // Swallow rejections: no gesture / disallowed by the browser just means we
+    // stay in the app-viewport takeover.
+    void el.requestFullscreen().catch(() => {});
+  }
+}
+
+export function exitBrowserFullscreen(): void {
+  if (typeof document === "undefined") {
+    return;
+  }
+  if (document.fullscreenElement && document.exitFullscreen) {
+    void document.exitFullscreen().catch(() => {});
+  }
+}

{remo_cli-2.2.0rc4 → remo_cli-2.2.0rc6}/frontend/src/state/useConsoleKeyboard.ts

@@ -2,14 +2,16 @@
 //
 //   1–9            open that numbered session solo (single view)
 //   ⌘/Ctrl/Shift 1–9  add/toggle that session in the grid
-//   Esc            close an open overlay, else collapse the grid to the
-//                  focused terminal
+//   f              toggle fullscreen on the focused terminal
+//   Esc            close an open overlay, else exit fullscreen, else collapse
+//                  the grid to the focused terminal
 //   ?              toggle the shortcuts panel
 //
 // Ignored while typing in an <input>/<textarea> (e.g. the rail search).
 
 import { useEffect } from "react";
 import type { SessionTarget } from "../api/client";
+import { requestBrowserFullscreen } from "../lib/fullscreen";
 import type { UseWorkspaceResult } from "./workspace";
 
 export interface ConsoleKeyboardConfig {
@@ -45,6 +47,11 @@ export function useConsoleKeyboard(config: ConsoleKeyboardConfig): void {
         if (onEscapeOverlay()) {
           return;
         }
+        // Exit fullscreen before touching the single/grid layout.
+        if (workspace.maximizedId) {
+          workspace.restore();
+          return;
+        }
         // Collapse a grid to just the focused terminal.
         if (workspace.visible.length > 1 && workspace.focusedId) {
           workspace.soloTile(workspace.focusedId);
@@ -52,6 +59,23 @@ export function useConsoleKeyboard(config: ConsoleKeyboardConfig): void {
         return;
       }
 
+      // Fullscreen the focused terminal (toggle). Requesting browser fullscreen
+      // here works because a keydown is a user gesture.
+      if (e.key === "f" || e.key === "F") {
+        const id = workspace.focusedId;
+        if (!id) {
+          return;
+        }
+        e.preventDefault();
+        if (workspace.maximizedId === id) {
+          workspace.restore();
+        } else {
+          workspace.maximize(id);
+          requestBrowserFullscreen();
+        }
+        return;
+      }
+
       if (/^[1-9]$/.test(e.key)) {
         const target = flatOpenable[Number(e.key) - 1];
         if (!target) {