feat(webapp): account preference for the chat open position

Author: kathiekiwi

.server-changes/chat-open-mode-account-preference.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: improvement
+---
+
+You can now set your preferred Ask Trigger chat position (floating, right panel, or fullscreen) in your account settings — it's used every time you open the chat.

apps/webapp/app/components/dashboard-agent/DashboardAgent.tsx

@@ -11,6 +11,7 @@ import { useEnvironment } from "~/hooks/useEnvironment";
 import { useOrganization } from "~/hooks/useOrganizations";
 import { useProject } from "~/hooks/useProject";
 import { useShortcutKeys } from "~/hooks/useShortcutKeys";
+import { useUser } from "~/hooks/useUser";
 import { useAskAiAvailability } from "~/hooks/useAskAiAvailability";
 import { agentDeepLinkParams, ASK_AI_SHORTCUT, askAiChannelTarget } from "./ask-ai-channels";
 import { DashboardAgentPanel } from "./DashboardAgentPanel";
@@ -19,8 +20,7 @@ import { useDashboardAgentOpenRequests } from "./dashboardAgentOpenRequest";
 import {
   agentHiddenContentClassName,
   FloatingAgentWindow,
-  readAgentMode,
-  writeAgentMode,
+  initialAgentMode,
   type DashboardAgentMode,
 } from "./panel-layout";
 import { nextPendingTurnChatId } from "./pending-turn";
