feat: add user education to New Workspace flow

Author: ammario

src/components/NewWorkspaceModal.tsx

@@ -1,6 +1,7 @@
 import React, { useEffect, useId, useState } from "react";
 import styled from "@emotion/styled";
 import { Modal, ModalInfo, ModalActions, CancelButton, PrimaryButton } from "./Modal";
+import { TooltipWrapper, Tooltip } from "./Tooltip";
 
 const FormGroup = styled.div`
   margin-bottom: 20px;
@@ -54,6 +55,12 @@ const InfoCode = styled.code`
   word-break: break-all;
 `;
 
+const UnderlinedLabel = styled.span`
+  text-decoration: underline dotted #666;
+  text-underline-offset: 2px;
+  cursor: help;
+`;
+
 interface NewWorkspaceModalProps {
   isOpen: boolean;
   projectName: string;
@@ -152,7 +159,23 @@ const NewWorkspaceModal: React.FC<NewWorkspaceModalProps> = ({
     >
       <form onSubmit={(event) => void handleSubmit(event)}>
         <FormGroup>
-          <label htmlFor="branchName">Workspace Branch Name:</label>
+          <label htmlFor="branchName">
+            <TooltipWrapper inline>
+              <UnderlinedLabel>Workspace Branch Name:</UnderlinedLabel>
+              <Tooltip width="wide" position="bottom" interactive>
+                <strong>About Workspaces:</strong>
+                <ul style={{ margin: "4px 0", paddingLeft: "16px" }}>
+                  <li>Uses git worktrees (separate directories sharing .git)</li>
+                  <li>All committed changes visible across all worktrees</li>
+                  <li>Agent can switch branches freely during session</li>
+                  <li>Define branching strategy in AGENTS.md</li>
+                </ul>
+                <a href="https://cmux.io/workspaces.html" target="_blank" rel="noopener noreferrer">
+                  Learn more
+                </a>
+              </Tooltip>
+            </TooltipWrapper>
+          </label>
           <input
             id="branchName"
             type="text"

src/components/Tooltip.tsx

@@ -5,11 +5,14 @@ import styled from "@emotion/styled";
 // Context for passing hover state and trigger ref from wrapper to tooltip
 interface TooltipContextValue {
   isHovered: boolean;
+  setIsHovered: (value: boolean) => void;
   triggerRef: React.RefObject<HTMLElement> | null;
 }
 
 const TooltipContext = createContext<TooltipContextValue>({
   isHovered: false,
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  setIsHovered: () => {},
   triggerRef: null,
 });
 
@@ -22,14 +25,30 @@ interface TooltipWrapperProps {
 export const TooltipWrapper: React.FC<TooltipWrapperProps> = ({ inline = false, children }) => {
   const [isHovered, setIsHovered] = useState(false);
   const triggerRef = useRef<HTMLSpanElement>(null);
+  const leaveTimerRef = useRef<NodeJS.Timeout | null>(null);
+
+  const handleMouseEnter = () => {
+    if (leaveTimerRef.current) {
+      clearTimeout(leaveTimerRef.current);
+      leaveTimerRef.current = null;
+    }
+    setIsHovered(true);
+  };
+
+  const handleMouseLeave = () => {
+    // Delay hiding to allow moving mouse to tooltip
+    leaveTimerRef.current = setTimeout(() => {
+      setIsHovered(false);
+    }, 100);
+  };
 
   return (
-    <TooltipContext.Provider value={{ isHovered, triggerRef }}>
+    <TooltipContext.Provider value={{ isHovered, setIsHovered, triggerRef }}>
       <StyledWrapper
         ref={triggerRef}
         inline={inline}
-        onMouseEnter={() => setIsHovered(true)}
-        onMouseLeave={() => setIsHovered(false)}
+        onMouseEnter={handleMouseEnter}
+        onMouseLeave={handleMouseLeave}
       >
         {children}
       </StyledWrapper>
@@ -49,6 +68,7 @@ interface TooltipProps {
   position?: "top" | "bottom";
   children: React.ReactNode;
   className?: string;
+  interactive?: boolean;
 }
 
 export const Tooltip: React.FC<TooltipProps> = ({
@@ -57,9 +77,11 @@ export const Tooltip: React.FC<TooltipProps> = ({
   position = "top",
   children,
   className = "tooltip",
+  interactive = false,
 }) => {
-  const { isHovered, triggerRef } = useContext(TooltipContext);
+  const { isHovered, setIsHovered, triggerRef } = useContext(TooltipContext);
   const tooltipRef = useRef<HTMLDivElement>(null);
+  const leaveTimerRef = useRef<NodeJS.Timeout | null>(null);
   const [tooltipState, setTooltipState] = useState<{
     style: React.CSSProperties;
     arrowStyle: React.CSSProperties;
@@ -170,6 +192,22 @@ export const Tooltip: React.FC<TooltipProps> = ({
     return () => cancelAnimationFrame(rafId);
   }, [isHovered, align, position, triggerRef]);
 
+  const handleTooltipMouseEnter = () => {
+    if (interactive) {
+      if (leaveTimerRef.current) {
+        clearTimeout(leaveTimerRef.current);
+        leaveTimerRef.current = null;
+      }
+      setIsHovered(true);
+    }
+  };
+
+  const handleTooltipMouseLeave = () => {
+    if (interactive) {
+      setIsHovered(false);
+    }
+  };
+
   if (!isHovered) {
     return null;
   }
@@ -187,6 +225,9 @@ export const Tooltip: React.FC<TooltipProps> = ({
       }}
       width={width}
       className={className}
+      interactive={interactive}
+      onMouseEnter={handleTooltipMouseEnter}
+      onMouseLeave={handleTooltipMouseLeave}
     >
       {children}
       <Arrow style={tooltipState.arrowStyle} />
@@ -195,7 +236,7 @@ export const Tooltip: React.FC<TooltipProps> = ({
   );
 };
 
-const StyledTooltip = styled.div<{ width: string }>`
+const StyledTooltip = styled.div<{ width: string; interactive: boolean }>`
   background-color: #2d2d30;
   color: #cccccc;
   text-align: left;
@@ -209,8 +250,18 @@ const StyledTooltip = styled.div<{ width: string }>`
   font-family: var(--font-primary);
   border: 1px solid #464647;
   box-shadow: 0 2px 8px rgba(0, 0, 0, 0.4);
-  pointer-events: none;
+  pointer-events: ${(props) => (props.interactive ? "auto" : "none")};
   /* No default visibility/opacity - controlled via inline styles */
+
+  a {
+    color: #4ec9b0;
+    text-decoration: underline;
+    cursor: pointer;
+
+    &:hover {
+      color: #6fd9c0;
+    }
+  }
 `;
 
 const Arrow = styled.div`