feat: add VNC display zoom controls (#1314)

src/ui/features/guacamole/GuacamoleApp.tsx

@@ -166,6 +166,7 @@ const GuacamoleAppInner = React.forwardRef<
       : null,
   );
   const displayRef = useRef<GuacamoleDisplayHandle>(null);
+  const [displayZoom, setDisplayZoom] = useState(1);
   const [filesystem, setFilesystem] = useState<Guacamole.Object | null>(null);
   const [fileBrowserOpen, setFileBrowserOpen] = useState(false);
   const [pendingUploads, setPendingUploads] = useState<File[]>([]);
@@ -472,6 +473,7 @@ const GuacamoleAppInner = React.forwardRef<
             }),
           })
         }
+        onZoomChange={setDisplayZoom}
         onFilesystem={setFilesystem}
         onDropFiles={handleDropFiles}
         onDropUnavailable={handleDropUnavailable}
@@ -494,6 +496,7 @@ const GuacamoleAppInner = React.forwardRef<
         fileBrowserOpen={fileBrowserOpen}
         onToggleFileBrowser={() => setFileBrowserOpen((open) => !open)}
         onTouchModeChange={setTouchMode}
+        zoom={displayZoom}
       />
       {shareModalOpen && guacamoleConnectionId && (
         <ShareSessionModal

src/ui/features/guacamole/GuacamoleDisplay.tsx

@@ -31,6 +31,7 @@ import {
 } from "./guacamole-file-drop.ts";
 import { guacStateToStage } from "@/components/connection/connection-status.ts";
 import type { ConnectionStage } from "@/types/connection-log.ts";
+import { clampGuacamoleZoom, stepGuacamoleZoom } from "./guacamole-zoom.ts";
 
 export type GuacamoleConnectionType = "rdp" | "vnc" | "telnet";
 
@@ -56,6 +57,9 @@ export interface GuacamoleDisplayHandle {
   sendMouse: (x: number, y: number, buttonMask: number) => void;
   setClipboard: (data: string) => void;
   getFilesystem: () => Guacamole.Object | null;
+  zoomIn: () => number;
+  zoomOut: () => number;
+  resetZoom: () => number;
 }
 
 export type GuacamoleTouchMode = "touchscreen" | "touchpad";
@@ -72,6 +76,7 @@ interface GuacamoleDisplayProps {
   onDropFiles?: (files: File[]) => void;
   onDropUnavailable?: () => void;
   onStageChange?: (stage: ConnectionStage) => void;
+  onZoomChange?: (zoom: number) => void;
 }
 
 const isDev = import.meta.env.DEV;
@@ -92,6 +97,7 @@ export const GuacamoleDisplay = forwardRef<
     onDropFiles,
     onDropUnavailable,
     onStageChange,
+    onZoomChange,
   },
   ref,
 ) {
@@ -113,6 +119,8 @@ export const GuacamoleDisplay = forwardRef<
   onStageChangeRef.current = onStageChange;
   const keyboardRef = useRef<Guacamole.Keyboard | null>(null);
   const scaleRef = useRef<number>(1);
+  const fitScaleRef = useRef<number>(1);
+  const zoomRef = useRef<number>(1);
   const resizeTimeoutRef = useRef<NodeJS.Timeout | null>(null);
   const hasKeyboardFocusRef = useRef(false);
   const windowFocusedRef = useRef(
@@ -141,6 +149,24 @@ export const GuacamoleDisplay = forwardRef<
     }
   }, []);
 
+  const applyZoom = useCallback(
+    (nextZoom: number): number => {
+      const zoom = clampGuacamoleZoom(nextZoom);
+      zoomRef.current = zoom;
+      const display = clientRef.current?.getDisplay();
+      if (display && displayRef.current) {
+        const scale = fitScaleRef.current * zoom;
+        scaleRef.current = scale;
+        display.scale(scale);
+        displayRef.current.style.width = `${display.getWidth() * scale}px`;
+        displayRef.current.style.height = `${display.getHeight() * scale}px`;
+      }
+      onZoomChange?.(zoom);
+      return zoom;
+    },
+    [onZoomChange],
+  );
+
   useImperativeHandle(ref, () => ({
     disconnect: disconnectClient,
     isConnected: () => isReady && !hasError,
@@ -171,6 +197,9 @@ export const GuacamoleDisplay = forwardRef<
       }
     },
     getFilesystem: () => filesystemRef.current,
+    zoomIn: () => applyZoom(stepGuacamoleZoom(zoomRef.current, 1)),
+    zoomOut: () => applyZoom(stepGuacamoleZoom(zoomRef.current, -1)),
+    resetZoom: () => applyZoom(1),
   }));
 
   const getWebSocketConnection = useCallback(
@@ -315,34 +344,44 @@ export const GuacamoleDisplay = forwardRef<
     };
   }, [isVisible]);
 
