From 1cf27010558959ce401f719ebd503c61ffa0f401 Mon Sep 17 00:00:00 2001
From: Lakshmi Tanmay <lakshmi@voltcrash.com>
Date: Mon, 2 Nov 2026 13:06:34 +0530
Subject: [PATCH 1/3] fix(web): restore composer focus when returning to a
 thread

---
 apps/web/src/components/ChatView.tsx          |  16 +-
 .../src/components/ThreadTerminalDrawer.tsx   |   1 +
 ...FocusComposerOnThreadOpen.browser.test.tsx |  17 +-
 .../chat/useFocusComposerOnThreadOpen.ts      |  39 +++--
 .../web/src/lib/terminalFocus.browser.test.ts | 162 ++++++++++++++++++
 apps/web/src/lib/terminalFocus.ts             |  62 ++++++-
 6 files changed, 263 insertions(+), 34 deletions(-)

diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index fdbb91d9073ff..f53fc542902ee 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -216,7 +216,7 @@ import { usePanelAnimationSettings, usePanelPresence } from "../panelAnimations"
 import { useNewThreadHandler } from "../hooks/useHandleNewThread";
 import { useOpenPanelPullRequestUrl } from "../hooks/useOpenPanelPullRequestUrl";
 import { isPreviewFocused } from "../lib/previewFocus";
-import { focusTerminalOnThreadEnter, getTerminalFocusOwner } from "../lib/terminalFocus";
+import { getTerminalFocusOwner } from "../lib/terminalFocus";
 import {
   deriveLogicalProjectKeyFromSettings,
   selectProjectGroupingSettings,
@@ -2138,8 +2138,10 @@ export default function ChatView(props: ChatViewProps) {
   });
 
   useFocusComposerOnThreadOpen(
-    activeThread?.id,
-    !embedded && !terminalUiState.terminalOpen,
+    activeThreadRef,
+    workspaceLayoutElement,
+    !embedded,
+    terminalUiState.terminalOpen,
     focusComposerStable,
   );
 
@@ -2676,14 +2678,6 @@ export default function ChatView(props: ChatViewProps) {
     setTerminalUiLaunchContext(null);
   }
 
