From 4db342f49645082a429c49fb3e783d2fcdb15ea6 Mon Sep 17 00:00:00 2001
From: waclaude <colemurray.cs+ghwaclaude@gmail.com>
Date: Sat, 1 Aug 2026 16:14:24 +0000
Subject: [PATCH] fix: prevent hydration drift and improve form semantics

---
 .../web/src/app/(app)/session/[id]/page.tsx   | 47 +++++++++++++----
 .../automations/automation-form.tsx           |  8 ++-
 .../components/settings/sandbox-settings.tsx  | 25 +++++-----
 .../web/src/hooks/use-session-attachments.ts  | 50 +++++++++++--------
 .../hooks/use-session-participant-profiles.ts | 16 +++---
 packages/web/src/hooks/use-session-socket.ts  | 27 ++++++----
 6 files changed, 112 insertions(+), 61 deletions(-)

diff --git a/packages/web/src/app/(app)/session/[id]/page.tsx b/packages/web/src/app/(app)/session/[id]/page.tsx
index 06a11d4d8d..b29e5d2f44 100644
--- a/packages/web/src/app/(app)/session/[id]/page.tsx
+++ b/packages/web/src/app/(app)/session/[id]/page.tsx
@@ -3,7 +3,15 @@
 import { useParams, useRouter, useSearchParams } from "next/navigation";
 import { mutate } from "swr";
 import useSWRMutation from "swr/mutation";
-import { Suspense, useState, useRef, useEffect, useCallback, useMemo } from "react";
+import {
+  Suspense,
+  useState,
+  useRef,
+  useEffect,
+  useCallback,
+  useMemo,
+  useSyncExternalStore,
+} from "react";
 import { useSessionSocket } from "@/hooks/use-session-socket";
 import { SessionTimeline } from "@/components/session-timeline";
 import { MediaLightbox } from "@/components/media-lightbox";
@@ -52,6 +60,27 @@ import { useBrowserLayoutStorage } from "@/hooks/use-browser-layout-storage";
 import { focusSessionDetailsTrigger } from "@/lib/session-details-focus";
 import { useSessionParticipantProfiles } from "@/hooks/use-session-participant-profiles";
 