-  const rescaleDisplay = useCallback((immediate: boolean = false) => {
+  const rescaleDisplay = useCallback(
-    if (!clientRef.current || !containerRef.current) return;
+    (immediate: boolean = false) => {
-
-    const performRescale = () => {
       if (!clientRef.current || !containerRef.current) return;
 
-      const display = clientRef.current.getDisplay();
+      const performRescale = () => {
-      const cWidth = containerRef.current.clientWidth;
+        if (!clientRef.current || !containerRef.current) return;
-      const cHeight = containerRef.current.clientHeight;
-      const displayWidth = display.getWidth();
-      const displayHeight = display.getHeight();
 
-      if (displayWidth > 0 && displayHeight > 0 && cWidth > 0 && cHeight > 0) {
+        const display = clientRef.current.getDisplay();
-        const scale = Math.min(cWidth / displayWidth, cHeight / displayHeight);
+        const cWidth = containerRef.current.clientWidth;
-        scaleRef.current = scale;
+        const cHeight = containerRef.current.clientHeight;
-        display.scale(scale);
+        const displayWidth = display.getWidth();
-      }
+        const displayHeight = display.getHeight();
-    };
 
-    if (immediate) {
+        if (
-      performRescale();
+          displayWidth > 0 &&
-    } else {
+          displayHeight > 0 &&
-      if (resizeTimeoutRef.current) {
+          cWidth > 0 &&
-        clearTimeout(resizeTimeoutRef.current);
+          cHeight > 0
+        ) {
+          fitScaleRef.current = Math.min(
+            cWidth / displayWidth,
+            cHeight / displayHeight,
+          );
+          applyZoom(zoomRef.current);
+        }
+      };
+
+      if (immediate) {
+        performRescale();
+      } else {
+        if (resizeTimeoutRef.current) {
+          clearTimeout(resizeTimeoutRef.current);
+        }
+        resizeTimeoutRef.current = setTimeout(performRescale, 200);
       }
-      resizeTimeoutRef.current = setTimeout(performRescale, 200);
+    },
-    }
+    [applyZoom],
-  }, []);
+  );
 
   const connect = useCallback(async () => {
     if (isConnectingRef.current) return;
@@ -762,6 +801,51 @@ export const GuacamoleDisplay = forwardRef<
     }
   }, [isVisible, isReady, syncClipboard]);
 
