feat(huddle): add 'headphones recommended' banner while AEC is missing

Adds a session-dismissable banner inside HuddleBar that warns users to use
headphones until echo cancellation lands. Lives in a new tiny
HeadphonesNotice component so it can be deleted in one diff when the AEC
follow-up PR flips aecMissing to false.

Why it's needed for this PR: the FIFO/jitter fix in commit 25b380f and
the protocol v2 frame header in commit b6dd829 together make 10-person
huddles work *for everyone wearing headphones*. The play path is still
native rodio (outside the WebView render graph), so the browser's WebRTC
echo canceller has nothing to cancel against. Two users on speakers in
the same physical room would hear themselves echo. The banner makes
that limitation visible up-front rather than letting users discover it
when they're already in a 10-person meeting.

Quinn's tripwire from the design thread: AEC v1 is the next PR after
this one merges, not 'soon' or 'in the backlog'.

Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>

Author: tlongwell-block

desktop/src/features/huddle/components/HeadphonesNotice.tsx

@@ -0,0 +1,40 @@
+import { Headphones } from "lucide-react";
+
+/**
+ * "Headphones recommended — echo cancellation lands in the next release."
+ *
+ * Session-dismissable banner shown on the active HuddleBar while the desktop
+ * client lacks an echo-cancellation reference. The current play path is
+ * native rodio (outside the WebView render graph), so the browser's WebRTC
+ * AEC cannot suppress local-speaker → mic feedback for users on speakers.
+ *
+ * The follow-up PR moves remote-peer playout into WebAudio inside the same
+ * `AudioContext` as `getUserMedia({ echoCancellation: true })`. When that
+ * lands, the parent component flips `aecMissing` to false and this banner
+ * (and this file) become removable in a single diff.
+ *
+ * State (`dismissed`, `aecMissing`) lives in the parent so the parent can
+ * decide whether to render at all. Keep this component dumb so the
+ * deletion later is mechanical.
+ */
+export function HeadphonesNotice({ onDismiss }: { onDismiss: () => void }) {
+  return (
+    <output
+      data-testid="huddle-headphones-notice"
+      className="flex items-center gap-1.5 rounded bg-amber-500/10 px-2 py-1 text-xs text-amber-700 dark:text-amber-300"
+    >
+      <Headphones className="h-3 w-3" />
+      <span className="max-w-[260px] truncate">
+        Headphones recommended — echo cancellation lands in the next release.
+      </span>
+      <button
+        aria-label="Dismiss headphones notice for this session"
+        className="ml-1 opacity-60 hover:opacity-100"
+        onClick={onDismiss}
+        type="button"
+      >
+        ✕
+      </button>
+    </output>
+  );
+}

desktop/src/features/huddle/components/HuddleBar.tsx

@@ -8,6 +8,7 @@ import { Button } from "@/shared/ui/button";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/shared/ui/tooltip";
 import { useHuddle } from "../HuddleContext";
 import { AddAgentDialog, type AgentAddResult } from "./AddAgentDialog";
+import { HeadphonesNotice } from "./HeadphonesNotice";
 import { MicControls, SpeakerControls } from "./MicControls";
 import { ParticipantList } from "./ParticipantList";
 
@@ -60,6 +61,16 @@ export function HuddleBar({ className }: HuddleBarProps) {
   const isPttMode = voiceInputMode === "push_to_talk";
   const [state, setState] = React.useState<HuddleState | null>(null);
   const [isMuted, setIsMuted] = React.useState(false);
+  // Session-dismissable "use headphones" notice. The desktop client plays
+  // remote peer audio via native rodio, outside the WebView render graph,
+  // so the browser's echo canceller has no far-end reference to cancel
+  // against. Until the WebAudio AEC follow-up PR lands, two people on
+  // speakers in the same physical room will hear themselves echo. The
+  // banner stays visible across huddle start/stop within a single page
+  // load; it auto-removes when the AEC plumbing lands and the detection
+  // below flips to false.
+  const [headphonesNoticeDismissed, setHeadphonesNoticeDismissed] =
+    React.useState(false);
   const ttsEnabled = state?.tts_enabled ?? true;
   const [isLeaving, setIsLeaving] = React.useState(false);
   const [showAddAgent, setShowAddAgent] = React.useState(false);
@@ -165,6 +176,12 @@ export function HuddleBar({ className }: HuddleBarProps) {
   if (!state || (state.phase !== "active" && state.phase !== "connected"))
     return null;
 
+  // Self-removing detection: remote-peer audio plays through native rodio
+  // today (outside the WebView render graph), so the browser's AEC has no
+  // far-end reference. The AEC follow-up PR flips this constant in the
+  // same diff that moves playout into WebAudio.
+  const aecMissing = true;
+
   async function handleLeave() {
     if (isLeaving) return;
     setIsLeaving(true);
@@ -226,6 +243,13 @@ export function HuddleBar({ className }: HuddleBarProps) {
         </div>
       )}
 
+      {/* Echo-cancellation pre-PR notice. Removed when AEC plumbing lands. */}
+      {aecMissing && !headphonesNoticeDismissed && (
+        <HeadphonesNotice
+          onDismiss={() => setHeadphonesNoticeDismissed(true)}
+        />
+      )}
+
       {/* Model download progress */}
       {modelStatus &&
         (modelStatus.stt !== "ready" || modelStatus.tts !== "ready") && (