+const TERMINAL_VISIBILITY_KEY = "terminal-visible";
+const TERMINAL_VISIBILITY_EVENT = "terminal-visibility-change";
+
+function subscribeToTerminalVisibility(onStoreChange: () => void) {
+  window.addEventListener("storage", onStoreChange);
+  window.addEventListener(TERMINAL_VISIBILITY_EVENT, onStoreChange);
+  return () => {
+    window.removeEventListener("storage", onStoreChange);
+    window.removeEventListener(TERMINAL_VISIBILITY_EVENT, onStoreChange);
+  };
+}
+
+function getTerminalVisibility() {
+  return localStorage.getItem(TERMINAL_VISIBILITY_KEY) === "true";
+}
+
+function setTerminalVisibility(visible: boolean) {
+  localStorage.setItem(TERMINAL_VISIBILITY_KEY, String(visible));
+  window.dispatchEvent(new Event(TERMINAL_VISIBILITY_EVENT));
+}
+
 type SessionState = ReturnType<typeof useSessionSocket>["sessionState"];
 
 export default function SessionPage() {
@@ -141,18 +170,16 @@ function SessionPageContent() {
   const actionsButtonRef = useRef<HTMLButtonElement>(null);
 
   // Terminal panel state
-  const [terminalOpen, setTerminalOpen] = useState(() => {
-    if (typeof window === "undefined") return false;
-    return localStorage.getItem("terminal-visible") === "true";
-  });
+  const terminalOpen = useSyncExternalStore(
+    subscribeToTerminalVisibility,
+    getTerminalVisibility,
+    () => false
+  );
   const toggleTerminal = useCallback(() => {
-    const next = !terminalOpen;
-    localStorage.setItem("terminal-visible", String(next));
-    setTerminalOpen(next);
+    setTerminalVisibility(!terminalOpen);
   }, [terminalOpen]);
   const closeTerminal = useCallback(() => {
-    setTerminalOpen(false);
-    localStorage.setItem("terminal-visible", "false");
+    setTerminalVisibility(false);
   }, []);
   const ttydUrl = sessionState?.ttydUrl;
   const ttydToken = sessionState?.ttydToken;
diff --git a/packages/web/src/components/automations/automation-form.tsx b/packages/web/src/components/automations/automation-form.tsx
index 3d706dd829..cdce4feaf9 100644
--- a/packages/web/src/components/automations/automation-form.tsx
+++ b/packages/web/src/components/automations/automation-form.tsx
@@ -371,7 +371,7 @@ export function AutomationForm({ mode, initialValues, onSubmit, submitting }: Au
       {/* Trigger Type */}
       {mode === "create" ? (
         <div>
-          <label className="block text-sm font-medium text-foreground mb-1.5">Trigger Type</label>
+          <div className="block text-sm font-medium text-foreground mb-1.5">Trigger Type</div>
           <FieldDescription className="my-1">
             Scheduled automations run on a repeating timer. Other types run when the connected
             service sends an event (for example a GitHub webhook or Sentry alert).
@@ -420,12 +420,16 @@ export function AutomationForm({ mode, initialValues, onSubmit, submitting }: Au
 
       {/* Repository Configuration */}
       <div>
-        <label className="block text-sm font-medium text-foreground mb-1.5">
+        <label
+          htmlFor="automation-repository-configuration"
+          className="block text-sm font-medium text-foreground mb-1.5"
+        >
           Repository Configuration
         </label>
         <Popover open={repoDropdownOpen} onOpenChange={setRepoDropdownOpen}>
           <PopoverTrigger asChild>
             <button
+              id="automation-repository-configuration"
               type="button"
               className="flex w-full items-center gap-2 rounded-sm border border-border bg-input px-3 py-2 text-sm text-foreground transition hover:border-foreground/20 focus-visible:border-ring focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40"
               aria-label="Repository selection"
diff --git a/packages/web/src/components/settings/sandbox-settings.tsx b/packages/web/src/components/settings/sandbox-settings.tsx
index 5b9b10bd70..2f718a3b01 100644
--- a/packages/web/src/components/settings/sandbox-settings.tsx
+++ b/packages/web/src/components/settings/sandbox-settings.tsx
@@ -593,8 +593,8 @@ export function SandboxSettingsEditor({
         </div>
       </div>
 
-      <div>
-        <label className="block text-sm font-medium text-foreground mb-1.5">Service Ports</label>
+      <fieldset>
+        <legend className="block text-sm font-medium text-foreground mb-1.5">Service Ports</legend>
         <p className="text-xs text-muted-foreground mb-2">
           Ports code-server and the web terminal bind to. Leave blank for the defaults (
           {DEFAULT_CODE_SERVER_PORT} and {DEFAULT_TERMINAL_PORT}). Change a port to free the default
@@ -634,11 +634,12 @@ export function SandboxSettingsEditor({
             />
           </div>
         </div>
-      </div>
+      </fieldset>
 
-      <div>
+      <fieldset>
+        <legend className="sr-only">Tunnel Ports</legend>
         <div className="flex items-center justify-between max-w-sm mb-1.5">
-          <label className="block text-sm font-medium text-foreground">Tunnel Ports</label>
+          <span className="block text-sm font-medium text-foreground">Tunnel Ports</span>
           <Button
             type="button"
             variant="subtle"
@@ -680,10 +681,10 @@ export function SandboxSettingsEditor({
             ))
           )}
         </div>
-      </div>
+      </fieldset>
 
-      <div>
-        <label className="block text-sm font-medium text-foreground mb-1.5">Child Sessions</label>
+      <fieldset>
+        <legend className="block text-sm font-medium text-foreground mb-1.5">Child Sessions</legend>
         <p className="text-xs text-muted-foreground mb-2">
           Limit agent-spawned child sessions to prevent runaway sandbox usage.
         </p>
@@ -721,10 +722,10 @@ export function SandboxSettingsEditor({
             />
           </div>
         </div>
-      </div>
+      </fieldset>
 
-      <div>
-        <label className="block text-sm font-medium text-foreground mb-1.5">Resources</label>
+      <fieldset>
+        <legend className="block text-sm font-medium text-foreground mb-1.5">Resources</legend>
         <p className="text-xs text-muted-foreground mb-2">
           Reserve CPU and memory for each sandbox. Leave blank to use the provider&apos;s default
           reservation.
@@ -764,7 +765,7 @@ export function SandboxSettingsEditor({
             />
           </div>
         </div>
-      </div>
+      </fieldset>
 
       <div>
         <label
diff --git a/packages/web/src/hooks/use-session-attachments.ts b/packages/web/src/hooks/use-session-attachments.ts
index c34ae1d16a..543792d39b 100644
--- a/packages/web/src/hooks/use-session-attachments.ts
+++ b/packages/web/src/hooks/use-session-attachments.ts
@@ -44,9 +44,14 @@ export function useSessionAttachments() {
   const attachmentsRef = useRef<PendingAttachment[]>([]);
   const attachmentsRevisionRef = useRef(0);
   const activeUploadRef = useRef<AbortController | null>(null);
-  const uploadedByIdRef = useRef(
-    new Map<string, { sessionId: string; attachment: SessionAttachmentReference }>()
-  );
+  const uploadedByIdRef = useRef<Map<
+    string,
+    { sessionId: string; attachment: SessionAttachmentReference }
+  > | null>(null);
+  if (uploadedByIdRef.current === null) {
+    uploadedByIdRef.current = new Map();
+  }
+  const uploadedById = uploadedByIdRef.current;
 
   useEffect(() => {
     attachmentsRef.current = attachments;
@@ -107,32 +112,35 @@ export function useSessionAttachments() {
     }
   }, []);
 
-  const removeAttachment = useCallback((id: string) => {
-    setAttachmentError(null);
-    const current = attachmentsRef.current;
-    const removed = current.find((attachment) => attachment.id === id);
-    if (!removed) return;
+  const removeAttachment = useCallback(
+    (id: string) => {
+      setAttachmentError(null);
+      const current = attachmentsRef.current;
+      const removed = current.find((attachment) => attachment.id === id);
+      if (!removed) return;
 
-    URL.revokeObjectURL(removed.previewUrl);
-    uploadedByIdRef.current.delete(removed.id);
-    attachmentsRevisionRef.current += 1;
-    activeUploadRef.current?.abort();
-    const next = current.filter((attachment) => attachment.id !== id);
-    attachmentsRef.current = next;
-    setAttachments(next);
-  }, []);
+      URL.revokeObjectURL(removed.previewUrl);
+      uploadedById.delete(removed.id);
+      attachmentsRevisionRef.current += 1;
+      activeUploadRef.current?.abort();
+      const next = current.filter((attachment) => attachment.id !== id);
+      attachmentsRef.current = next;
+      setAttachments(next);
+    },
+    [uploadedById]
+  );
 
   const clearAttachments = useCallback(() => {
     const current = attachmentsRef.current;
     for (const attachment of current) {
       URL.revokeObjectURL(attachment.previewUrl);
     }
-    uploadedByIdRef.current.clear();
+    uploadedById.clear();
     attachmentsRevisionRef.current += 1;
     activeUploadRef.current?.abort();
     attachmentsRef.current = [];
     setAttachments([]);
-  }, []);
+  }, [uploadedById]);
 
   /**
    * Upload all pending attachments and return the references to send with the
@@ -170,7 +178,7 @@ export function useSessionAttachments() {
         for (const pendingAttachment of pending) {
           const fileName = pendingAttachment.file.name;
           assertCurrent();
-          const cached = uploadedByIdRef.current.get(pendingAttachment.id);
+          const cached = uploadedById.get(pendingAttachment.id);
           if (cached?.sessionId === sessionId) {
             uploaded.push(cached.attachment);
             continue;
@@ -204,7 +212,7 @@ export function useSessionAttachments() {
             name: fileName || "image-attachment",
             attachmentId,
           };
-          uploadedByIdRef.current.set(pendingAttachment.id, { sessionId, attachment });
+          uploadedById.set(pendingAttachment.id, { sessionId, attachment });
           uploaded.push(attachment);
         }
         assertCurrent();
@@ -228,7 +236,7 @@ export function useSessionAttachments() {
         setIsUploading(false);
       }
     },
-    []
+    [uploadedById]
   );
 
   return {
diff --git a/packages/web/src/hooks/use-session-participant-profiles.ts b/packages/web/src/hooks/use-session-participant-profiles.ts
index 7826bdfbb5..cc130e9696 100644
--- a/packages/web/src/hooks/use-session-participant-profiles.ts
+++ b/packages/web/src/hooks/use-session-participant-profiles.ts
@@ -18,7 +18,11 @@ export function useSessionParticipantProfiles(
   const { data, mutate } = useSWR<unknown>(
     `/api/sessions/${sessionId}/participant-profiles` as const
   );
-  const attemptedUnknownIds = useRef(new Set<string>());
+  const attemptedUnknownIdsRef = useRef<Set<string> | null>(null);
+  if (attemptedUnknownIdsRef.current === null) {
+    attemptedUnknownIdsRef.current = new Set();
+  }
+  const attemptedUnknownIds = attemptedUnknownIdsRef.current;
 
   const profiles = useMemo<Record<string, SessionParticipantProfile>>(() => {
     const parsed = sessionParticipantProfilesResponseSchema.safeParse(data);
@@ -34,19 +38,19 @@ export function useSessionParticipantProfiles(
   }, [events, participants]);
 
   useEffect(() => {
-    attemptedUnknownIds.current.clear();
-  }, [sessionId]);
+    attemptedUnknownIds.clear();
+  }, [attemptedUnknownIds, sessionId]);
 
   useEffect(() => {
     if (data === undefined) return;
     const unknownIds = [...observedUserIds].filter(
-      (userId) => !profiles[userId] && !attemptedUnknownIds.current.has(userId)
+      (userId) => !profiles[userId] && !attemptedUnknownIds.has(userId)
     );
     if (unknownIds.length === 0) return;
 
-    for (const userId of unknownIds) attemptedUnknownIds.current.add(userId);
+    for (const userId of unknownIds) attemptedUnknownIds.add(userId);
     void mutate();
-  }, [data, mutate, observedUserIds, profiles]);
+  }, [attemptedUnknownIds, data, mutate, observedUserIds, profiles]);
 
   const profiledParticipants = useMemo(
     () =>
diff --git a/packages/web/src/hooks/use-session-socket.ts b/packages/web/src/hooks/use-session-socket.ts
index fac793700e..8b03d3a1bc 100644
--- a/packages/web/src/hooks/use-session-socket.ts
+++ b/packages/web/src/hooks/use-session-socket.ts
@@ -74,18 +74,25 @@ export function useSessionSocket(sessionId: string): UseSessionSocketReturn {
   // Buffers streamed assistant text in a ref so token events (which arrive at
   // high frequency) don't re-render; the text is appended on completion.
   const pendingTextRef = useRef<PendingAssistantText | null>(null);
-  const subscriptionWaitersRef = useRef(new Set<(subscribed: boolean) => void>());
+  const subscriptionWaitersRef = useRef<Set<(subscribed: boolean) => void> | null>(null);
+  if (subscriptionWaitersRef.current === null) {
+    subscriptionWaitersRef.current = new Set();
+  }
+  const subscriptionWaiters = subscriptionWaitersRef.current;
   const pendingPromptRef = useRef<{
     resolve: (accepted: boolean) => void;
     timeout: ReturnType<typeof setTimeout>;
   } | null>(null);
 
-  const settleSubscriptionWaiters = useCallback((subscribed: boolean) => {
-    for (const resolve of subscriptionWaitersRef.current) {
-      resolve(subscribed);
-    }
-    subscriptionWaitersRef.current.clear();
-  }, []);
+  const settleSubscriptionWaiters = useCallback(
+    (subscribed: boolean) => {
+      for (const resolve of subscriptionWaiters) {
+        resolve(subscribed);
+      }
+      subscriptionWaiters.clear();
+    },
+    [subscriptionWaiters]
+  );
 
   const settlePendingPrompt = useCallback((accepted: boolean) => {
     const pending = pendingPromptRef.current;
@@ -166,13 +173,13 @@ export function useSessionSocket(sessionId: string): UseSessionSocketReturn {
         if (settled) return;
         settled = true;
         clearTimeout(timeout);
-        subscriptionWaitersRef.current.delete(finish);
+        subscriptionWaiters.delete(finish);
         resolve(subscribed);
       };
       const timeout = setTimeout(() => finish(false), PROMPT_SUBSCRIPTION_TIMEOUT_MS);
-      subscriptionWaitersRef.current.add(finish);
+      subscriptionWaiters.add(finish);
     });
-  }, [isOpen]);
+  }, [isOpen, subscriptionWaiters]);
 
   const sendPrompt = useCallback(
     async (