+  useEffect(() => {
+    const container = containerRef.current;
+    const protocol = connectionConfig.protocol ?? connectionConfig.type;
+    if (!container || !isReady || protocol !== "vnc") return;
+
+    let pinchDistance = 0;
+    let pinchZoom = zoomRef.current;
+    const distance = (touches: TouchList) =>
+      Math.hypot(
+        touches[0].clientX - touches[1].clientX,
+        touches[0].clientY - touches[1].clientY,
+      );
+    const onTouchStart = (event: TouchEvent) => {
+      if (event.touches.length !== 2) return;
+      event.preventDefault();
+      event.stopPropagation();
+      pinchDistance = distance(event.touches);
+      pinchZoom = zoomRef.current;
+    };
+    const onTouchMove = (event: TouchEvent) => {
+      if (event.touches.length !== 2 || pinchDistance === 0) return;
+      event.preventDefault();
+      event.stopPropagation();
+      applyZoom(pinchZoom * (distance(event.touches) / pinchDistance));
+    };
+    const onTouchEnd = () => {
+      pinchDistance = 0;
+    };
+
+    container.addEventListener("touchstart", onTouchStart, {
+      passive: false,
+      capture: true,
+    });
+    container.addEventListener("touchmove", onTouchMove, {
+      passive: false,
+      capture: true,
+    });
+    container.addEventListener("touchend", onTouchEnd, { capture: true });
+    return () => {
+      container.removeEventListener("touchstart", onTouchStart, true);
+      container.removeEventListener("touchmove", onTouchMove, true);
+      container.removeEventListener("touchend", onTouchEnd, true);
+    };
+  }, [applyZoom, connectionConfig.protocol, connectionConfig.type, isReady]);
+
   useEffect(() => {
     const container = containerRef.current;
     if (!container || !isReady) return;
@@ -818,7 +902,7 @@ export const GuacamoleDisplay = forwardRef<
   return (
     <div
       ref={containerRef}
-      className="absolute inset-0 overflow-hidden"
+      className="absolute inset-0 overflow-auto"
       style={{ backgroundColor: "var(--bg-base)" }}
       onDragEnter={handleDragEnter}
       onDragOver={(event) => {
@@ -829,7 +913,7 @@ export const GuacamoleDisplay = forwardRef<
     >
       <div
         ref={displayRef}
-        className="relative w-full h-full flex items-center justify-center"
+        className="relative flex min-h-full min-w-full items-center justify-center"
         style={{
           cursor: isReady ? "none" : "default",
           visibility: isReady ? "visible" : "hidden",

src/ui/features/guacamole/GuacamoleToolbar.tsx

@@ -16,6 +16,9 @@ import {
   FolderOpen,
   Touchpad,
   MousePointer,
+  ZoomIn,
+  ZoomOut,
+  Scan,
 } from "lucide-react";
 import {
   Tooltip,
@@ -38,6 +41,7 @@ interface GuacamoleToolbarProps {
   fileBrowserOpen?: boolean;
   onToggleFileBrowser?: () => void;
   onTouchModeChange?: (mode: GuacamoleTouchMode) => void;
+  zoom?: number;
 }
 
 const MODIFIER_KEYSYMS = {
@@ -73,6 +77,7 @@ function TipBtn({
       <TooltipTrigger asChild>
         <button
           type="button"
+          aria-label={tooltip}
           onClick={onClick}
           className={cn(BTN_BASE, className)}
         >
@@ -102,6 +107,7 @@ function TipIconBtn({
       <TooltipTrigger asChild>
         <button
           type="button"
+          aria-label={tooltip}
           onClick={onClick}
           className={cn(BTN_ICON, className)}
         >
@@ -123,6 +129,7 @@ export const GuacamoleToolbar: React.FC<GuacamoleToolbarProps> = ({
   fileBrowserOpen = false,
   onToggleFileBrowser,
   onTouchModeChange,
+  zoom = 1,
 }) => {
   const { t } = useTranslation();
   const [position, setPosition] = useState({ x: 0, y: 12 });
@@ -350,6 +357,37 @@ export const GuacamoleToolbar: React.FC<GuacamoleToolbarProps> = ({
               </>
             )}
 
+            {protocol === "vnc" && (
+              <>
+                <div className={SEP} />
+                <TipIconBtn
+                  tooltip={t("guacamole.toolbar.zoomOut")}
+                  onClick={() => displayRef.current?.zoomOut()}
+                >
+                  <ZoomOut className="size-3.5" />
+                </TipIconBtn>
+                <TipBtn
+                  tooltip={t("guacamole.toolbar.resetZoom")}
+                  onClick={() => displayRef.current?.resetZoom()}
+                  className="min-w-12 tabular-nums"
+                >
+                  {Math.round(zoom * 100)}%
+                </TipBtn>
+                <TipIconBtn
+                  tooltip={t("guacamole.toolbar.zoomIn")}
+                  onClick={() => displayRef.current?.zoomIn()}
+                >
+                  <ZoomIn className="size-3.5" />
+                </TipIconBtn>
+                <TipIconBtn
+                  tooltip={t("guacamole.toolbar.fitToScreen")}
+                  onClick={() => displayRef.current?.resetZoom()}
+                >
+                  <Scan className="size-3.5" />
+                </TipIconBtn>
+              </>
+            )}
+
             {/* System combos — RDP/VNC only */}
             {isRdpVnc && (
               <>

src/ui/features/guacamole/guacamole-zoom.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { clampGuacamoleZoom, stepGuacamoleZoom } from "./guacamole-zoom.js";
+
+describe("guacamole zoom", () => {
+  it("steps in predictable quarter increments", () => {
+    expect(stepGuacamoleZoom(1, 1)).toBe(1.25);
+    expect(stepGuacamoleZoom(1, -1)).toBe(0.75);
+  });
+
+  it("keeps toolbar and pinch zoom within usable bounds", () => {
+    expect(clampGuacamoleZoom(0.1)).toBe(0.5);
+    expect(clampGuacamoleZoom(8)).toBe(4);
+  });
+});

src/ui/features/guacamole/guacamole-zoom.ts

@@ -0,0 +1,11 @@
+export const MIN_GUACAMOLE_ZOOM = 0.5;
+export const MAX_GUACAMOLE_ZOOM = 4;
+export const GUACAMOLE_ZOOM_STEP = 0.25;
+
+export function clampGuacamoleZoom(zoom: number): number {
+  return Math.min(MAX_GUACAMOLE_ZOOM, Math.max(MIN_GUACAMOLE_ZOOM, zoom));
+}
+
+export function stepGuacamoleZoom(zoom: number, direction: -1 | 1): number {
+  return clampGuacamoleZoom(zoom + direction * GUACAMOLE_ZOOM_STEP);
+}

src/ui/locales/en.json

@@ -1908,6 +1908,10 @@
       "collapse": "Collapse toolbar",
       "expand": "Expand toolbar",
       "dragHandle": "Drag to reposition",
+      "zoomIn": "Zoom in",
+      "zoomOut": "Zoom out",
+      "resetZoom": "Reset zoom",
+      "fitToScreen": "Fit to screen",
       "switchToTrackpad": "Switch to trackpad mode (drag to move cursor, tap to click)",
       "switchToTouch": "Switch to touch mode (tap directly where you want to click)"
     }

src/ui/tests/features/guacamole/GuacamoleToolbar.test.tsx

@@ -19,6 +19,9 @@ describe("GuacamoleToolbar Windows key", () => {
         sendMouse: vi.fn(),
         setClipboard: vi.fn(),
         getFilesystem: () => null,
+        zoomIn: vi.fn(() => 1.25),
+        zoomOut: vi.fn(() => 0.75),
+        resetZoom: vi.fn(() => 1),
       } satisfies GuacamoleDisplayHandle,
     } as React.RefObject<GuacamoleDisplayHandle>;
     const { getByText } = render(
@@ -44,4 +47,33 @@ describe("GuacamoleToolbar Windows key", () => {
     fireEvent.click(getByText("guacamole.toolbar.win"));
     expect(sendKey).toHaveBeenCalledWith(0xffeb, true);
   });
+
+  it("exposes VNC zoom controls without showing them for RDP", () => {
+    const zoomIn = vi.fn(() => 1.25);
+    const zoomOut = vi.fn(() => 0.75);
+    const resetZoom = vi.fn(() => 1);
+    const displayRef = {
+      current: {
+        disconnect: vi.fn(),
+        isConnected: () => true,
+        sendKey: vi.fn(),
+        sendMouse: vi.fn(),
+        setClipboard: vi.fn(),
+        getFilesystem: () => null,
+        zoomIn,
+        zoomOut,
+        resetZoom,
+      } satisfies GuacamoleDisplayHandle,
+    } as React.RefObject<GuacamoleDisplayHandle>;
+    const { getByLabelText, getByText } = render(
+      <GuacamoleToolbar displayRef={displayRef} protocol="vnc" zoom={1.25} />,
+    );
+
+    fireEvent.click(getByLabelText("guacamole.toolbar.zoomOut"));
+    fireEvent.click(getByLabelText("guacamole.toolbar.zoomIn"));
+    fireEvent.click(getByText("125%"));
+    expect(zoomOut).toHaveBeenCalledOnce();
+    expect(zoomIn).toHaveBeenCalledOnce();
+    expect(resetZoom).toHaveBeenCalledOnce();
+  });
 });