-  // Entering a thread with its drawer open focuses the drawer terminal; opening
-  // it from a handler requests focus there. A closed drawer leaves focus to the
-  // composer effect above.
-  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- focuses the open drawer terminal when entering a thread
-  useEffect(() => {
-    if (activeThreadRef && !embedded) return focusTerminalOnThreadEnter(activeThreadRef);
-  }, [activeThreadRef, embedded]);
-
   const getShortcutContext = (eventTarget: EventTarget | null = document.activeElement) => ({
     terminalFocus: getTerminalFocusOwner() !== null,
     terminalOpen: Boolean(terminalUiState.terminalOpen),
diff --git a/apps/web/src/components/ThreadTerminalDrawer.tsx b/apps/web/src/components/ThreadTerminalDrawer.tsx
index 049589d0b671a..98604724cc118 100644
--- a/apps/web/src/components/ThreadTerminalDrawer.tsx
+++ b/apps/web/src/components/ThreadTerminalDrawer.tsx
@@ -1206,6 +1206,7 @@ function TerminalSessionViewport({
     const unregister = registerTerminalFocusTarget({
       threadRef,
       terminalId,
+      element: mount,
       focus,
     });
     return () => {
diff --git a/apps/web/src/components/chat/useFocusComposerOnThreadOpen.browser.test.tsx b/apps/web/src/components/chat/useFocusComposerOnThreadOpen.browser.test.tsx
index 864f4c7079497..8324e96133e73 100644
--- a/apps/web/src/components/chat/useFocusComposerOnThreadOpen.browser.test.tsx
+++ b/apps/web/src/components/chat/useFocusComposerOnThreadOpen.browser.test.tsx
@@ -1,4 +1,6 @@
-import { useRef } from "react";
+import { scopeThreadRef } from "@t3tools/client-runtime/environment";
+import { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import { useRef, useState } from "react";
 import { expect, it, vi } from "vite-plus/test";
 
 import { act, fakeTimers, render } from "../../../test/render";
@@ -6,14 +8,21 @@ import { useFocusComposerOnThreadOpen } from "./useFocusComposerOnThreadOpen";
 
 function ThreadProbe(props: { threadId: string }) {
   const composerRef = useRef<HTMLTextAreaElement>(null);
-  useFocusComposerOnThreadOpen(props.threadId, true, () => composerRef.current?.focus());
+  const [root, setRoot] = useState<HTMLDivElement | null>(null);
+  useFocusComposerOnThreadOpen(
+    scopeThreadRef(EnvironmentId.make("rename"), ThreadId.make(props.threadId)),
+    root,
+    true,
+    false,
+    () => composerRef.current?.focus(),
+  );
   return (
-    <>
+    <div ref={setRoot}>
       <div data-sidebar-row="thread:beta">
         <input aria-label="Thread title" />
       </div>
       <textarea aria-label="Message" ref={composerRef} />
-    </>
+    </div>
   );
 }
 
diff --git a/apps/web/src/components/chat/useFocusComposerOnThreadOpen.ts b/apps/web/src/components/chat/useFocusComposerOnThreadOpen.ts
index 436a9dcaf6126..b904e18544e30 100644
--- a/apps/web/src/components/chat/useFocusComposerOnThreadOpen.ts
+++ b/apps/web/src/components/chat/useFocusComposerOnThreadOpen.ts
@@ -1,21 +1,40 @@
+import type { ScopedThreadRef } from "@t3tools/contracts";
 import { useEffect } from "react";
 
-/** Lands the caret in the composer a frame after a thread opens. */
+import { focusTerminalOnThreadEnter } from "../../lib/terminalFocus";
+
+/** Restores thread focus, landing the caret a frame after composer entry. */
 export function useFocusComposerOnThreadOpen(
-  threadId: string | undefined,
+  threadRef: ScopedThreadRef | null,
+  root: HTMLElement | null,
   enabled: boolean,
+  terminalOpen: boolean,
   focusComposer: () => void,
 ) {
-  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- schedules a frame to focus the composer DOM element when a thread opens with the terminal closed
+  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- restores DOM focus on thread entry and after the drawer opens or closes
   useEffect(() => {
-    if (!threadId || !enabled) return;
-    const frame = window.requestAnimationFrame(() => {
-      // Double-clicking a sidebar row opens its thread and its rename field in one gesture.
-      if (document.activeElement?.matches("[data-sidebar-row] input")) return;
-      focusComposer();
+    if (!threadRef || !enabled || !root) return;
+    let frame: number | undefined;
+    const leave = focusTerminalOnThreadEnter(threadRef, {
+      root,
+      focusComposer: () => {
+        frame = window.requestAnimationFrame(() => {
+          // Double-clicking a sidebar row opens its thread and its rename field in one gesture.
+          if (document.activeElement?.matches("[data-sidebar-row] input")) return;
+          focusComposer();
+        });
+      },
     });
     return () => {
-      window.cancelAnimationFrame(frame);
+      leave();
+      if (frame !== undefined) window.cancelAnimationFrame(frame);
     };
-  }, [threadId, enabled, focusComposer]);
+  }, [
+    threadRef,
+    root,
+    enabled,
+    // oxlint-disable-next-line react/exhaustive-effect-dependencies -- Drawer visibility changes also restore focus after explicit open/close actions.
+    terminalOpen,
+    focusComposer,
+  ]);
 }
diff --git a/apps/web/src/lib/terminalFocus.browser.test.ts b/apps/web/src/lib/terminalFocus.browser.test.ts
index ac3ed25a3b617..3a4634b407fb8 100644
--- a/apps/web/src/lib/terminalFocus.browser.test.ts
+++ b/apps/web/src/lib/terminalFocus.browser.test.ts
@@ -2,10 +2,15 @@ import { scopeThreadRef } from "@t3tools/client-runtime/environment";
 import { EnvironmentId, ThreadId } from "@t3tools/contracts";
 import { describe, expect, it } from "vite-plus/test";
 
+import { useRightPanelStore } from "../rightPanelStore";
+import { useTerminalUiStateStore } from "../terminalUiStateStore";
+
 import {
   consumePendingTerminalFocus,
   focusTerminal,
   focusTerminalViewport,
+  focusTerminalOnThreadEnter,
+  focusTerminalOnNavigation,
   registerTerminalFocusTarget,
 } from "./terminalFocus";
 
@@ -57,3 +62,160 @@ describe("focusTerminalViewport", () => {
     expect(document.activeElement).toBe(viewport.input);
   });
 });
+
+function mountThread(threadId: string, environmentId = "env") {
+  const ref = scopeThreadRef(EnvironmentId.make(environmentId), ThreadId.make(threadId));
+  const root = document.createElement("div");
+  const composer = document.createElement("textarea");
+  composer.ariaLabel = "Composer";
+  composer.dataset.workspaceArea = "composer";
+  root.append(composer);
+  document.body.append(root);
+  const drawerState = { visible: true };
+  const mountTerminal = (id: string) => {
+    const input = document.createElement("textarea");
+    input.ariaLabel = id;
+    root.append(input);
+    const unregister = registerTerminalFocusTarget({
+      threadRef: ref,
+      terminalId: id,
+      element: input,
+      focus: () => {
+        if (id === "drawer" && !drawerState.visible) return false;
+        input.focus();
+        return document.activeElement === input;
+      },
+    });
+    return {
+      input,
+      [Symbol.dispose]() {
+        unregister();
+        input.remove();
+      },
+    };
+  };
+  useTerminalUiStateStore.getState().ensureTerminal(ref, "drawer", { open: true, active: true });
+  useRightPanelStore.getState().openTerminal(ref, "panel");
+  return {
+    ref,
+    root,
+    composer,
+    drawerState,
+    mountTerminal,
+    enter: () => focusTerminalOnThreadEnter(ref, { root, focusComposer: () => composer.focus() }),
+    [Symbol.dispose]: () => root.remove(),
+  };
+}
+
+describe("thread focus restoration", () => {
+  it.each(["composer", "drawer", "panel"] as const)(
+    "restores %s focus when returning to a thread with both terminals open",
+    (control) => {
+      using thread = mountThread(`return-${control}`);
+      using drawer = thread.mountTerminal("drawer");
+      using panel = thread.mountTerminal("panel");
+      const leave = thread.enter();
+      if (control === "panel") document.body.append(panel.input);
+      const initial =
+        control === "composer"
+          ? thread.composer
+          : control === "drawer"
+            ? drawer.input
+            : panel.input;
+      initial.focus();
+      expect(document.activeElement).toBe(initial);
+      leave();
+      thread.root.hidden = true;
+      focusTerminalOnThreadEnter(
+        scopeThreadRef(EnvironmentId.make("env"), ThreadId.make("other-thread")),
+      )();
+      drawer[Symbol.dispose]();
+      panel[Symbol.dispose]();
+      thread.root.hidden = false;
+      using remountedDrawer = thread.mountTerminal("drawer");
+      using remountedPanel = thread.mountTerminal("panel");
+      if (control === "panel") document.body.append(remountedPanel.input);
+      using _leave = { [Symbol.dispose]: thread.enter() };
+      const expected =
+        control === "composer"
+          ? thread.composer
+          : control === "drawer"
+            ? remountedDrawer.input
+            : remountedPanel.input;
+
+      expect(document.activeElement).toBe(expected);
+    },
+  );
+
+  it("keeps an explicit terminal navigation request ahead of remembered composer focus", () => {
+    using thread = mountThread("explicit-reveal");
+    using _drawer = thread.mountTerminal("drawer");
+    using panel = thread.mountTerminal("panel");
+    const leave = thread.enter();
+    thread.composer.focus();
+    leave();
+    focusTerminalOnThreadEnter(
+      scopeThreadRef(EnvironmentId.make("env"), ThreadId.make("before-reveal")),
+    )();
+
+    focusTerminalOnNavigation(thread.ref, "panel");
+    using _leave = { [Symbol.dispose]: thread.enter() };
+
+    expect(document.activeElement).toBe(panel.input);
+  });
+
+  it("does not share focus history between matching thread ids in different environments", () => {
+    using first = mountThread("shared-id", "first");
+    using _firstDrawer = first.mountTerminal("drawer");
+    const leaveFirst = first.enter();
+    first.composer.focus();
+    leaveFirst();
+    using second = mountThread("shared-id", "second");
+    using secondDrawer = second.mountTerminal("drawer");
+    using secondPanel = second.mountTerminal("panel");
+    const leaveSecond = second.enter();
+    expect(document.activeElement).toBe(secondDrawer.input);
+    secondPanel.input.focus();
+    leaveSecond();
+    using _leave = { [Symbol.dispose]: first.enter() };
+
+    expect(document.activeElement).toBe(first.composer);
+  });
+
+  it("keeps an explicit drawer-open request while its viewport becomes visible", () => {
+    using thread = mountThread("drawer-open");
+    using drawer = thread.mountTerminal("drawer");
+    const leave = thread.enter();
+    thread.composer.focus();
+    thread.drawerState.visible = false;
+    useTerminalUiStateStore.getState().setTerminalOpen(thread.ref, false);
+    focusTerminal(thread.ref, "drawer");
+    useTerminalUiStateStore.getState().setTerminalOpen(thread.ref, true);
+    leave();
+    using _leave = { [Symbol.dispose]: thread.enter() };
+    thread.drawerState.visible = true;
+    consumePendingTerminalFocus(thread.ref, "drawer");
+
+    expect(document.activeElement).toBe(drawer.input);
+  });
+
+  it.each(["viewport", "close button", "header toggle"] as const)(
+    "falls back to the composer when the drawer closes from its %s",
+    (control) => {
+      using thread = mountThread(`closed-remembered-${control}`);
+      using drawer = thread.mountTerminal("drawer");
+      const close = document.createElement("button");
+      if (control === "close button") close.dataset.terminalOwner = "drawer";
+      thread.root.append(close);
+      const leave = thread.enter();
+      if (control !== "viewport") close.focus();
+      else expect(document.activeElement).toBe(drawer.input);
+      leave();
+      useTerminalUiStateStore.getState().setTerminalOpen(thread.ref, false);
+      thread.drawerState.visible = false;
+      using _leave = { [Symbol.dispose]: thread.enter() };
+
+      expect(document.activeElement).toBe(thread.composer);
+    },
+  );
+});
diff --git a/apps/web/src/lib/terminalFocus.ts b/apps/web/src/lib/terminalFocus.ts
index b9d11ab68fd64..7053d39db8836 100644
--- a/apps/web/src/lib/terminalFocus.ts
+++ b/apps/web/src/lib/terminalFocus.ts
@@ -31,11 +31,13 @@ export function subscribeToTerminalFocusChanges(listener: () => void): () => voi
 interface TerminalFocusTarget {
   readonly threadRef: ScopedThreadRef;
   readonly terminalId: string;
+  readonly element?: HTMLElement;
   /** Returns false when the target cannot take focus yet (hidden, or no operate grant). */
   readonly focus: () => boolean;
 }
 
 const focusTargets = new Set<TerminalFocusTarget>();
+const lastThreadFocus = new Map<string, "composer" | { terminalId: string }>();
 // One request at a time: the newest terminal the user asked for wins, so an
 // older request never fires later and steals focus.
 let pendingFocus: { readonly threadKey: string; readonly terminalId: string } | null = null;
@@ -44,6 +46,8 @@ let pendingFocus: { readonly threadKey: string; readonly terminalId: string } |
 // thread's viewports mount and consume the handler's request in the commit's
 // layout phase, before ChatView's thread-enter effect runs.
 let enteredThreadKey: string | null = null;
+// Survives effect cleanup so drawer visibility updates remain distinct from navigation.
+let lastEnteredThreadKey: string | null = null;
 let navigationRequestThreadKey: string | null = null;
 
 function isPending(threadKey: string, terminalId: string): boolean {
@@ -122,24 +126,64 @@ export function focusTerminalOnNavigation(threadRef: ScopedThreadRef, terminalId
   focusTerminal(threadRef, terminalId);
 }
 
-/**
- * Entering a thread with its drawer open focuses the drawer terminal, unless a
- * navigating handler already asked for a terminal there. Returns the leave
- * cleanup for ChatView's effect.
- */
-export function focusTerminalOnThreadEnter(threadRef: ScopedThreadRef): () => void {
+/** Restores composer or terminal focus; explicit terminal navigation takes precedence. */
+export function focusTerminalOnThreadEnter(
+  threadRef: ScopedThreadRef,
+  content?: { readonly root: HTMLElement; readonly focusComposer: () => void },
+): () => void {
   const threadKey = scopedThreadKey(threadRef);
-  const requestedByHandler = navigationRequestThreadKey === threadKey;
+  const requestedByHandler =
+    navigationRequestThreadKey === threadKey ||
+    (lastEnteredThreadKey === threadKey && pendingFocus?.threadKey === threadKey);
+  if (!requestedByHandler) pendingFocus = null;
+  lastEnteredThreadKey = threadKey;
   navigationRequestThreadKey = null;
   enteredThreadKey = threadKey;
+  const previous = lastThreadFocus.get(threadKey);
+  const remember = () => {
+    if (!content) return;
+    const element = document.activeElement;
+    if (!(element instanceof HTMLElement)) return;
+    const terminal = Array.from(focusTargets).find((target) => target.element?.contains(element));
+    if (terminal) {
+      if (scopedThreadKey(terminal.threadRef) === threadKey)
+        lastThreadFocus.set(threadKey, { terminalId: terminal.terminalId });
+    } else if (
+      content.root.contains(element) &&
+      element.closest('[data-workspace-area="composer"]')
+    ) {
+      lastThreadFocus.set(threadKey, "composer");
+    }
+  };
+  content?.root.ownerDocument.addEventListener("focusin", remember);
   if (!requestedByHandler) {
-    const { terminalOpen, activeTerminalId } = selectThreadTerminalUiState(
+    const drawer = selectThreadTerminalUiState(
       useTerminalUiStateStore.getState().terminalUiStateByThreadKey,
       threadRef,
     );
-    if (terminalOpen && activeTerminalId) focusTerminal(threadRef, activeTerminalId);
+    const panel = selectThreadRightPanelState(useRightPanelStore.getState().byThreadKey, threadRef);
+    const panelTerminal = panel.isOpen
+      ? panel.surfaces.find((surface) => surface.id === panel.activeSurfaceId)
+      : null;
+    if (previous === "composer") {
+      content?.focusComposer();
+    } else if (
+      previous &&
+      ((drawer.terminalOpen &&
+        drawer.terminalGroups
+          .find((group) => group.id === drawer.activeTerminalGroupId)
+          ?.terminalIds.includes(previous.terminalId)) ||
+        (panelTerminal?.kind === "terminal" &&
+          panelTerminal.terminalIds.includes(previous.terminalId)))
+    ) {
+      focusTerminal(threadRef, previous.terminalId);
+    } else if (drawer.terminalOpen && drawer.activeTerminalId) {
+      focusTerminal(threadRef, drawer.activeTerminalId);
+    } else content?.focusComposer();
   }
+  if (requestedByHandler) remember();
   return () => {
+    content?.root.ownerDocument.removeEventListener("focusin", remember);
     // A handler navigating elsewhere marks its target before this cleanup runs.
     if (enteredThreadKey === threadKey) enteredThreadKey = null;
   };

From a506294bedcc3b5c8fa7730b9a886cddd65ac234 Mon Sep 17 00:00:00 2001
From: Lakshmi Tanmay <lakshmi@voltcrash.com>
Date: Mon, 2 Nov 2026 13:54:03 +0530
Subject: [PATCH 2/3] fix(web): discard stale terminal focus requests after
 chat remounts

---
 .../web/src/lib/terminalFocus.browser.test.ts | 28 +++++++++++--------
 apps/web/src/lib/terminalFocus.ts             | 10 ++++---
 2 files changed, 23 insertions(+), 15 deletions(-)

diff --git a/apps/web/src/lib/terminalFocus.browser.test.ts b/apps/web/src/lib/terminalFocus.browser.test.ts
index 3a4634b407fb8..b80c772e44e64 100644
--- a/apps/web/src/lib/terminalFocus.browser.test.ts
+++ b/apps/web/src/lib/terminalFocus.browser.test.ts
@@ -108,7 +108,7 @@ function mountThread(threadId: string, environmentId = "env") {
 }
 
 describe("thread focus restoration", () => {
-  it.each(["composer", "drawer", "panel"] as const)(
+  it.each(["composer", "drawer", "panel", "remounted composer"] as const)(
     "restores %s focus when returning to a thread with both terminals open",
     (control) => {
       using thread = mountThread(`return-${control}`);
@@ -116,29 +116,35 @@ describe("thread focus restoration", () => {
       using panel = thread.mountTerminal("panel");
       const leave = thread.enter();
       if (control === "panel") document.body.append(panel.input);
+      const remount = control === "remounted composer";
       const initial =
-        control === "composer"
+        control === "composer" || remount
           ? thread.composer
           : control === "drawer"
             ? drawer.input
             : panel.input;
       initial.focus();
       expect(document.activeElement).toBe(initial);
+      if (remount) focusTerminal(thread.ref, "not-ready");
       leave();
       thread.root.hidden = true;
-      focusTerminalOnThreadEnter(
-        scopeThreadRef(EnvironmentId.make("env"), ThreadId.make("other-thread")),
-      )();
+      if (!remount)
+        focusTerminalOnThreadEnter(
+          scopeThreadRef(EnvironmentId.make("env"), ThreadId.make("other-thread")),
+        )();
       drawer[Symbol.dispose]();
       panel[Symbol.dispose]();
-      thread.root.hidden = false;
-      using remountedDrawer = thread.mountTerminal("drawer");
-      using remountedPanel = thread.mountTerminal("panel");
+      if (remount) thread.root.remove();
+      using remountedThread = remount ? mountThread(`return-${control}`) : undefined;
+      const returnedThread = remountedThread ?? thread;
+      returnedThread.root.hidden = false;
+      using remountedDrawer = returnedThread.mountTerminal("drawer");
+      using remountedPanel = returnedThread.mountTerminal("panel");
       if (control === "panel") document.body.append(remountedPanel.input);
-      using _leave = { [Symbol.dispose]: thread.enter() };
+      using _leave = { [Symbol.dispose]: returnedThread.enter() };
       const expected =
-        control === "composer"
-          ? thread.composer
+        control === "composer" || remount
+          ? returnedThread.composer
           : control === "drawer"
             ? remountedDrawer.input
             : remountedPanel.input;
diff --git a/apps/web/src/lib/terminalFocus.ts b/apps/web/src/lib/terminalFocus.ts
index 7053d39db8836..98b71b76cda95 100644
--- a/apps/web/src/lib/terminalFocus.ts
+++ b/apps/web/src/lib/terminalFocus.ts
@@ -46,8 +46,8 @@ let pendingFocus: { readonly threadKey: string; readonly terminalId: string } |
 // thread's viewports mount and consume the handler's request in the commit's
 // layout phase, before ChatView's thread-enter effect runs.
 let enteredThreadKey: string | null = null;
-// Survives effect cleanup so drawer visibility updates remain distinct from navigation.
-let lastEnteredThreadKey: string | null = null;
+// Drawer visibility reruns reuse the root; a remounted chat must not inherit parked requests.
+const lastEnteredThreadByRoot = new WeakMap<HTMLElement, string>();
 let navigationRequestThreadKey: string | null = null;
 
 function isPending(threadKey: string, terminalId: string): boolean {
@@ -134,9 +134,11 @@ export function focusTerminalOnThreadEnter(
   const threadKey = scopedThreadKey(threadRef);
   const requestedByHandler =
     navigationRequestThreadKey === threadKey ||
-    (lastEnteredThreadKey === threadKey && pendingFocus?.threadKey === threadKey);
+    (content !== undefined &&
+      lastEnteredThreadByRoot.get(content.root) === threadKey &&
+      pendingFocus?.threadKey === threadKey);
   if (!requestedByHandler) pendingFocus = null;
-  lastEnteredThreadKey = threadKey;
+  if (content) lastEnteredThreadByRoot.set(content.root, threadKey);
   navigationRequestThreadKey = null;
   enteredThreadKey = threadKey;
   const previous = lastThreadFocus.get(threadKey);

From cb63d686eeb03e2c0b0f23ec0f9ff09ba524dc64 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 12 Nov 2026 21:01:46 +0000
Subject: [PATCH 3/3] refactor(web): require the chat root when restoring
 thread focus

The only caller always passes the chat root, so the optional branches go
and the entry function is named for what it now does. Reads focus from the
root's own document, and trims tests that repeated an existing path.

AI-assisted; verified with the tests and tools listed above.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../chat/useFocusComposerOnThreadOpen.ts      |  4 +-
 .../web/src/lib/terminalFocus.browser.test.ts | 69 +++++++------------
 apps/web/src/lib/terminalFocus.test.ts        | 23 +++++--
 apps/web/src/lib/terminalFocus.ts             | 22 +++---
 4 files changed, 51 insertions(+), 67 deletions(-)

diff --git a/apps/web/src/components/chat/useFocusComposerOnThreadOpen.ts b/apps/web/src/components/chat/useFocusComposerOnThreadOpen.ts
index b904e18544e30..3cb35fbdff5f9 100644
--- a/apps/web/src/components/chat/useFocusComposerOnThreadOpen.ts
+++ b/apps/web/src/components/chat/useFocusComposerOnThreadOpen.ts
@@ -1,7 +1,7 @@
 import type { ScopedThreadRef } from "@t3tools/contracts";
 import { useEffect } from "react";
 
-import { focusTerminalOnThreadEnter } from "../../lib/terminalFocus";
+import { restoreFocusOnThreadEnter } from "../../lib/terminalFocus";
 
 /** Restores thread focus, landing the caret a frame after composer entry. */
 export function useFocusComposerOnThreadOpen(
@@ -15,7 +15,7 @@ export function useFocusComposerOnThreadOpen(
   useEffect(() => {
     if (!threadRef || !enabled || !root) return;
     let frame: number | undefined;
-    const leave = focusTerminalOnThreadEnter(threadRef, {
+    const leave = restoreFocusOnThreadEnter(threadRef, {
       root,
       focusComposer: () => {
         frame = window.requestAnimationFrame(() => {
diff --git a/apps/web/src/lib/terminalFocus.browser.test.ts b/apps/web/src/lib/terminalFocus.browser.test.ts
index b80c772e44e64..f393a4a7d8cc9 100644
--- a/apps/web/src/lib/terminalFocus.browser.test.ts
+++ b/apps/web/src/lib/terminalFocus.browser.test.ts
@@ -8,10 +8,10 @@ import { useTerminalUiStateStore } from "../terminalUiStateStore";
 import {
   consumePendingTerminalFocus,
   focusTerminal,
-  focusTerminalViewport,
-  focusTerminalOnThreadEnter,
   focusTerminalOnNavigation,
+  focusTerminalViewport,
   registerTerminalFocusTarget,
+  restoreFocusOnThreadEnter,
 } from "./terminalFocus";
 
 // The drawer's collapsed shape: a 0fr grid row that clips the viewport, which
@@ -63,6 +63,13 @@ describe("focusTerminalViewport", () => {
   });
 });
 
+function enterOtherThread(threadId: string) {
+  restoreFocusOnThreadEnter(scopeThreadRef(EnvironmentId.make("env"), ThreadId.make(threadId)), {
+    root: document.createElement("div"),
+    focusComposer: () => {},
+  })();
+}
+
 function mountThread(threadId: string, environmentId = "env") {
   const ref = scopeThreadRef(EnvironmentId.make(environmentId), ThreadId.make(threadId));
   const root = document.createElement("div");
@@ -102,7 +109,7 @@ function mountThread(threadId: string, environmentId = "env") {
     composer,
     drawerState,
     mountTerminal,
-    enter: () => focusTerminalOnThreadEnter(ref, { root, focusComposer: () => composer.focus() }),
+    enter: () => restoreFocusOnThreadEnter(ref, { root, focusComposer: () => composer.focus() }),
     [Symbol.dispose]: () => root.remove(),
   };
 }
@@ -128,10 +135,7 @@ describe("thread focus restoration", () => {
       if (remount) focusTerminal(thread.ref, "not-ready");
       leave();
       thread.root.hidden = true;
-      if (!remount)
-        focusTerminalOnThreadEnter(
-          scopeThreadRef(EnvironmentId.make("env"), ThreadId.make("other-thread")),
-        )();
+      if (!remount) enterOtherThread("other-thread");
       drawer[Symbol.dispose]();
       panel[Symbol.dispose]();
       if (remount) thread.root.remove();
@@ -160,9 +164,7 @@ describe("thread focus restoration", () => {
     const leave = thread.enter();
     thread.composer.focus();
     leave();
-    focusTerminalOnThreadEnter(
-      scopeThreadRef(EnvironmentId.make("env"), ThreadId.make("before-reveal")),
-    )();
+    enterOtherThread("before-reveal");
 
     focusTerminalOnNavigation(thread.ref, "panel");
     using _leave = { [Symbol.dispose]: thread.enter() };
@@ -170,24 +172,6 @@ describe("thread focus restoration", () => {
     expect(document.activeElement).toBe(panel.input);
   });
 
-  it("does not share focus history between matching thread ids in different environments", () => {
-    using first = mountThread("shared-id", "first");
-    using _firstDrawer = first.mountTerminal("drawer");
-    const leaveFirst = first.enter();
-    first.composer.focus();
-    leaveFirst();
-    using second = mountThread("shared-id", "second");
-    using secondDrawer = second.mountTerminal("drawer");
-    using secondPanel = second.mountTerminal("panel");
-    const leaveSecond = second.enter();
-    expect(document.activeElement).toBe(secondDrawer.input);
-    secondPanel.input.focus();
-    leaveSecond();
-    using _leave = { [Symbol.dispose]: first.enter() };
-
-    expect(document.activeElement).toBe(first.composer);
-  });
-
   it("keeps an explicit drawer-open request while its viewport becomes visible", () => {
     using thread = mountThread("drawer-open");
     using drawer = thread.mountTerminal("drawer");
@@ -205,23 +189,16 @@ describe("thread focus restoration", () => {
     expect(document.activeElement).toBe(drawer.input);
   });
 
-  it.each(["viewport", "close button", "header toggle"] as const)(
-    "falls back to the composer when the drawer closes from its %s",
-    (control) => {
-      using thread = mountThread(`closed-remembered-${control}`);
-      using drawer = thread.mountTerminal("drawer");
-      const close = document.createElement("button");
-      if (control === "close button") close.dataset.terminalOwner = "drawer";
-      thread.root.append(close);
-      const leave = thread.enter();
-      if (control !== "viewport") close.focus();
-      else expect(document.activeElement).toBe(drawer.input);
-      leave();
-      useTerminalUiStateStore.getState().setTerminalOpen(thread.ref, false);
-      thread.drawerState.visible = false;
-      using _leave = { [Symbol.dispose]: thread.enter() };
+  it("falls back to the composer when the remembered drawer terminal was closed", () => {
+    using thread = mountThread("closed-remembered");
+    using drawer = thread.mountTerminal("drawer");
+    const leave = thread.enter();
+    expect(document.activeElement).toBe(drawer.input);
+    leave();
+    useTerminalUiStateStore.getState().setTerminalOpen(thread.ref, false);
+    thread.drawerState.visible = false;
+    using _leave = { [Symbol.dispose]: thread.enter() };
 
-      expect(document.activeElement).toBe(thread.composer);
-    },
-  );
+    expect(document.activeElement).toBe(thread.composer);
+  });
 });
diff --git a/apps/web/src/lib/terminalFocus.test.ts b/apps/web/src/lib/terminalFocus.test.ts
index fe561e70c542c..075d13149d367 100644
--- a/apps/web/src/lib/terminalFocus.test.ts
+++ b/apps/web/src/lib/terminalFocus.test.ts
@@ -11,13 +11,22 @@ import {
   focusPanelTerminalAfterClose,
   focusTerminal,
   focusTerminalOnNavigation,
-  focusTerminalOnThreadEnter,
   registerTerminalFocusTarget,
+  restoreFocusOnThreadEnter,
 } from "./terminalFocus";
 
 const threadRef = (threadId: string) =>
   scopeThreadRef(EnvironmentId.make("env"), ThreadId.make(threadId));
 
+// Node has no DOM; entry only listens on the root's document for focus changes.
+const enterThread = (ref: ReturnType<typeof threadRef>) =>
+  restoreFocusOnThreadEnter(ref, {
+    root: {
+      ownerDocument: Object.assign(new EventTarget(), { activeElement: null }),
+    } as unknown as HTMLElement,
+    focusComposer: () => {},
+  });
+
 describe("focusTerminal", () => {
   it("focuses a mounted target right away", () => {
     const ref = threadRef("mounted");
@@ -173,7 +182,7 @@ describe("focusTerminal", () => {
     const focus = vi.fn(() => true);
     const unregister = registerTerminalFocusTarget({ threadRef: ref, terminalId: "a", focus });
 
-    const leave = focusTerminalOnThreadEnter(ref);
+    const leave = enterThread(ref);
 
     expect(focus).toHaveBeenCalledTimes(1);
     leave();
@@ -199,7 +208,7 @@ describe("focusTerminal", () => {
       terminalId: "panel",
       focus: panel,
     });
-    const leave = focusTerminalOnThreadEnter(ref);
+    const leave = enterThread(ref);
 
     expect(drawer).not.toHaveBeenCalled();
     expect(panel).toHaveBeenCalledTimes(1);
@@ -218,12 +227,12 @@ describe("focusTerminal", () => {
       focus: drawer,
     });
 
-    const leaveFirst = focusTerminalOnThreadEnter(ref);
+    const leaveFirst = enterThread(ref);
     focusTerminal(ref, "drawer");
     focusTerminalOnNavigation(ref, "drawer");
     leaveFirst();
     drawer.mockClear();
-    const leaveSecond = focusTerminalOnThreadEnter(ref);
+    const leaveSecond = enterThread(ref);
 
     expect(drawer).toHaveBeenCalledTimes(1);
     leaveSecond();
@@ -234,7 +243,7 @@ describe("focusTerminal", () => {
     const ref = threadRef("revisited");
     useTerminalUiStateStore.getState().ensureTerminal(ref, "drawer", { open: true, active: true });
     focusTerminalOnNavigation(ref, "panel");
-    focusTerminalOnThreadEnter(threadRef("elsewhere"))();
+    enterThread(threadRef("elsewhere"))();
 
     const drawer = vi.fn(() => true);
     const unregisterDrawer = registerTerminalFocusTarget({
@@ -242,7 +251,7 @@ describe("focusTerminal", () => {
       terminalId: "drawer",
       focus: drawer,
     });
-    const leave = focusTerminalOnThreadEnter(ref);
+    const leave = enterThread(ref);
 
     expect(drawer).toHaveBeenCalledTimes(1);
     leave();
diff --git a/apps/web/src/lib/terminalFocus.ts b/apps/web/src/lib/terminalFocus.ts
index 98b71b76cda95..21bc873b32c3a 100644
--- a/apps/web/src/lib/terminalFocus.ts
+++ b/apps/web/src/lib/terminalFocus.ts
@@ -127,25 +127,23 @@ export function focusTerminalOnNavigation(threadRef: ScopedThreadRef, terminalId
 }
 
 /** Restores composer or terminal focus; explicit terminal navigation takes precedence. */
-export function focusTerminalOnThreadEnter(
+export function restoreFocusOnThreadEnter(
   threadRef: ScopedThreadRef,
-  content?: { readonly root: HTMLElement; readonly focusComposer: () => void },
+  content: { readonly root: HTMLElement; readonly focusComposer: () => void },
 ): () => void {
   const threadKey = scopedThreadKey(threadRef);
   const requestedByHandler =
     navigationRequestThreadKey === threadKey ||
-    (content !== undefined &&
-      lastEnteredThreadByRoot.get(content.root) === threadKey &&
+    (lastEnteredThreadByRoot.get(content.root) === threadKey &&
       pendingFocus?.threadKey === threadKey);
   if (!requestedByHandler) pendingFocus = null;
-  if (content) lastEnteredThreadByRoot.set(content.root, threadKey);
+  lastEnteredThreadByRoot.set(content.root, threadKey);
   navigationRequestThreadKey = null;
   enteredThreadKey = threadKey;
   const previous = lastThreadFocus.get(threadKey);
   const remember = () => {
-    if (!content) return;
-    const element = document.activeElement;
-    if (!(element instanceof HTMLElement)) return;
+    const element = content.root.ownerDocument.activeElement;
+    if (!element) return;
     const terminal = Array.from(focusTargets).find((target) => target.element?.contains(element));
     if (terminal) {
       if (scopedThreadKey(terminal.threadRef) === threadKey)
@@ -157,7 +155,7 @@ export function focusTerminalOnThreadEnter(
       lastThreadFocus.set(threadKey, "composer");
     }
   };
-  content?.root.ownerDocument.addEventListener("focusin", remember);
+  content.root.ownerDocument.addEventListener("focusin", remember);
   if (!requestedByHandler) {
     const drawer = selectThreadTerminalUiState(
       useTerminalUiStateStore.getState().terminalUiStateByThreadKey,
@@ -168,7 +166,7 @@ export function focusTerminalOnThreadEnter(
       ? panel.surfaces.find((surface) => surface.id === panel.activeSurfaceId)
       : null;
     if (previous === "composer") {
-      content?.focusComposer();
+      content.focusComposer();
     } else if (
       previous &&
       ((drawer.terminalOpen &&
@@ -181,11 +179,11 @@ export function focusTerminalOnThreadEnter(
       focusTerminal(threadRef, previous.terminalId);
     } else if (drawer.terminalOpen && drawer.activeTerminalId) {
       focusTerminal(threadRef, drawer.activeTerminalId);
-    } else content?.focusComposer();
+    } else content.focusComposer();
   }
   if (requestedByHandler) remember();
   return () => {
-    content?.root.ownerDocument.removeEventListener("focusin", remember);
+    content.root.ownerDocument.removeEventListener("focusin", remember);
     // A handler navigating elsewhere marks its target before this cleanup runs.
     if (enteredThreadKey === threadKey) enteredThreadKey = null;
   };