fix(desktop): welcome banner overlap and missing dismiss control

desktop/src/features/channels/ui/ChannelPane.tsx

@@ -43,12 +43,8 @@ import { ChannelComposerActivityAccessory } from "@/features/channels/ui/Channel
 import {
   containsWelcomePersonaMention,
   WelcomeComposerGuidanceLayer,
-  WELCOME_COMPOSER_BANNER_DISMISS_DURATION_SECONDS,
-  WELCOME_COMPOSER_BANNER_HIDE_BUFFER_MS,
-  WELCOME_COMPOSER_BANNER_SUCCESS_SETTLE_MS,
-  WELCOME_PERSONA_ROTATION_MS,
-  type WelcomeComposerBannerState,
 } from "@/features/channels/ui/WelcomeComposerBanner";
+import { useWelcomeComposerBanner } from "@/features/channels/ui/useWelcomeComposerBanner";
 import { mentionsKnownAgent } from "@/features/channels/ui/ChannelPane.helpers";
 import { HuddleStartingView, HuddleTranscriptIntro } from "@/features/huddle";
 import { useChannelIntro } from "@/features/channels/ui/useChannelIntro";
@@ -168,11 +164,6 @@ export const ChannelPane = React.memo(function ChannelPane({
   const timelineScrollRef = React.useRef<HTMLDivElement>(null);
   const messageTimelineRef = React.useRef<MessageTimelineHandle>(null);
   const composerWrapperRef = React.useRef<HTMLDivElement>(null);
-  const completedWelcomeBannerChannelIdsRef = React.useRef(new Set<string>());
-  const welcomeComposerDismissTimerRef = React.useRef<number | null>(null);
-  const welcomeComposerHideTimerRef = React.useRef<number | null>(null);
-  const [welcomeComposerBannerState, setWelcomeComposerBannerState] =
-    React.useState<WelcomeComposerBannerState>("prompt");
   const { goChannel } = useAppNavigation();
   const prepareDmSendChannel = usePrepareDmSendChannel(
     activeChannel,
@@ -221,36 +212,11 @@ export const ChannelPane = React.memo(function ChannelPane({
     "css-variable",
     () => messageTimelineRef.current?.settleAtBottom() ?? false,
   );
-  const clearWelcomeComposerDismissTimer = React.useCallback(() => {
-    if (welcomeComposerDismissTimerRef.current !== null) {
-      window.clearTimeout(welcomeComposerDismissTimerRef.current);
-      welcomeComposerDismissTimerRef.current = null;
-    }
-    if (welcomeComposerHideTimerRef.current !== null) {
-      window.clearTimeout(welcomeComposerHideTimerRef.current);
-      welcomeComposerHideTimerRef.current = null;
-    }
-  }, []);
-  React.useEffect(
-    () => () => clearWelcomeComposerDismissTimer(),
-    [clearWelcomeComposerDismissTimer],
-  );
-  React.useEffect(() => {
-    clearWelcomeComposerDismissTimer();
-    if (
-      activeChannelId &&
-      isActiveWelcomeChannel &&
-      completedWelcomeBannerChannelIdsRef.current.has(activeChannelId)
-    ) {
-      setWelcomeComposerBannerState("hidden");
-      return;
-    }
-    setWelcomeComposerBannerState("prompt");
-  }, [
-    activeChannelId,
-    clearWelcomeComposerDismissTimer,
-    isActiveWelcomeChannel,
-  ]);
+  const {
+    bannerState: welcomeComposerBannerState,
+    completeBanner: completeWelcomeComposerBanner,
+    dismissBanner: handleDismissWelcomeBanner,
+  } = useWelcomeComposerBanner(activeChannelId, isActiveWelcomeChannel);
   const isEditInThread =
     editTarget != null &&
     threadHeadMessage != null &&
@@ -330,31 +296,6 @@ export const ChannelPane = React.memo(function ChannelPane({
 
     return pubkeys;
   }, [activityAgents, agentPubkeys, agentSessionAgents]);
-  const completeWelcomeComposerBanner = React.useCallback(() => {
-    if (!activeChannelId || !isActiveWelcomeChannel) {
-      return;
-    }
-
-    clearWelcomeComposerDismissTimer();
-    completedWelcomeBannerChannelIdsRef.current.add(activeChannelId);
-    setWelcomeComposerBannerState("complete");
-    welcomeComposerDismissTimerRef.current = window.setTimeout(() => {
-      setWelcomeComposerBannerState("dismissing");
-      welcomeComposerDismissTimerRef.current = null;
-      welcomeComposerHideTimerRef.current = window.setTimeout(
-        () => {
-          setWelcomeComposerBannerState("hidden");
-          welcomeComposerHideTimerRef.current = null;
-        },
-        WELCOME_COMPOSER_BANNER_DISMISS_DURATION_SECONDS * 1000 +
-          WELCOME_COMPOSER_BANNER_HIDE_BUFFER_MS,
-      );
-    }, WELCOME_PERSONA_ROTATION_MS + WELCOME_COMPOSER_BANNER_SUCCESS_SETTLE_MS);
-  }, [
-    activeChannelId,
-    clearWelcomeComposerDismissTimer,
-    isActiveWelcomeChannel,
-  ]);
   const handleSendMessage = React.useCallback(
     async (
       content: string,
@@ -739,6 +680,7 @@ export const ChannelPane = React.memo(function ChannelPane({
               >
                 {isActiveWelcomeChannel && !timeoutState.active ? (
                   <WelcomeComposerGuidanceLayer
+                    onDismiss={handleDismissWelcomeBanner}
                     settingUp={welcomeKickoffSettingUp}
                     state={welcomeComposerBannerState}
                   >

desktop/src/features/channels/ui/WelcomeComposerBanner.tsx

@@ -1,6 +1,6 @@
 import * as React from "react";
 import { AnimatePresence, motion, useReducedMotion } from "motion/react";
-import { Bot, Check } from "lucide-react";
+import { Bot, Check, X } from "lucide-react";
 
 import { ComposerDockGlassBackdrop } from "@/features/messages/ui/ComposerDockBackdrop";
 import { cn } from "@/shared/lib/cn";
@@ -291,9 +291,15 @@ type WelcomeComposerBannerProps = {
    * banner during this window.
    */
   settingUp?: boolean;
+  /**
+   * Called when the user dismisses the banner manually via the close button.
+   * Only rendered while `state === "prompt"`.
+   */
+  onDismiss?: () => void;
 };
 
 export function WelcomeComposerBanner({
+  onDismiss,
   settingUp = false,
   state,
 }: WelcomeComposerBannerProps) {
@@ -307,7 +313,7 @@ export function WelcomeComposerBanner({
         animate={{
           height: state === "dismissing" ? 0 : "auto",
         }}
-        className="overflow-visible"
+        className="overflow-hidden"
         initial={false}
         transition={{
           duration:
@@ -326,7 +332,7 @@ export function WelcomeComposerBanner({
                 : 0,
           }}
           className={cn(
-            "relative z-[1] mx-5 -mb-3 flex items-center gap-2 rounded-t-2xl border border-b-0 px-4 pb-5 pt-2.5 text-sm leading-5 transition-colors",
+            "relative z-[1] mx-5 mb-0 flex items-center gap-2 rounded-t-2xl border border-b-0 px-4 pb-5 pt-2.5 text-sm leading-5 transition-colors",
             state !== "prompt"
               ? "border-emerald-500/30 bg-emerald-500/15 text-foreground"
               : "border-border/60 bg-muted/55 text-muted-foreground",
@@ -376,7 +382,7 @@ export function WelcomeComposerBanner({
             {state !== "prompt" ? (
               <motion.span
                 animate="animate"
-                className="min-w-0"
+                className="min-w-0 flex-1"
                 data-animation-target="success-copy"
                 initial="initial"
                 key="complete-copy"
@@ -387,7 +393,7 @@ export function WelcomeComposerBanner({
             ) : settingUp ? (
               <motion.span
                 animate="animate"
-                className="min-w-0"
+                className="min-w-0 flex-1"
                 data-testid="welcome-composer-setting-up-copy"
                 exit="exit"
                 initial="initial"
@@ -399,7 +405,7 @@ export function WelcomeComposerBanner({
             ) : (
               <motion.span
                 animate="animate"
-                className="min-w-0"
+                className="min-w-0 flex-1"
                 exit="exit"
                 initial="initial"
                 key="prompt-copy"
@@ -410,6 +416,17 @@ export function WelcomeComposerBanner({
               </motion.span>
             )}
           </AnimatePresence>
+          {state === "prompt" && onDismiss && !settingUp ? (
+            <button
+              aria-label="Dismiss hint"
+              className="ml-auto flex h-5 w-5 shrink-0 items-center justify-center rounded-full text-muted-foreground/60 transition-colors hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              data-testid="welcome-composer-dismiss-button"
+              onClick={onDismiss}
+              type="button"
+            >
+              <X aria-hidden className="h-3 w-3" />
+            </button>
+          ) : null}
         </motion.div>
       </motion.div>
     </AnimatePresence>
@@ -422,22 +439,22 @@ type WelcomeComposerGuidanceLayerProps = WelcomeComposerBannerProps & {
 
 export function WelcomeComposerGuidanceLayer({
   children,
+  onDismiss,
   settingUp,
   state,
 }: WelcomeComposerGuidanceLayerProps) {
   return (
-    <div
-      className="absolute inset-x-0 bottom-full z-[-1]"
-      data-testid="welcome-composer-guidance-layer"
-    >
-      <div className="relative">
-        <ComposerDockGlassBackdrop
-          className="absolute inset-x-5 top-0 bottom-3 z-0 rounded-t-2xl"
-          testId="welcome-composer-guidance-backdrop"
-        />
-        {children}
-        <WelcomeComposerBanner settingUp={settingUp} state={state} />
-      </div>
+    <div className="relative" data-testid="welcome-composer-guidance-layer">
+      <ComposerDockGlassBackdrop
+        className="absolute inset-x-5 top-0 bottom-3 z-0 rounded-t-2xl"
+        testId="welcome-composer-guidance-backdrop"
+      />
+      {children}
+      <WelcomeComposerBanner
+        onDismiss={onDismiss}
+        settingUp={settingUp}
+        state={state}
+      />
     </div>
   );
 }

desktop/src/features/channels/ui/useWelcomeComposerBanner.ts

@@ -0,0 +1,99 @@
+import * as React from "react";
+
+import {
+  WELCOME_COMPOSER_BANNER_DISMISS_DURATION_SECONDS,
+  WELCOME_COMPOSER_BANNER_HIDE_BUFFER_MS,
+  WELCOME_COMPOSER_BANNER_SUCCESS_SETTLE_MS,
+  WELCOME_PERSONA_ROTATION_MS,
+  type WelcomeComposerBannerState,
+} from "@/features/channels/ui/WelcomeComposerBanner";
+
+/**
+ * Manages the Welcome-channel composer hint banner's state machine.
+ *
+ * Tracks which channels have been completed within the session so the banner
+ * stays hidden on re-entry. Exposes three transitions:
+ * - `completeBanner`: agent-mention path — plays the "Nice work." success
+ *   animation before auto-dismissing.
+ * - `dismissBanner`: manual X-button path — immediately begins the slide-down
+ *   dismiss animation.
+ */
+export function useWelcomeComposerBanner(
+  activeChannelId: string | null,
+  isActiveWelcomeChannel: boolean,
+): {
+  bannerState: WelcomeComposerBannerState;
+  completeBanner: () => void;
+  dismissBanner: () => void;
+} {
+  const completedChannelIdsRef = React.useRef(new Set<string>());
+  const dismissTimerRef = React.useRef<number | null>(null);
+  const hideTimerRef = React.useRef<number | null>(null);
+  const [bannerState, setBannerState] =
+    React.useState<WelcomeComposerBannerState>("prompt");
+
+  const clearTimers = React.useCallback(() => {
+    if (dismissTimerRef.current !== null) {
+      window.clearTimeout(dismissTimerRef.current);
+      dismissTimerRef.current = null;
+    }
+    if (hideTimerRef.current !== null) {
+      window.clearTimeout(hideTimerRef.current);
+      hideTimerRef.current = null;
+    }
+  }, []);
+
+  React.useEffect(() => () => clearTimers(), [clearTimers]);
+
+  React.useEffect(() => {
+    clearTimers();
+    if (
+      activeChannelId &&
+      isActiveWelcomeChannel &&
+      completedChannelIdsRef.current.has(activeChannelId)
+    ) {
+      setBannerState("hidden");
+      return;
+    }
+    setBannerState("prompt");
+  }, [activeChannelId, clearTimers, isActiveWelcomeChannel]);
+
+  const scheduleHide = React.useCallback(() => {
+    hideTimerRef.current = window.setTimeout(
+      () => {
+        setBannerState("hidden");
+        hideTimerRef.current = null;
+      },
+      WELCOME_COMPOSER_BANNER_DISMISS_DURATION_SECONDS * 1000 +
+        WELCOME_COMPOSER_BANNER_HIDE_BUFFER_MS,
+    );
+  }, []);
+
+  const completeBanner = React.useCallback(() => {
+    if (!activeChannelId || !isActiveWelcomeChannel) {
+      return;
+    }
+
+    clearTimers();
+    completedChannelIdsRef.current.add(activeChannelId);
+    setBannerState("complete");
+    dismissTimerRef.current = window.setTimeout(() => {
+      setBannerState("dismissing");
+      dismissTimerRef.current = null;
+      scheduleHide();
+    }, WELCOME_PERSONA_ROTATION_MS + WELCOME_COMPOSER_BANNER_SUCCESS_SETTLE_MS);
+  }, [activeChannelId, clearTimers, isActiveWelcomeChannel, scheduleHide]);
+
+  const dismissBanner = React.useCallback(() => {
+    if (!activeChannelId || !isActiveWelcomeChannel) {
+      return;
+    }
+
+    clearTimers();
+    completedChannelIdsRef.current.add(activeChannelId);
+    setBannerState("dismissing");
+    scheduleHide();
+  }, [activeChannelId, clearTimers, isActiveWelcomeChannel, scheduleHide]);
+
+  return { bannerState, completeBanner, dismissBanner };
+}