@@ -37,6 +37,10 @@ import {
 
 const TOASTED_WAKES_STORAGE_KEY = "tdev:dashboard-agent:toasted-wakes";
 
+// Superseded by the account preference; a stray value here would otherwise pin the mode
+// forever if this cleanup effect never ran.
+const STALE_MODE_STORAGE_KEYS = ["tdev:dashboard-agent:mode", "tdev:dashboard-agent:fullscreen"];
+
 // Shorter than the poll interval, so a stuck request is dropped before the next tick.
 const UNREAD_REQUEST_TIMEOUT_MS = 30_000;
 
@@ -62,6 +66,8 @@ export function DashboardAgent({
   const organization = useOrganization();
   const project = useProject();
   const environment = useEnvironment();
+  const user = useUser();
+  const modePreference = user.dashboardPreferences.chatOpenMode;
   const actionPath = `/resources/orgs/${organization.slug}/projects/${project.slug}/env/${environment.slug}/dashboard-agent`;
 
   const [open, setOpen] = useState(false);
@@ -116,27 +122,32 @@ export function DashboardAgent({
     setUnreadWakes(initialUnreadWakes);
     setUnreadWork(initialUnreadWork);
   }, [environment.id, initialUnreadWakes, initialUnreadWork]);
-  // Read lazily: SSR has no localStorage, so the server always renders the floating default.
-  const [mode, setMode] = useState<DashboardAgentMode>(readAgentMode);
+  // Every open starts from the account preference; in-chat switches (toggle, drag-to-dock)
+  // are transient and never write it back.
+  const [mode, setMode] = useState<DashboardAgentMode>(() => initialAgentMode(modePreference));
   const fullscreen = mode === "fullscreen";
 
   const changeMode = useCallback((next: DashboardAgentMode) => {
-    writeAgentMode(next);
     setMode(next);
   }, []);
 
+  // Superseded localStorage keys; harmless to skip if storage is unavailable.
+  useEffect(() => {
+    try {
+      for (const key of STALE_MODE_STORAGE_KEYS) window.localStorage.removeItem(key);
+    } catch {
+      /* ignore */
+    }
+  }, []);
+
   // Pathname only: filter and search-param changes must keep fullscreen.
   const { pathname } = useLocation();
   const previousPathname = useRef(pathname);
   useEffect(() => {
     if (previousPathname.current === pathname) return;
     previousPathname.current = pathname;
-    setMode((current) => {
-      if (current !== "fullscreen") return current;
-      writeAgentMode("floating");
-      return "floating";
-    });
-  }, [pathname]);
+    setMode((current) => (current !== "fullscreen" ? current : initialAgentMode(modePreference)));
+  }, [pathname, modePreference]);
   const [newChatSeq, setNewChatSeq] = useState(0);
   const [requestedMessage, setRequestedMessage] = useState<
     { text: string; seq: number } | undefined
@@ -167,16 +178,14 @@ export function DashboardAgent({
       setOpen(false);
       // Pending requests must be dropped or a stale one re-applies on the next open.
       visibleChat.current = null;
-      setMode((current) => {
-        if (current !== "fullscreen") return current;
-        writeAgentMode("floating");
-        return "floating";
-      });
+      // Any transient in-chat mode switch applied only until close; the next open
+      // starts from the account preference again.
+      setMode(initialAgentMode(modePreference));
       setRequestedMessage(undefined);
       setOpenChatRequest(undefined);
       setWatchRequest(undefined);
     },
-    [openPanel]
+    [openPanel, modePreference]
   );
 
   const openChat = useCallback(

apps/webapp/app/components/dashboard-agent/chat-open-mode.test.ts

@@ -0,0 +1,79 @@
+// @vitest-environment jsdom
+import { createElement, useCallback, useState } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { act } from "react-dom/test-utils";
+import { afterEach, describe, expect, it } from "vitest";
+import { initialAgentMode, type DashboardAgentMode } from "./panel-layout";
+
+describe("initialAgentMode", () => {
+  it("opens in the account preference when one is set", () => {
+    expect(initialAgentMode("rightPanel")).toBe("rightPanel");
+    expect(initialAgentMode("fullscreen")).toBe("fullscreen");
+  });
+
+  it("defaults to floating when there is no preference", () => {
+    expect(initialAgentMode(undefined)).toBe("floating");
+  });
+});
+
+type HarnessHandle = {
+  mode: DashboardAgentMode;
+  changeMode: (mode: DashboardAgentMode) => void;
+  close: () => void;
+  reopen: () => void;
+};
+
+let container: HTMLDivElement | undefined;
+let root: Root | undefined;
+
+afterEach(() => {
+  if (root) act(() => root!.unmount());
+  container?.remove();
+  container = undefined;
+  root = undefined;
+});
+
+// Mirrors DashboardAgent.tsx's own state shape: mode starts from the preference, an
+// in-chat switch is transient (setMode only), and closing reverts to the preference —
+// so the next open starts clean regardless of what the last session left it on.
+function renderHarness(preference: DashboardAgentMode | undefined) {
+  let latest!: HarnessHandle;
+  function Harness() {
+    const [mode, setMode] = useState<DashboardAgentMode>(() => initialAgentMode(preference));
+
+    const changeMode = useCallback((next: DashboardAgentMode) => setMode(next), []);
+    const close = useCallback(() => setMode(initialAgentMode(preference)), []);
+    const reopen = useCallback(() => {}, []);
+
+    // oxlint-disable-next-line react/globals -- test harness capturing the latest state/handlers.
+    latest = { mode, changeMode, close, reopen };
+    return null;
+  }
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+  act(() => {
+    root!.render(createElement(Harness));
+  });
+  return {
+    get current() {
+      return latest;
+    },
+  };
+}
+
+describe("a transient in-chat mode switch reverts on close", () => {
+  it("switching mode while open, then closing and reopening, lands back on the preference", () => {
+    const harness = renderHarness("rightPanel");
+
+    expect(harness.current.mode).toBe("rightPanel");
+
+    act(() => harness.current.changeMode("fullscreen"));
+    expect(harness.current.mode).toBe("fullscreen");
+
+    act(() => harness.current.close());
+    act(() => harness.current.reopen());
+
+    expect(harness.current.mode).toBe("rightPanel");
+  });
+});

apps/webapp/app/components/dashboard-agent/panel-layout.tsx

@@ -15,6 +15,7 @@ import {
   type Point,
   type Rect,
 } from "~/components/primitives/draggableResizableMath";
+import type { ChatOpenMode } from "~/utils/dashboardPreferences";
 import { cn } from "~/utils/cn";
 
 // Mark an element (e.g. a header button, or just its icon) with `data-agent-no-drag` so a
@@ -27,10 +28,7 @@ export type FloatingDragProps = {
   dragHandleClassName: string;
 };
 
-const AGENT_FULLSCREEN_STORAGE_KEY = "tdev:dashboard-agent:fullscreen";
-const AGENT_MODE_STORAGE_KEY = "tdev:dashboard-agent:mode";
-
-export type DashboardAgentMode = "floating" | "rightPanel" | "fullscreen";
+export type DashboardAgentMode = ChatOpenMode;
 
 // V1 floating window: FLOATING_WIDTH x FLOATING_HEIGHT, bottom-right, matching the
 // gallery's own panel frame.
@@ -62,28 +60,10 @@ export function initialFloatingRect() {
   };
 }
 
-// Reads the old boolean key once, so a browser that only ever knew fullscreen keeps its
-// choice after the upgrade to three modes.
-export function readAgentMode(): DashboardAgentMode {
-  if (typeof window === "undefined") return "floating";
-  try {
-    const stored = window.localStorage.getItem(AGENT_MODE_STORAGE_KEY);
-    if (stored === "floating" || stored === "rightPanel" || stored === "fullscreen") return stored;
-    return window.localStorage.getItem(AGENT_FULLSCREEN_STORAGE_KEY) === "true"
-      ? "fullscreen"
-      : "floating";
-  } catch {
-    return "floating";
-  }
-}
-
-export function writeAgentMode(mode: DashboardAgentMode): void {
-  if (typeof window === "undefined") return;
-  try {
-    window.localStorage.setItem(AGENT_MODE_STORAGE_KEY, mode);
-  } catch {
-    /* ignore */
-  }
+/** The mode a chat starts in, and the mode a transient in-chat switch reverts to: the
+ * account preference, defaulting to floating. */
+export function initialAgentMode(preference: DashboardAgentMode | undefined): DashboardAgentMode {
+  return preference ?? "floating";
 }
 
 function agentTakeoverClassName(fullscreen: boolean): string {

apps/webapp/app/routes/account._index/route.tsx

@@ -8,6 +8,9 @@ import {
 } from "@remix-run/server-runtime";
 import { z } from "zod";
 import { EditPencilIcon } from "~/assets/icons/EditPencilIcon";
+import { ChatFloatingPanel } from "~/assets/icons/ChatFloatingPanel";
+import { ChatFullScreen } from "~/assets/icons/ChatFullScreen";
+import { ChatRightPanel } from "~/assets/icons/ChatRightPanel";
 import { UserProfilePhoto } from "~/components/UserProfilePhoto";
 import {
   MainHorizontallyCenteredContainer,
@@ -24,6 +27,7 @@ import {
   DialogTrigger,
 } from "~/components/primitives/Dialog";
 import { Select, SelectItem } from "~/components/primitives/Select";
+import SegmentedControl from "~/components/primitives/SegmentedControl";
 import { Slider } from "~/components/primitives/Slider";
 import { FormError } from "~/components/primitives/FormError";
 import { Header2 } from "~/components/primitives/Headers";
@@ -77,6 +81,7 @@ import {
   updateThemePreference,
   updateUnderlineLinksPreference,
 } from "~/services/dashboardPreferences.server";
+import type { ChatOpenMode } from "~/utils/dashboardPreferences";
 import {
   normalizeIconContrast,
   normalizeSystemDarkTheme,
@@ -778,6 +783,49 @@ function CustomizeSidebarButton({
   );
 }
 
+const CHAT_OPEN_MODE_OPTIONS: {
+  mode: ChatOpenMode;
+  label: string;
+  Icon: typeof ChatFloatingPanel;
+}[] = [
+  { mode: "floating", label: "Floating", Icon: ChatFloatingPanel },
+  { mode: "rightPanel", label: "Right panel", Icon: ChatRightPanel },
+  { mode: "fullscreen", label: "Fullscreen", Icon: ChatFullScreen },
+];
+
+/** The mode Ask Trigger opens in; in-chat mode switches stay transient and don't change this. */
+function ChatOpenModePicker() {
+  const user = useUser();
+  const fetcher = useFetcher();
+  const pending = fetcher.formData?.get("chatOpenMode");
+  const current =
+    typeof pending === "string"
+      ? (pending as ChatOpenMode)
+      : (user.dashboardPreferences.chatOpenMode ?? "floating");
+
+  return (
+    <SegmentedControl
+      name="chat-open-mode"
+      variant="secondary/small"
+      value={current}
+      options={CHAT_OPEN_MODE_OPTIONS.map(({ mode, label, Icon }) => ({
+        value: mode,
+        label: (
+          <span className="flex items-center justify-center" aria-label={label} title={label}>
+            <Icon className="size-4" />
+          </span>
+        ),
+      }))}
+      onChange={(value) =>
+        fetcher.submit(
+          { chatOpenMode: value },
+          { method: "POST", action: "/resources/preferences/chat-open-mode" }
+        )
+      }
+    />
+  );
+}
+
 export default function Page() {
   const user = useUser();
   const { showThemeSwitcher, sidebarContext } = useLoaderData<typeof loader>();
@@ -1094,6 +1142,17 @@ export default function Page() {
                   </div>
                 </div>
               )}
+              <div className="flex min-h-16 w-full items-center border-b border-grid-dimmed">
+                <div className="flex w-full items-center justify-between gap-4">
+                  <div className={cn("flex-1", SETTINGS_ROW_TITLE_GAP)}>
+                    <Label>Ask Trigger chat</Label>
+                    <SettingsRowDescription>Choose where the chat opens</SettingsRowDescription>
+                  </div>
+                  <div className="flex flex-none items-center">
+                    <ChatOpenModePicker />
+                  </div>
+                </div>
+              </div>
               <div className="flex min-h-16 w-full items-center border-b border-grid-dimmed">
                 <div className="flex w-full items-center justify-between gap-4">
                   <div className={cn("flex-1", SETTINGS_ROW_TITLE_GAP)}>

apps/webapp/app/routes/resources.preferences.chat-open-mode.ts

@@ -0,0 +1,23 @@
+import { json, type ActionFunctionArgs } from "@remix-run/node";
+import { updateChatOpenModePreference } from "~/services/dashboardPreferences.server";
+import { requireUser } from "~/services/session.server";
+import { ChatOpenMode } from "~/utils/dashboardPreferences";
+
+export async function action({ request }: ActionFunctionArgs) {
+  const user = await requireUser(request);
+
+  if (user.isImpersonating) {
+    return json({ success: false, error: "Not available" }, { status: 403 });
+  }
+
+  const formData = await request.formData();
+  // Strict, not normalized: an unknown value must fail rather than reset.
+  const chatOpenMode = ChatOpenMode.safeParse(formData.get("chatOpenMode"));
+  if (!chatOpenMode.success) {
+    return json({ success: false, error: "Invalid mode" }, { status: 400 });
+  }
+
+  await updateChatOpenModePreference({ user, chatOpenMode: chatOpenMode.data });
+
+  return json({ success: true });
+}