Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

Add an opposite-edge dictation pill for Agent mode (#1867)

voidecc7852e5da7
diff --git a/preload.js b/preload.js
index 3fdd2ebca..13feaa022 100644
--- a/preload.js
+++ b/preload.js
@@ -86,14 +86,41 @@ contextBridge.exposeInMainWorld("electronAPI", {
onToggleTranslation: registerListener("toggle-translation", (callback) => () => callback()),
onStartDictation: registerListener("start-dictation", (callback) => () => callback()),
onStopDictation: registerListener("stop-dictation", (callback) => () => callback()),
- onPrepareDictation: registerListener("prepare-dictation", (callback) => () => callback()),
+ onPrepareDictation: registerListener(
+ "prepare-dictation",
+ (callback) => (_event, options) => callback(options)
+ ),
onCancelDictationPreparation: registerListener(
"cancel-dictation-preparation",
(callback) => () => callback()
),
+ onCancelDictation: registerListener("cancel-dictation", (callback) => () => callback()),
micWarmHoldChanged: (active) => ipcRenderer.send("mic-warm-hold-changed", active),
- dictationLifecycleStateChanged: (state) =>
- ipcRenderer.send("dictation-lifecycle-state-changed", state),
+ dictationLifecycleStateChanged: (state, inputKind) =>
+ ipcRenderer.send("dictation-lifecycle-state-changed", state, inputKind),
+ dictationAudioLevelChanged: (level) =>
+ ipcRenderer.send("dictation-audio-level-changed", level),
+ toggleAgentPanelDictation: () => ipcRenderer.invoke("toggle-agent-panel-dictation"),
+ cancelAgentPanelDictation: () => ipcRenderer.invoke("cancel-agent-panel-dictation"),
+ getAgentDictationPillState: () => ipcRenderer.invoke("get-agent-dictation-pill-state"),
+ resizeAgentDictationPillToContent: (surfaceHeight) =>
+ ipcRenderer.invoke("resize-agent-dictation-pill-to-content", surfaceHeight),
+ setAgentDictationPillInteractivity: (interactive) =>
+ ipcRenderer.invoke("set-agent-dictation-pill-interactivity", interactive),
+ onAgentDictationPillStateChanged: registerListener(
+ "agent-dictation-pill-state-changed",
+ (callback) => (_event, state) => callback(state)
+ ),
+ onAgentDictationPillAudioLevelChanged: registerListener(
+ "agent-dictation-pill-audio-level-changed",
+ (callback) => (_event, level) => callback(level)
+ ),
+ showAgentDictationFinalTranscript: (text) =>
+ ipcRenderer.send("show-agent-dictation-final-transcript", text),
+ onAgentDictationPillFinalTranscript: registerListener(
+ "agent-dictation-pill-final-transcript",
+ (callback) => (_event, text) => callback(text)
+ ),
// Database functions
saveTranscription: (text, rawText, options) =>
diff --git a/src/App.jsx b/src/App.jsx
index 1e566ab18..fce8bb8c6 100644
--- a/src/App.jsx
+++ b/src/App.jsx
@@ -11,6 +11,7 @@ import { useAssistantPanel } from "./hooks/useAssistantPanel";
import { useLiveTranscriptPanel } from "./hooks/useLiveTranscriptPanel";
import { useMainWindowSizeOwner } from "./hooks/useMainWindowSizeOwner";
import { useMainProcessNotifications } from "./hooks/useMainProcessNotifications";
+import { useListeningEntrancePhase } from "./hooks/useListeningEntrancePhase";
import { useWindowResizeCompensation } from "./hooks/useWindowResizeCompensation";
import { useSettingsStore } from "./stores/settingsStore";
import { isAgentAllowed } from "./stores/policyRules";
@@ -24,7 +25,6 @@ import { PillCommandMenu } from "./components/dictation/PillCommandMenu";
import { createMainWindowResizeCoordinator } from "./utils/mainWindowResizeCoordinator";
import {
ASSISTANT_FOOTER_TRANSITION_TIMING,
- getListeningEntranceTimeline,
LIVE_TRANSCRIPT_ENTRANCE_TIMING,
resolveLiveTranscriptEntrancePresentation,
resolveAssistantFooterPresentation,
@@ -38,6 +38,7 @@ import {
isVoicePillActivationKey,
shouldActivateVoicePill,
shouldOfferLiveTranscriptReopen,
+ shouldSuppressPillForAssistantActions,
} from "./helpers/voicePillPresentation";
const formatPillHotkeyLabel = (value) =>
@@ -195,7 +196,16 @@ export default function App() {
dismissDictationError,
onDictationError: handleDictationError,
getAssistantSelectionContext: assistant.getSelectionContext,
- onShowTranscript: (text) => liveTranscriptApiRef.current?.showFinalText(text),
+ onShowTranscript: (text) => {
+ // While the Agent panel is open the main window's transcript is suppressed
+ // (openPanel refuses under assistantOpenRef); the companion hosts it instead.
+ if (assistantOpenRef.current) {
+ window.electronAPI?.showAgentDictationFinalTranscript?.(text);
+ return;
+ }
+ liveTranscriptApiRef.current?.showFinalText(text);
+ },
+ assistantOpenRef,
});
const isVisuallyProcessing = isProcessing || isPreparing || isStopping;
@@ -248,53 +258,37 @@ export default function App() {
}
}, [isAssistantVoice, isProcessing, assistantOpenRef, beginAssistantThinking]);
+ // While the Agent panel is open, plain dictation renders on the
+ // opposite-edge companion pill — neither its recording nor its processing
+ // may animate the footer pill here. Ownership returns at close INTENT
+ // (assistant.closing), not at fade completion: beginClose hides the
+ // companion immediately, so waiting for the fade would leave a running
+ // recording with no visual owner for the fade duration.
+ const voicePillOwnsActivity = !assistant.open || assistant.closing || isAssistantVoice;
+ const voicePillIsRecording = isRecording && voicePillOwnsActivity;
+ const voicePillIsProcessing = (isProcessing || isStopping) && voicePillOwnsActivity;
const voiceActivity = resolveVoiceActivityPresentation({
- isRecording,
+ isRecording: voicePillIsRecording,
// Mic warm-up is an acknowledged press, not work on a transcript. Keeping
// isPreparing out of the thinking state leaves the press on the pulsing
// "processing" mic-state pill instead of lighting the glow at hotkey time.
- isProcessing: isProcessing || isStopping,
+ isProcessing: voicePillIsProcessing,
isAssistantVoice,
assistantThinking: assistant.thinking || assistant.busy,
});
- const [listeningEntrancePhase, setListeningEntrancePhase] = useState("idle");
- useLayoutEffect(() => {
- if (!isRecording) {
- setListeningEntrancePhase("idle");
- return;
- }
-
- setListeningEntrancePhase("thinking");
- const timeline = getListeningEntranceTimeline();
- const expansionTimer = setTimeout(
- () => setListeningEntrancePhase("expanding"),
- timeline.expandAtMs
- );
- const settledTimer = setTimeout(
- () => setListeningEntrancePhase("settled"),
- timeline.settleAtMs
- );
- const waveformTimer = setTimeout(
- () => setListeningEntrancePhase("waveform"),
- timeline.waveformAtMs
- );
-
- return () => {
- clearTimeout(expansionTimer);
- clearTimeout(settledTimer);
- clearTimeout(waveformTimer);
- };
- }, [isRecording]);
+ const listeningEntrancePhase = useListeningEntrancePhase(voicePillIsRecording);
const listeningEntrance = resolveListeningEntrancePresentation({
- isRecording,
+ isRecording: voicePillIsRecording,
phase: listeningEntrancePhase,
});
- const isCompactPill = isRecording ? listeningEntrance.compactPill : voiceActivity.compactPill;
+ const isCompactPill = voicePillIsRecording
+ ? listeningEntrance.compactPill
+ : voiceActivity.compactPill;
// The native window grows during the entrance's static thinking hold, not
// when the pill starts its width transition: a setBounds landing mid
// animation forces compositor work that visibly stutters the expansion, and
// the growing pill can clip against the old bounds if the resize IPC lags.
- const windowFitsCompactPill = isRecording || voiceActivity.compactPill;
+ const windowFitsCompactPill = voicePillIsRecording || voiceActivity.compactPill;
const { dictationErrorPillHandoffActive } = useMainWindowSizeOwner({
requestMainWindowSize,
@@ -353,6 +347,16 @@ export default function App() {
return () => unsubscribe?.();
}, [cancelRecording]);
+ // The Agent companion pill's cancel button routes here: only this renderer
+ // owns the recording, so it decides what "cancel" means at arrival time.
+ useEffect(() => {
+ const unsubscribe = window.electronAPI?.onCancelDictation?.(() => {
+ if (isRecording || isPreparing) cancelRecording();
+ else if (isProcessing) cancelProcessing();
+ });
+ return () => unsubscribe?.();
+ }, [isRecording, isPreparing, isProcessing, cancelRecording, cancelProcessing]);
+
// Auto-hide the floating icon when idle (setting enabled or dictation cycle completed)
useEffect(() => {
let hideTimeout;
@@ -535,7 +539,12 @@ export default function App() {
// Keep one pill DOM node alive while final Agent actions own the footer. On
// close it can fade and travel from the panel dock instead of mounting at
// the resting dock halfway through the surface contraction.
- const assistantActionsSuppressPill = assistant.open && !assistantFooter.pillVisible;
+ const assistantActionsSuppressPill = shouldSuppressPillForAssistantActions({
+ assistantOpen: assistant.open,
+ footerPillVisible: assistantFooter.pillVisible,
+ assistantClosing: assistant.closing,
+ hasLiveActivity: voicePillIsRecording || voicePillIsProcessing,
+ });
const pillVisuallySuppressed = dictationErrorSuppressesPill || assistantActionsSuppressPill;
const pillInteractionSuppressed = pillVisuallySuppressed || assistant.closing;
diff --git a/src/AppRouter.jsx b/src/AppRouter.jsx
index 37ac432dc..d281fff70 100644
--- a/src/AppRouter.jsx
+++ b/src/AppRouter.jsx
@@ -1,6 +1,7 @@
import React, { Suspense, useEffect, useState } from "react";
import { useTranslation } from "react-i18next";
import App from "./App.jsx";
+import AgentDictationPillOverlay from "./components/dictation/AgentDictationPillOverlay.tsx";
import MeetingNotificationOverlay from "./components/MeetingNotificationOverlay.tsx";
import ReauthenticationScreen from "./components/ReauthenticationScreen.tsx";
import UpdateNotificationOverlay from "./components/UpdateNotificationOverlay.tsx";
@@ -33,6 +34,10 @@ export default function AppRouter() {
return <UpdateNotificationOverlay />;
}
+ if (params.includes("agent-dictation-pill=true")) {
+ return <AgentDictationPillOverlay />;
+ }
+
return <MainApp />;
}
diff --git a/src/components/dictation/AgentDictationPillOverlay.tsx b/src/components/dictation/AgentDictationPillOverlay.tsx
new file mode 100644
index 000000000..6ebc292cc
--- /dev/null
+++ b/src/components/dictation/AgentDictationPillOverlay.tsx
@@ -0,0 +1,281 @@
+import {
+ useCallback,
+ useEffect,
+ useLayoutEffect,
+ useRef,
+ useState,
+ type CSSProperties,
+} from "react";
+import { X } from "lucide-react";
+import { useTranslation } from "react-i18next";
+import { useListeningEntrancePhase } from "../../hooks/useListeningEntrancePhase";
+import { useLiveTranscriptPanel } from "../../hooks/useLiveTranscriptPanel";
+import {
+ LIVE_TRANSCRIPT_ENTRANCE_TIMING,
+ resolveCompanionPillInteractive,
+ resolveListeningEntrancePresentation,
+ resolveLiveTranscriptEntrancePresentation,
+ resolveVoiceActivityPresentation,
+ resolveVoicePillDock,
+ resolveVoicePillInteraction,
+ shouldOfferLiveTranscriptReopen,
+} from "../../helpers/voicePillPresentation";
+import { LiveTranscriptPanel, type LiveTranscriptPhase } from "./LiveTranscriptPanel";
+import { VoiceModePanelCore, type VoiceModePanelStage } from "./VoiceModePanelCore";
+import { VoicePill, type VoicePillState } from "./VoicePill";
+import "../../styles/agent-dictation-pill.css";
+
+type DictationLifecycle = "idle" | "preparing" | "recording" | "processing";
+type HorizontalDirection = "left" | "right";
+type CompanionState = {
+ lifecycle: DictationLifecycle;
+ interactive: boolean;
+ horizontalDirection: HorizontalDirection;
+};
+
+const DEFAULT_STATE: CompanionState = {
+ lifecycle: "idle",
+ interactive: true,
+ horizontalDirection: "left",
+};
+const UNAVAILABLE_RESIZE = { success: false, message: "Window not available" };
+
+export default function AgentDictationPillOverlay() {
+ const { t } = useTranslation();
+ const [companionState, setCompanionState] = useState(DEFAULT_STATE);
+ const [hovered, setHovered] = useState(false);
+ const audioLevelRef = useRef<number | null>(null);
+ const assistantOpenRef = useRef(false);
+
+ useEffect(() => {
+ let disposed = false;
+ const applyState = (state: CompanionState) => {
+ if (!disposed) setCompanionState(state);
+ };
+ const disposeState = window.electronAPI.onAgentDictationPillStateChanged?.(applyState);
+ const disposeAudio = window.electronAPI.onAgentDictationPillAudioLevelChanged?.((level) => {
+ audioLevelRef.current = level;
+ });
+ window.electronAPI
+ .getAgentDictationPillState?.()
+ .then(applyState)
+ .catch(() => {});
+ return () => {
+ disposed = true;
+ disposeState?.();
+ disposeAudio?.();
+ };
+ }, []);
+
+ // hideAgentDictationPill force-resets native click-through, but a hidden
+ // window never fires mouseleave, so React's hovered flag would survive the
+ // hide and desync the interactivity effect on the next show (first click
+ // falls through). Electron marks hidden windows document.hidden.
+ useEffect(() => {
+ const handleVisibilityChange = () => {
+ if (document.visibilityState === "hidden") setHovered(false);
+ };
+ document.addEventListener("visibilitychange", handleVisibilityChange);
+ return () => document.removeEventListener("visibilitychange", handleVisibilityChange);
+ }, []);
+
+ const resizeToContent = useCallback(
+ (height: number) =>
+ window.electronAPI.resizeAgentDictationPillToContent?.(height) ??
+ Promise.resolve(UNAVAILABLE_RESIZE),
+ []
+ );
+ const isRecording = companionState.lifecycle === "recording";
+ const isProcessing = companionState.lifecycle === "processing";
+ const isPreparing = companionState.lifecycle === "preparing";
+ const liveTranscript = useLiveTranscriptPanel({
+ resizeToContent,
+ assistantOpenRef,
+ onWillOpen: undefined,
+ isRecording,
+ isProcessing,
+ isAssistantVoice: false,
+ });
+ const { close: closeLiveTranscript, mounted: liveTranscriptMounted } = liveTranscript;
+
+ const { showFinalText } = liveTranscript;
+ useEffect(
+ () =>
+ window.electronAPI.onAgentDictationPillFinalTranscript?.((text) => {
+ showFinalText(text);
+ }),
+ [showFinalText]
+ );
+
+ useEffect(() => {
+ if (!liveTranscriptMounted) {
+ void window.electronAPI.resizeAgentDictationPillToContent?.(null);
+ }
+ }, [liveTranscriptMounted]);
+
+ useEffect(() => {
+ if (!companionState.interactive && liveTranscriptMounted) {
+ closeLiveTranscript({ clear: true });
+ }
+ }, [closeLiveTranscript, companionState.interactive, liveTranscriptMounted]);
+
+ // The window is click-through (macOS) until something needs real clicks:
+ // the hovered pill, or the Live Transcript surface with its controls.
+ const captureMouseEvents = hovered || liveTranscriptMounted;
+ useEffect(() => {
+ void window.electronAPI.setAgentDictationPillInteractivity?.(captureMouseEvents);
+ }, [captureMouseEvents]);
+
+ const listeningEntrancePhase = useListeningEntrancePhase(isRecording);
+ useLayoutEffect(() => {
+ if (!isRecording) audioLevelRef.current = null;
+ }, [isRecording]);
+
+ const listeningEntrance = resolveListeningEntrancePresentation({
+ isRecording,
+ phase: listeningEntrancePhase,
+ });
+ const voiceActivity = resolveVoiceActivityPresentation({
+ isRecording,
+ isProcessing,
+ isAssistantVoice: false,
+ assistantThinking: false,
+ });
+ const liveTranscriptEntrance = resolveLiveTranscriptEntrancePresentation(
+ liveTranscript.entrancePhase
+ );
+ const canReopenLiveTranscript = shouldOfferLiveTranscriptReopen({
+ manuallyCollapsed: liveTranscript.manuallyCollapsed,
+ isRecording,
+ isProcessing,
+ isAssistantVoice: false,
+ });
+ const horizontalDirection = companionState.horizontalDirection;
+ const voicePillDock = resolveVoicePillDock({
+ liveTranscriptOpen: liveTranscript.open,
+ liveTranscriptEntrancePhase: liveTranscript.entrancePhase,
+ assistantOpen: false,
+ panelStartPosition: `bottom-${horizontalDirection}`,
+ horizontalDirection,
+ });
+ const voicePillTravelDuration =
+ liveTranscript.open && liveTranscript.entrancePhase === "encapsulate"
+ ? LIVE_TRANSCRIPT_ENTRANCE_TIMING.encapsulateMs
+ : LIVE_TRANSCRIPT_ENTRANCE_TIMING.horizontalMs;
+ const state = (listeningEntrance.activeState ||
+ voiceActivity.activeState ||
+ (isPreparing
+ ? "processing"
+ : hovered && companionState.interactive
+ ? "hover"
+ : "idle")) as VoicePillState;
+ const expanded = isRecording ? listeningEntrance.compactPill : voiceActivity.compactPill;
+ // The shared rule (a mounted transcript locks the pill except while
+ // recording) comes from the tested helper; the companion additionally
+ // requires main-process consent and no transcript still processing.
+ const { pillInteractive: surfaceInteractive, cancelVisible } = resolveVoicePillInteraction({
+ assistantMounted: false,
+ liveTranscriptMounted: liveTranscript.mounted,
+ isRecording,
+ isProcessing,
+ isHovered: hovered,
+ });
+ const pillInteractive = resolveCompanionPillInteractive({
+ mainProcessInteractive: companionState.interactive,
+ surfaceInteractive,
+ isProcessing,
+ canReopenLiveTranscript,
+ });
+ const label = isRecording
+ ? t("app.mic.recording")
+ : isProcessing || isPreparing
+ ? t("app.mic.processing")
+ : canReopenLiveTranscript
+ ? t("transcriptionPreview.label")
+ : t("app.mic.clickToSpeak");
+ const getAudioLevel = useCallback(() => audioLevelRef.current, []);
+
+ const activatePill = () => {
+ if (!pillInteractive) return;
+ if (canReopenLiveTranscript) {
+ liveTranscript.reopen();
+ return;
+ }
+ void window.electronAPI.toggleAgentPanelDictation?.();
+ };
+
+ return (
+ <main className="agent-dictation-pill-window dictation-window">
+ <div
+ className={`voice-pill-position voice-pill-position-${voicePillDock} fixed z-50`}
+ style={
+ {
+ "--voice-pill-travel-duration": `${voicePillTravelDuration}ms`,
+ } as CSSProperties
+ }
+ onMouseEnter={() => {
+ if (companionState.interactive) setHovered(true);
+ }}
+ onMouseLeave={() => setHovered(false)}
+ >
+ <div className="relative flex items-center gap-2">
+ <VoicePill
+ variant={liveTranscript.open ? "panel" : "floating"}
+ state={state}
+ expanded={!liveTranscript.open && expanded}
+ collapseToLogo={listeningEntrance.collapseToLogo}
+ waveformVisible={listeningEntrance.waveformVisible}
+ waveformOnlyWhileRecording={liveTranscript.mounted}
+ integratedWithPanel={liveTranscript.open}
+ showExpandChevron={canReopenLiveTranscript && hovered}
+ getAudioLevel={getAudioLevel}
+ horizontalDirection={horizontalDirection}
+ role={pillInteractive ? "button" : "status"}
+ aria-label={label}
+ aria-disabled={!pillInteractive}
+ onClick={activatePill}
+ />
+ {cancelVisible && (
+ <button
+ type="button"
+ aria-label={
+ isRecording ? t("app.buttons.cancelRecording") : t("app.buttons.cancelProcessing")
+ }
+ onClick={(event) => {
+ event.preventDefault();
+ event.stopPropagation();
+ void window.electronAPI.cancelAgentPanelDictation?.();
+ }}
+ className="flex size-7 shrink-0 items-center justify-center rounded-full border border-border/55 bg-surface-2 text-muted-foreground shadow-sm transition-colors hover:bg-surface-3 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40"
+ >
+ <X size={13} strokeWidth={2.5} aria-hidden="true" />
+ </button>
+ )}
+ </div>
+ </div>
+
+ <VoiceModePanelCore
+ mode={liveTranscript.mounted ? "live-transcript" : null}
+ open={liveTranscript.open}
+ stage={liveTranscriptEntrance.coreStage as VoiceModePanelStage}
+ horizontalDirection={horizontalDirection}
+ label={t("transcriptionPreview.label")}
+ measurementRevision={liveTranscript.measurementText}
+ onPreferredHeightChange={liveTranscript.requestHeight}
+ >
+ {liveTranscript.mounted && (
+ <LiveTranscriptPanel
+ text={liveTranscript.text}
+ measurementText={liveTranscript.measurementText}
+ phase={liveTranscript.phase as LiveTranscriptPhase}
+ processing={isProcessing}
+ controlsVisible={liveTranscriptEntrance.controlsVisible}
+ contentVisible={liveTranscriptEntrance.contentVisible}
+ onCollapse={() => liveTranscript.close({ suppress: true })}
+ onHoldChange={liveTranscript.holdFinal}
+ />
+ )}
+ </VoiceModePanelCore>
+ </main>
+ );
+}
diff --git a/src/components/dictation/PillCommandMenu.tsx b/src/components/dictation/PillCommandMenu.tsx
index 91422c71e..a412227dd 100644
--- a/src/components/dictation/PillCommandMenu.tsx
+++ b/src/components/dictation/PillCommandMenu.tsx
@@ -68,7 +68,11 @@ export function PillCommandMenu({
>
{isRecording ? t("app.commandMenu.stopListening") : t("app.commandMenu.startListening")}
</button>
- {agentAllowed && (
+ {/* Opening the Agent panel mid-recording would strand the capture with no
+ surface (a translation recording becomes invisible AND un-stoppable:
+ its hotkey is blocked while the panel is open and Escape belongs to the
+ panel). Stop or finish the recording first. */}
+ {agentAllowed && !isRecording && (
<>
<div className="h-px bg-border" />
<button
diff --git a/src/helpers/dictationLifecycle.js b/src/helpers/dictationLifecycle.js
index d7fa5fdc1..290c7a16e 100644
--- a/src/helpers/dictationLifecycle.js
+++ b/src/helpers/dictationLifecycle.js
@@ -1,15 +1,40 @@
const DICTATION_LIFECYCLE = Object.freeze({
IDLE: "idle",
+ PREPARING: "preparing",
RECORDING: "recording",
PROCESSING: "processing",
});
+const DICTATION_INPUT_KIND = Object.freeze({
+ DICTATION: "dictation",
+ ASSISTANT: "assistant",
+ TRANSLATION: "translation",
+});
+
const VALID_STATES = new Set(Object.values(DICTATION_LIFECYCLE));
+const VALID_INPUT_KINDS = new Set(Object.values(DICTATION_INPUT_KIND));
function normalizeDictationLifecycle(state) {
return VALID_STATES.has(state) ? state : DICTATION_LIFECYCLE.IDLE;
}
+function normalizeDictationInputKind(inputKind) {
+ return VALID_INPUT_KINDS.has(inputKind) ? inputKind : DICTATION_INPUT_KIND.DICTATION;
+}
+
+function resolveAgentDictationPillState(state, inputKind) {
+ const lifecycle = normalizeDictationLifecycle(state);
+ const normalizedInputKind = normalizeDictationInputKind(inputKind);
+ const ownsLifecycle =
+ lifecycle === DICTATION_LIFECYCLE.IDLE ||
+ normalizedInputKind === DICTATION_INPUT_KIND.DICTATION;
+
+ return {
+ lifecycle: ownsLifecycle ? lifecycle : DICTATION_LIFECYCLE.IDLE,
+ interactive: ownsLifecycle,
+ };
+}
+
function shouldIgnoreDictationHotkey(state) {
return normalizeDictationLifecycle(state) === DICTATION_LIFECYCLE.PROCESSING;
}
@@ -18,22 +43,34 @@ function isDictationRecording(state) {
return normalizeDictationLifecycle(state) === DICTATION_LIFECYCLE.RECORDING;
}
-// While the assistant panel owns the shared pill window, plain dictation must
-// not start underneath it. An idle assistant may accept a voice follow-up,
-// but no recording may begin while the current request is still busy.
function shouldBlockDictationWhilePanelOpen({
assistantPanelOpen,
assistantPanelBusy = false,
- voiceAgentRequested = false,
+ inputKind = "dictation",
+ companionAvailable = true,
}) {
+ // Plain dictation renders on the opposite-edge companion pill, which only
+ // exists while the panel is open. A busy assistant that has not opened its
+ // panel yet (the pre-open thinking flourish) leaves no surface that could
+ // show the recording, so plain dictation stays blocked for that window.
+ // The open panel hands those visuals to the companion, so a companion that
+ // is not live yet (still loading, or its load failed) leaves the recording
+ // equally invisible — fail closed until it comes back.
+ if (inputKind === "dictation") {
+ if (assistantPanelBusy && !assistantPanelOpen) return true;
+ return assistantPanelOpen && !companionAvailable;
+ }
if (assistantPanelBusy) return true;
if (!assistantPanelOpen) return false;
- return !voiceAgentRequested;
+ return inputKind !== "assistant";
}
module.exports = {
DICTATION_LIFECYCLE,
+ DICTATION_INPUT_KIND,
normalizeDictationLifecycle,
+ normalizeDictationInputKind,
+ resolveAgentDictationPillState,
shouldIgnoreDictationHotkey,
isDictationRecording,
shouldBlockDictationWhilePanelOpen,
diff --git a/src/helpers/dictationRouting.js b/src/helpers/dictationRouting.js
index 150e2a652..ab1b951ad 100644
--- a/src/helpers/dictationRouting.js
+++ b/src/helpers/dictationRouting.js
@@ -160,6 +160,15 @@ export function resolveWakeWordLanguage({ preferredLanguage, uiLanguage }, detec
// selection disposition, not here. A translation recording degrades to
// cleanup instead: the transcript is still a useful dictation without the
// translation step.
+// The renderer-side source of truth for what the main process gates the Agent
+// companion pill on. Assistant wins over translation: a voice-agent request is
+// explicit user intent even if a stale translation flag survived.
+export function resolveLifecycleInputKind({ voiceAgentRequested, translationRequested }) {
+ if (voiceAgentRequested) return "assistant";
+ if (translationRequested) return "translation";
+ return "dictation";
+}
+
export function resolveDictationRouteKind({
cleanupReachable,
agentReachable,
diff --git a/src/helpers/ipcHandlers.js b/src/helpers/ipcHandlers.js
index 6c98268eb..2c7ce4a72 100644
--- a/src/helpers/ipcHandlers.js
+++ b/src/helpers/ipcHandlers.js
@@ -1541,7 +1541,7 @@ class IPCHandlers {
// in the dictation renderer. Only confirmed renderer state may change the
// main-process recording gate; raw key presses are merely requests and can
// be declined while a transcript is still being finalized.
- ipcMain.on("dictation-lifecycle-state-changed", (event, state) => {
+ ipcMain.on("dictation-lifecycle-state-changed", (event, state, inputKind) => {
const dictationWindow = this.windowManager.mainWindow;
if (
!dictationWindow ||
@@ -1550,7 +1550,32 @@ class IPCHandlers {
) {
return;
}
- this.windowManager.setDictationLifecycleState(state);
+ this.windowManager.setDictationLifecycleState(state, inputKind);
+ });
+
+ ipcMain.on("show-agent-dictation-final-transcript", (event, text) => {
+ const dictationWindow = this.windowManager.mainWindow;
+ if (
+ !dictationWindow ||
+ dictationWindow.isDestroyed() ||
+ event.sender !== dictationWindow.webContents
+ ) {
+ return;
+ }
+ if (typeof text !== "string" || !text.trim()) return;
+ this.windowManager.showAgentDictationFinalTranscript(text);
+ });
+
+ ipcMain.on("dictation-audio-level-changed", (event, level) => {
+ const dictationWindow = this.windowManager.mainWindow;
+ if (
+ !dictationWindow ||
+ dictationWindow.isDestroyed() ||
+ event.sender !== dictationWindow.webContents
+ ) {
+ return;
+ }
+ this.windowManager.setDictationAudioLevel(level);
});
// Dictionary handlers
@@ -5123,6 +5148,51 @@ class IPCHandlers {
return { success: true };
});
+ const isAgentDictationPill = (event) => {
+ const pillWindow = this.windowManager?.agentDictationPillWindow;
+ return pillWindow && !pillWindow.isDestroyed() && event.sender === pillWindow.webContents;
+ };
+
+ // The pill disables its own controls when an assistant or translation
+ // capture owns the lifecycle, but that state travels by IPC — a click can
+ // race it. Re-check here so a stale pill can never toggle or cancel a
+ // recording it does not own.
+ const isAgentDictationPillInteractive = () =>
+ this.windowManager.getAgentDictationPillState().interactive;
+
+ ipcMain.handle("toggle-agent-panel-dictation", (event) => {
+ if (!isAgentDictationPill(event) || !isAgentDictationPillInteractive()) {
+ return { success: false };
+ }
+ this.windowManager.sendToggleDictation();
+ return { success: true };
+ });
+
+ ipcMain.handle("cancel-agent-panel-dictation", (event) => {
+ if (!isAgentDictationPill(event) || !isAgentDictationPillInteractive()) {
+ return { success: false };
+ }
+ this.windowManager.sendCancelActiveDictation();
+ return { success: true };
+ });
+
+ ipcMain.handle("get-agent-dictation-pill-state", (event) => {
+ return isAgentDictationPill(event)
+ ? this.windowManager.getAgentDictationPillState()
+ : { lifecycle: "idle", interactive: false, horizontalDirection: "left" };
+ });
+
+ ipcMain.handle("resize-agent-dictation-pill-to-content", (event, surfaceHeight = null) => {
+ if (!isAgentDictationPill(event)) return { success: false };
+ return this.windowManager.resizeAgentDictationPillToContent(surfaceHeight);
+ });
+
+ ipcMain.handle("set-agent-dictation-pill-interactivity", (event, interactive) => {
+ if (!isAgentDictationPill(event)) return { success: false };
+ this.windowManager.setAgentDictationPillInteractivity(Boolean(interactive));
+ return { success: true };
+ });
+
ipcMain.handle("open-calendar-privacy-settings", () => openSystemSettings("calendars"));
ipcMain.handle("show-emoji-panel", () => {
diff --git a/src/helpers/voicePillPresentation.js b/src/helpers/voicePillPresentation.js
index fdef3b9de..72868aa4c 100644
--- a/src/helpers/voicePillPresentation.js
+++ b/src/helpers/voicePillPresentation.js
@@ -318,6 +318,36 @@ export function resolveVoicePillInteraction({
};
}
+// The companion pill defers to the main process's interactivity verdict and
+// keeps toggle clicks away from a transcript still processing — except to
+// reopen a manually collapsed transcript, which must stay reachable until the
+// final text lands (activatePill routes the reopen before any toggle).
+export function resolveCompanionPillInteractive({
+ mainProcessInteractive,
+ surfaceInteractive,
+ isProcessing,
+ canReopenLiveTranscript,
+}) {
+ if (!mainProcessInteractive || !surfaceInteractive) return false;
+ if (!isProcessing) return true;
+ return Boolean(canReopenLiveTranscript);
+}
+
+// Final Agent actions own the footer, so the pill node stays mounted but
+// hidden until the panel finishes closing. Live activity handed back at close
+// INTENT is the exception: the companion hides on that same tick, so keeping
+// the pill hidden until the fade completes would leave a running recording
+// with no visible owner at all.
+export function shouldSuppressPillForAssistantActions({
+ assistantOpen,
+ footerPillVisible,
+ assistantClosing,
+ hasLiveActivity,
+}) {
+ if (!assistantOpen || footerPillVisible) return false;
+ return !(assistantClosing && hasLiveActivity);
+}
+
export function shouldActivateVoicePill({
hasDragged,
liveTranscriptMounted,
diff --git a/src/helpers/windowManager.js b/src/helpers/windowManager.js
index 40417042f..df3b423c4 100644
--- a/src/helpers/windowManager.js
+++ b/src/helpers/windowManager.js
@@ -15,7 +15,10 @@ const { i18nMain } = require("./i18nMain");
const { NotificationDismissTimer, getNotificationTimeoutMs } = require("./notificationTimer");
const {
DICTATION_LIFECYCLE,
+ DICTATION_INPUT_KIND,
normalizeDictationLifecycle,
+ normalizeDictationInputKind,
+ resolveAgentDictationPillState,
shouldIgnoreDictationHotkey,
isDictationRecording,
shouldBlockDictationWhilePanelOpen,
@@ -37,6 +40,7 @@ const {
WINDOW_SIZES,
WindowPositionUtil,
} = require("./windowConfig");
+const AGENT_DICTATION_PILL_SIZE = Object.freeze({ ...WINDOW_SIZES.BASE });
const { centeredBounds, clampedBounds } = require("./onboardingWindowBounds");
const { ONBOARDING_DEMO_KINDS, isOnboardingInputAllowed } = require("./onboardingInputPolicy");
@@ -57,6 +61,11 @@ class WindowManager {
// teardown path (id-matched end, onboarding exit, control panel closed).
this.onOnboardingDemoTeardown = null;
this.notificationWindow = null;
+ this.agentDictationPillWindow = null;
+ this._agentDictationPillReady = false;
+ this._agentDictationPillSize = AGENT_DICTATION_PILL_SIZE;
+ this._agentDictationPillHorizontalDirection = "left";
+ this._agentDictationPillScreenListener = null;
this._notificationLoadTimeout = null;
this._notificationDismissTimer = new NotificationDismissTimer(() => {
if (this.meetingDetectionEngine) {
@@ -88,6 +97,7 @@ class WindowManager {
this._activeHorizontalDirection = null;
this._isDictatingToggle = false;
this._dictationLifecycleState = DICTATION_LIFECYCLE.IDLE;
+ this._dictationInputKind = DICTATION_INPUT_KIND.DICTATION;
this._assistantPanelOpen = false;
this._assistantPanelBusy = false;
this._pendingMeetingNoteNavigation = null;
@@ -191,6 +201,8 @@ class WindowManager {
}
this.enforceMainWindowOnTop();
}
+ if (this._assistantPanelOpen) this.showAgentDictationPill();
+ else this.hideAgentDictationPill();
this._updateMainContentProtection();
}
@@ -789,16 +801,47 @@ class WindowManager {
return this._isOnboardingInputAllowed("meeting");
}
+ // Visibility is part of "available": a ready pill that is merely hidden
+ // (onboarding took the screen, a panel close hid it) cannot show a
+ // recording, so counting it as a live surface would let dictation start
+ // with nothing on screen. A blocked press re-kicks the show below.
+ _isAgentDictationPillAvailable() {
+ const pillWindow = this.agentDictationPillWindow;
+ return Boolean(
+ pillWindow &&
+ !pillWindow.isDestroyed() &&
+ this._agentDictationPillReady &&
+ pillWindow.isVisible()
+ );
+ }
+
+ _shouldBlockDictationInput(inputKind) {
+ const blocked = shouldBlockDictationWhilePanelOpen({
+ assistantPanelOpen: this._assistantPanelOpen,
+ assistantPanelBusy: this._assistantPanelBusy,
+ inputKind,
+ companionAvailable: this._isAgentDictationPillAvailable(),
+ });
+ // A dictation press that lost to a missing companion re-kicks its load
+ // (a companion mid-load is left alone), so the surface can come back and
+ // the next press can land.
+ if (blocked && this._assistantPanelOpen && inputKind === DICTATION_INPUT_KIND.DICTATION) {
+ this.showAgentDictationPill();
+ }
+ // Fail-closed by design: while the companion is recreating after a crash
+ // (blocked && !companionAvailable above), a blocked "dictation" press
+ // could actually be a STOP of an already-running recording, not a start —
+ // this blanket block doesn't distinguish them. That costs the user one
+ // extra press with a hot mic (Escape/the cancel hotkey still work in the
+ // meantime). If that gap ever needs closing, a future reader should
+ // consider letting the press through when `this._isDictatingToggle` is
+ // already true, rather than loosening the block for starts too.
+ return blocked;
+ }
+
_sendDictationToggle(channel, inputKind) {
if (!this._isOnboardingInputAllowed(inputKind)) return;
- const voiceAgentRequested = channel === "toggle-voice-agent";
- if (
- shouldBlockDictationWhilePanelOpen({
- assistantPanelOpen: this._assistantPanelOpen,
- assistantPanelBusy: this._assistantPanelBusy,
- voiceAgentRequested,
- })
- ) {
+ if (this._shouldBlockDictationInput(inputKind)) {
return;
}
if (this.hotkeyManager.isInListeningMode()) {
@@ -835,19 +878,55 @@ class WindowManager {
// toggle's own kind so the pre-warm survives the assistant demo, whose
// gate rejects "dictation".
if (isStarting) {
- this.sendPrepareDictation({ inputKind, voiceAgentRequested });
+ this.sendPrepareDictation({ inputKind });
}
this.mainWindow.webContents.send(channel);
}
}
- setDictationLifecycleState(state) {
+ setDictationLifecycleState(state, inputKind = DICTATION_INPUT_KIND.DICTATION) {
const nextState = normalizeDictationLifecycle(state);
- if (nextState === this._dictationLifecycleState) return;
+ const nextInputKind = normalizeDictationInputKind(inputKind);
+ if (nextState === this._dictationLifecycleState && nextInputKind === this._dictationInputKind) {
+ return;
+ }
this._dictationLifecycleState = nextState;
+ this._dictationInputKind = nextInputKind;
this._isDictatingToggle = isDictationRecording(nextState);
this.meetingDetectionEngine?.setUserRecording(this._isDictatingToggle);
+ this._sendAgentDictationPillState();
+ }
+
+ _sendAgentDictationPillState() {
+ const pillWindow = this.agentDictationPillWindow;
+ if (!pillWindow || pillWindow.isDestroyed() || !this._agentDictationPillReady) return;
+ pillWindow.webContents.send(
+ "agent-dictation-pill-state-changed",
+ this.getAgentDictationPillState()
+ );
+ }
+
+ getAgentDictationPillState() {
+ return {
+ ...resolveAgentDictationPillState(this._dictationLifecycleState, this._dictationInputKind),
+ horizontalDirection: this._agentDictationPillHorizontalDirection,
+ };
+ }
+
+ setDictationAudioLevel(level) {
+ if (
+ !this._assistantPanelOpen ||
+ this._dictationLifecycleState !== DICTATION_LIFECYCLE.RECORDING ||
+ this._dictationInputKind !== DICTATION_INPUT_KIND.DICTATION
+ ) {
+ return;
+ }
+ const numericLevel = Number(level);
+ if (!Number.isFinite(numericLevel)) return;
+ const pillWindow = this.agentDictationPillWindow;
+ if (!pillWindow || pillWindow.isDestroyed() || !this._agentDictationPillReady) return;
+ pillWindow.webContents.send("agent-dictation-pill-audio-level-changed", numericLevel);
}
isDictationProcessing() {
@@ -868,12 +947,7 @@ class WindowManager {
sendStartDictation() {
if (!this._isOnboardingInputAllowed("dictation")) return;
- if (
- shouldBlockDictationWhilePanelOpen({
- assistantPanelOpen: this._assistantPanelOpen,
- assistantPanelBusy: this._assistantPanelBusy,
- })
- ) {
+ if (this._shouldBlockDictationInput("dictation")) {
return;
}
if (this.hotkeyManager.isInListeningMode()) {
@@ -891,9 +965,6 @@ class WindowManager {
}
sendStopDictation() {
- if (shouldBlockDictationWhilePanelOpen({ assistantPanelOpen: this._assistantPanelOpen })) {
- return;
- }
if (this.hotkeyManager.isInListeningMode()) {
return;
}
@@ -902,15 +973,9 @@ class WindowManager {
}
}
- sendPrepareDictation({ inputKind = "dictation", voiceAgentRequested = false } = {}) {
+ sendPrepareDictation({ inputKind = "dictation" } = {}) {
if (!this._isOnboardingInputAllowed(inputKind)) return;
- if (
- shouldBlockDictationWhilePanelOpen({
- assistantPanelOpen: this._assistantPanelOpen,
- assistantPanelBusy: this._assistantPanelBusy,
- voiceAgentRequested,
- })
- ) {
+ if (this._shouldBlockDictationInput(inputKind)) {
return;
}
if (this.hotkeyManager.isInListeningMode()) {
@@ -920,7 +985,7 @@ class WindowManager {
return;
}
if (this.mainWindow && !this.mainWindow.isDestroyed()) {
- this.mainWindow.webContents.send("prepare-dictation");
+ this.mainWindow.webContents.send("prepare-dictation", { inputKind });
}
}
@@ -940,6 +1005,17 @@ class WindowManager {
}
}
+ // Unlike sendCancelDictation (a silent input reset: preparation and
+ // recording only), this also cancels a transcript still processing. The
+ // companion pill's cancel control lives in another window, but only the
+ // main window's renderer owns the recording state, so it decides what
+ // "cancel" means at arrival time.
+ sendCancelActiveDictation() {
+ if (this.mainWindow && !this.mainWindow.isDestroyed()) {
+ this.mainWindow.webContents.send("cancel-dictation");
+ }
+ }
+
getActivationMode() {
return this._cachedActivationMode;
}
@@ -1223,10 +1299,20 @@ class WindowManager {
await this.loadWindowContent(this.controlPanelWindow, true);
}
+ _sendAgentDictationPreview(channel, payload) {
+ if (!this._assistantPanelOpen || this._dictationInputKind !== DICTATION_INPUT_KIND.DICTATION) {
+ return;
+ }
+ const pillWindow = this.agentDictationPillWindow;
+ if (!pillWindow || pillWindow.isDestroyed() || !this._agentDictationPillReady) return;
+ pillWindow.webContents.send(channel, payload);
+ }
+
async showTranscriptionPreview(text) {
if (this._onboardingActive) return;
if (!this.mainWindow || this.mainWindow.isDestroyed()) return;
this.mainWindow.webContents.send("preview-text", text);
+ this._sendAgentDictationPreview("preview-text", text);
this.mainWindow.showInactive();
this.enforceMainWindowOnTop();
}
@@ -1235,26 +1321,42 @@ class WindowManager {
if (this._onboardingActive) return;
if (!this.mainWindow || this.mainWindow.isDestroyed()) return;
this.mainWindow.webContents.send("preview-append", text);
+ this._sendAgentDictationPreview("preview-append", text);
}
holdTranscriptionPreview(options = {}) {
if (this._onboardingActive) return;
if (!this.mainWindow || this.mainWindow.isDestroyed()) return;
- this.mainWindow.webContents.send("preview-hold", {
+ const payload = {
showCleanup: !!options.showCleanup,
- });
+ };
+ this.mainWindow.webContents.send("preview-hold", payload);
+ this._sendAgentDictationPreview("preview-hold", payload);
}
completeTranscriptionPreview(text) {
if (this._onboardingActive) return;
if (!this.mainWindow || this.mainWindow.isDestroyed()) return;
- this.mainWindow.webContents.send("preview-result", { text });
+ const payload = { text };
+ this.mainWindow.webContents.send("preview-result", payload);
+ this._sendAgentDictationPreview("preview-result", payload);
this.enforceMainWindowOnTop();
}
+ // A recoverable dictation error's "View Transcript" action has no surface in
+ // the main window while the Agent panel owns it (openPanel refuses under
+ // assistantOpenRef), so the recovered text shows on the companion instead.
+ showAgentDictationFinalTranscript(text) {
+ this._sendAgentDictationPreview("agent-dictation-pill-final-transcript", text);
+ }
+
hideTranscriptionPreview() {
if (!this.mainWindow || this.mainWindow.isDestroyed()) return;
this.mainWindow.webContents.send("preview-hide");
+ const pillWindow = this.agentDictationPillWindow;
+ if (pillWindow && !pillWindow.isDestroyed() && this._agentDictationPillReady) {
+ pillWindow.webContents.send("preview-hide");
+ }
}
// The display the user is working on is the one showing the app being dictated
@@ -1394,6 +1496,7 @@ class WindowManager {
_hideNormalAppSurfaces() {
this.hideDictationPanel();
this.hideTranscriptionPreview();
+ this.hideAgentDictationPill();
this.dismissMeetingNotification();
if (this._pendingUpdateNotificationData) {
@@ -1585,6 +1688,173 @@ class WindowManager {
if (this.mainWindow && !this.mainWindow.isDestroyed()) this.mainWindow.hide();
}
+ positionAgentDictationPill() {
+ const pillWindow = this.agentDictationPillWindow;
+ if (
+ !pillWindow ||
+ pillWindow.isDestroyed() ||
+ !this.mainWindow ||
+ this.mainWindow.isDestroyed()
+ ) {
+ return;
+ }
+
+ const mainBounds = this.mainWindow.getBounds();
+ const display = screen.getDisplayMatching(mainBounds);
+ const mainSide = resolveHorizontalWindowDirection(
+ mainBounds,
+ display,
+ this._panelStartPosition
+ );
+ const oppositeEdge = mainSide === "right" ? "bottom-left" : "bottom-right";
+ const horizontalDirection = oppositeEdge === "bottom-left" ? "left" : "right";
+ const directionChanged = horizontalDirection !== this._agentDictationPillHorizontalDirection;
+ this._agentDictationPillHorizontalDirection = horizontalDirection;
+ pillWindow.setBounds(
+ WindowPositionUtil.getMainWindowPosition(display, this._agentDictationPillSize, oppositeEdge)
+ );
+ if (directionChanged) this._sendAgentDictationPillState();
+ }
+
+ resizeAgentDictationPillToContent(surfaceHeight = null) {
+ const pillWindow = this.agentDictationPillWindow;
+ if (
+ !pillWindow ||
+ pillWindow.isDestroyed() ||
+ !this.mainWindow ||
+ this.mainWindow.isDestroyed()
+ ) {
+ return { success: false, message: "Window not available" };
+ }
+
+ const mainBounds = this.mainWindow.getBounds();
+ const display = screen.getDisplayMatching(mainBounds);
+ const nextSize =
+ surfaceHeight === null
+ ? AGENT_DICTATION_PILL_SIZE
+ : fitAssistantContentWindowToWorkArea(surfaceHeight, display.workArea || display.bounds);
+ const currentBounds = pillWindow.getBounds();
+ const changed =
+ currentBounds.width !== nextSize.width || currentBounds.height !== nextSize.height;
+ this._agentDictationPillSize = nextSize;
+ this.positionAgentDictationPill();
+ return { success: true, bounds: pillWindow.getBounds(), changed };
+ }
+
+ showAgentDictationPill() {
+ if (this._onboardingActive) return;
+ if (!this._assistantPanelOpen || !this.mainWindow || this.mainWindow.isDestroyed()) return;
+
+ let pillWindow = this.agentDictationPillWindow;
+ if (!pillWindow || pillWindow.isDestroyed()) {
+ pillWindow = new BrowserWindow({
+ ...NOTIFICATION_WINDOW_CONFIG,
+ ...AGENT_DICTATION_PILL_SIZE,
+ });
+ this.agentDictationPillWindow = pillWindow;
+ this._agentDictationPillReady = false;
+ this._agentDictationPillSize = AGENT_DICTATION_PILL_SIZE;
+ // Registered lazily with the first companion window (screen.on in the
+ // constructor would fire before `screen` is usable in some test/boot orders)
+ // and kept for the app's lifetime; positionAgentDictationPill no-ops safely
+ // when no pill exists.
+ if (!this._agentDictationPillScreenListener) {
+ this._agentDictationPillScreenListener = () => this.positionAgentDictationPill();
+ screen.on("display-metrics-changed", this._agentDictationPillScreenListener);
+ screen.on("display-added", this._agentDictationPillScreenListener);
+ screen.on("display-removed", this._agentDictationPillScreenListener);
+ }
+ // The companion exists only while the content-protected Agent panel is
+ // open; keep it out of screen shares along with the panel it accompanies.
+ pillWindow.setContentProtection(true);
+ this._applyAgentDictationPillClickThrough(pillWindow, true);
+
+ pillWindow.on("closed", () => {
+ if (this.agentDictationPillWindow !== pillWindow) return;
+ this.agentDictationPillWindow = null;
+ this._agentDictationPillReady = false;
+ this._agentDictationPillSize = AGENT_DICTATION_PILL_SIZE;
+ });
+ pillWindow.webContents.on("did-finish-load", () => {
+ if (this.agentDictationPillWindow !== pillWindow) return;
+ this._agentDictationPillReady = true;
+ this._sendAgentDictationPillState();
+ this.showAgentDictationPill();
+ });
+ pillWindow.webContents.on("render-process-gone", (_event, details) => {
+ if (this.agentDictationPillWindow !== pillWindow) return;
+ // "clean-exit" is benign teardown already handled by the `closed`
+ // listener below; tear down on every other reason (a blocklist, not
+ // an allowlist) so an abnormal reason we don't yet have a name for
+ // still fails closed instead of leaving a dead renderer marked ready.
+ if (details?.reason === "clean-exit") return;
+ debugLogger.warn(
+ "Agent dictation pill renderer gone; closing so the next press recreates it",
+ { reason: details?.reason, exitCode: details?.exitCode },
+ "window"
+ );
+ // Readiness must drop immediately: with a dead renderer the fail-closed
+ // dictation gate would otherwise approve recordings nobody can see.
+ this._agentDictationPillReady = false;
+ if (!pillWindow.isDestroyed()) pillWindow.close();
+ });
+
+ const loadPromise =
+ process.env.NODE_ENV === "development"
+ ? DevServerManager.waitForDevServer().then(() =>
+ pillWindow.loadURL(`${DevServerManager.DEV_SERVER_URL}?agent-dictation-pill=true`)
+ )
+ : (() => {
+ const fileInfo = DevServerManager.getAppFilePath(false);
+ if (!fileInfo) return Promise.reject(new Error("Failed to get app file path"));
+ return pillWindow.loadFile(fileInfo.path, {
+ query: { ...fileInfo.query, "agent-dictation-pill": "true" },
+ });
+ })();
+ void loadPromise.catch((error) => {
+ debugLogger.warn("Failed to load Agent dictation pill", { error: error.message }, "window");
+ if (!pillWindow.isDestroyed()) pillWindow.close();
+ });
+ return;
+ }
+
+ if (!this._agentDictationPillReady) return;
+ this.positionAgentDictationPill();
+ WindowPositionUtil.setupAlwaysOnTop(pillWindow);
+ if (!pillWindow.isVisible()) pillWindow.showInactive();
+ pillWindow.moveTop?.();
+ }
+
+ hideAgentDictationPill() {
+ const pillWindow = this.agentDictationPillWindow;
+ if (!pillWindow || pillWindow.isDestroyed()) return;
+ if (pillWindow.isVisible()) pillWindow.hide();
+ if (this._agentDictationPillReady) pillWindow.webContents.send("preview-hide");
+ // A hover-captured window never sees its mouseleave once hidden; reset so
+ // the next show cannot start out swallowing clicks under stale capture.
+ this._applyAgentDictationPillClickThrough(pillWindow, true);
+ this._agentDictationPillSize = AGENT_DICTATION_PILL_SIZE;
+ this.positionAgentDictationPill();
+ }
+
+ setAgentDictationPillInteractivity(interactive) {
+ const pillWindow = this.agentDictationPillWindow;
+ if (!pillWindow || pillWindow.isDestroyed()) return;
+ this._applyAgentDictationPillClickThrough(pillWindow, !interactive);
+ }
+
+ // Like the dictation pill and meeting notification, the companion is
+ // click-through on macOS so its transparent bounds never swallow clicks
+ // meant for the app beneath; hovering re-captures via IPC. Windows
+ // forwarding is unreliable for floating panels and Linux ignores `forward`
+ // (one hover-out would strand the pill unreachable, #1456), so both keep
+ // normal hit-testing.
+ _applyAgentDictationPillClickThrough(pillWindow, clickThrough) {
+ if (process.platform !== "darwin") return;
+ if (clickThrough) pillWindow.setIgnoreMouseEvents(true, { forward: true });
+ else pillWindow.setIgnoreMouseEvents(false);
+ }
+
isDictationPanelVisible() {
if (!this.mainWindow || this.mainWindow.isDestroyed()) {
return false;
@@ -1624,14 +1894,20 @@ class WindowManager {
this.mainWindow.on("show", () => {
this.enforceMainWindowOnTop();
+ if (this._assistantPanelOpen) this.showAgentDictationPill();
});
this.mainWindow.on("focus", () => {
this.enforceMainWindowOnTop();
+ if (this._assistantPanelOpen) this.showAgentDictationPill();
});
+ this.mainWindow.on("move", () => this.positionAgentDictationPill());
+
this.mainWindow.on("closed", () => {
this.dragManager.cleanup();
+ const pillWindow = this.agentDictationPillWindow;
+ if (pillWindow && !pillWindow.isDestroyed()) pillWindow.close();
this.mainWindow = null;
});
}
diff --git a/src/hooks/useAudioRecording.js b/src/hooks/useAudioRecording.js
index af5c651b0..2fa24c5aa 100644
--- a/src/hooks/useAudioRecording.js
+++ b/src/hooks/useAudioRecording.js
@@ -21,6 +21,7 @@ import {
} from "../utils/transcriptionPreview";
import { canStartDictation } from "../utils/dictationReadiness";
import { waitForVisualFrames } from "../utils/visualFrame";
+import { resolveLifecycleInputKind } from "../helpers/dictationRouting";
import { createAssistantResponseDelivery } from "../helpers/assistantResponseDelivery";
// Maps a failed selection-replacement code to its `selectionEditing.*` toast
@@ -31,6 +32,7 @@ const SELECTION_EDIT_DETAIL_KEY_BY_CODE = {
session_expired: "expired",
paste_failed: "pasteFailed",
};
+const COMPANION_AUDIO_LEVEL_INTERVAL_MS = 80;
export const useAudioRecording = (toast, options = {}) => {
const { t } = useTranslation();
@@ -65,6 +67,7 @@ export const useAudioRecording = (toast, options = {}) => {
getAssistantSelectionContext,
onShowTranscript,
onDemoEvent,
+ assistantOpenRef,
} = options;
useEffect(() => {
@@ -86,6 +89,23 @@ export const useAudioRecording = (toast, options = {}) => {
getAssistantSelectionContextRef.current = getAssistantSelectionContext;
});
+ // Reads only refs and the global electronAPI bridge, so a single stable
+ // instance is safe to share between the mount effect (recording/processing
+ // transitions) and performStartRecording (the toggle path's own "preparing"
+ // report).
+ const reportLifecycle = useCallback((state, inputKindOverride) => {
+ const inputKind =
+ inputKindOverride ??
+ resolveLifecycleInputKind({
+ voiceAgentRequested: audioManagerRef.current?.voiceAgentRequested,
+ translationRequested: audioManagerRef.current?.translationRequested,
+ });
+ const signature = `${state}:${inputKind}`;
+ if (reportedLifecycleRef.current === signature) return;
+ reportedLifecycleRef.current = signature;
+ window.electronAPI?.dictationLifecycleStateChanged?.(state, inputKind);
+ }, []);
+
const performStartRecording = useCallback(
async ({ voiceAgentRequested = false, translationRequested = false } = {}) => {
if (startLockRef.current) return false;
@@ -138,6 +158,10 @@ export const useAudioRecording = (toast, options = {}) => {
audioManagerRef.current.setVoiceAgentRequested(voiceAgentRequested);
audioManagerRef.current.setAssistantSelectionContext(assistantSelectionContext);
audioManagerRef.current.setTranslationRequested(translationRequested);
+ // Covers the toggle path with freshly-set flags; the signature dedup
+ // makes this a no-op when the prepare handler already reported the
+ // same kind ahead of the flags being set.
+ reportLifecycle("preparing");
if (voiceAgentRequested) {
logger.info(
"Voice agent recording start",
@@ -224,10 +248,19 @@ export const useAudioRecording = (toast, options = {}) => {
if (!recordingStarted) {
setIsPreparing(false);
setIsAssistantVoice(false);
+ // Covers every exit above that never started a recording — the
+ // policy-block early return, the mic-open failure, a stale
+ // preparation generation, etc. Without this, a failed start leaves
+ // the main process (and the companion pill) stuck reporting
+ // "preparing" forever, since startRecording's failure path only
+ // fires onError, never the onStateChange that normally reports
+ // "idle". The signature dedup makes this a no-op when
+ // onStateChange already reported it first.
+ if (reportedLifecycleRef.current?.startsWith("preparing:")) reportLifecycle("idle");
}
}
},
- [t, toast, dismissDictationError]
+ [t, toast, dismissDictationError, reportLifecycle]
);
const performStopRecording = useCallback(async () => {
@@ -273,11 +306,6 @@ export const useAudioRecording = (toast, options = {}) => {
useEffect(() => {
audioManagerRef.current = new AudioManager();
- const reportLifecycle = (state) => {
- if (reportedLifecycleRef.current === state) return;
- reportedLifecycleRef.current = state;
- window.electronAPI?.dictationLifecycleStateChanged?.(state);
- };
// Reset stale main-process state after a renderer reload or crash recovery.
reportLifecycle("idle");
@@ -667,12 +695,16 @@ export const useAudioRecording = (toast, options = {}) => {
onToggle?.();
});
- const disposePrepare = window.electronAPI.onPrepareDictation?.(async () => {
+ const disposePrepare = window.electronAPI.onPrepareDictation?.(async (options) => {
if (!audioManagerRef.current || startLockRef.current) return;
if (!canStartDictation(audioManagerRef.current.getState())) return;
const generation = ++preparationGenerationRef.current;
setIsAssistantVoice(false);
setIsPreparing(true);
+ // The prepare event precedes the flag-setting start, so the kind must come
+ // from the payload — the audioManager flags still describe the PREVIOUS
+ // recording at this point.
+ reportLifecycle("preparing", options?.inputKind);
await waitForVisualFrames();
if (generation !== preparationGenerationRef.current || startLockRef.current) return;
void audioManagerRef.current.prepareMicCapture?.();
@@ -682,6 +714,7 @@ export const useAudioRecording = (toast, options = {}) => {
preparationGenerationRef.current += 1;
setIsPreparing(false);
audioManagerRef.current?.cancelPreparedMicCapture?.();
+ if (reportedLifecycleRef.current?.startsWith("preparing:")) reportLifecycle("idle");
});
const disposeStop = window.electronAPI.onStopDictation?.(() => {
@@ -711,6 +744,7 @@ export const useAudioRecording = (toast, options = {}) => {
performStopRecording,
dismissDictationError,
onDictationError,
+ reportLifecycle,
t,
]);
@@ -735,18 +769,35 @@ export const useAudioRecording = (toast, options = {}) => {
return false;
}, []);
- const cancelProcessing = () => {
+ const cancelProcessing = useCallback(() => {
if (audioManagerRef.current) {
return audioManagerRef.current.cancelProcessing();
}
return false;
- };
+ }, []);
const getAudioLevel = useCallback(
() => audioManagerRef.current?.getRecordingAudioLevel() ?? null,
[]
);
+ useEffect(() => {
+ if (!isRecording || isAssistantVoice) return undefined;
+
+ const reportAudioLevel = () => {
+ // The companion pill only exists while the Agent panel is open — with
+ // the panel closed there is nobody to mirror levels to, so skip the
+ // IPC. Checked per tick, not once: the panel can open mid-recording and
+ // a ref change never re-runs this effect.
+ if (!assistantOpenRef?.current) return;
+ const level = getAudioLevel();
+ if (level !== null) window.electronAPI?.dictationAudioLevelChanged?.(level);
+ };
+ reportAudioLevel();
+ const interval = setInterval(reportAudioLevel, COMPANION_AUDIO_LEVEL_INTERVAL_MS);
+ return () => clearInterval(interval);
+ }, [assistantOpenRef, getAudioLevel, isAssistantVoice, isRecording]);
+
const toggleListening = async ({
voiceAgentRequested = false,
translationRequested = false,
diff --git a/src/hooks/useListeningEntrancePhase.ts b/src/hooks/useListeningEntrancePhase.ts
new file mode 100644
index 000000000..e077dd302
--- /dev/null
+++ b/src/hooks/useListeningEntrancePhase.ts
@@ -0,0 +1,33 @@
+import { useLayoutEffect, useState } from "react";
+import { getListeningEntranceTimeline } from "../helpers/voicePillPresentation";
+
+export type ListeningEntrancePhase = "idle" | "thinking" | "expanding" | "settled" | "waveform";
+
+/**
+ * Drives the recording pill's entrance choreography (thinking → expanding →
+ * settled → waveform). The main pill and the Agent companion pill share this
+ * single timeline so their entrances can never drift apart.
+ */
+export function useListeningEntrancePhase(isRecording: boolean): ListeningEntrancePhase {
+ const [phase, setPhase] = useState<ListeningEntrancePhase>("idle");
+
+ useLayoutEffect(() => {
+ if (!isRecording) {
+ setPhase("idle");
+ return undefined;
+ }
+
+ setPhase("thinking");
+ const timeline = getListeningEntranceTimeline();
+ const expansionTimer = setTimeout(() => setPhase("expanding"), timeline.expandAtMs);
+ const settledTimer = setTimeout(() => setPhase("settled"), timeline.settleAtMs);
+ const waveformTimer = setTimeout(() => setPhase("waveform"), timeline.waveformAtMs);
+ return () => {
+ clearTimeout(expansionTimer);
+ clearTimeout(settledTimer);
+ clearTimeout(waveformTimer);
+ };
+ }, [isRecording]);
+
+ return phase;
+}
diff --git a/src/styles/agent-dictation-pill.css b/src/styles/agent-dictation-pill.css
new file mode 100644
index 000000000..ef420b6db
--- /dev/null
+++ b/src/styles/agent-dictation-pill.css
@@ -0,0 +1,8 @@
+html:has(.agent-dictation-pill-window),
+body:has(.agent-dictation-pill-window),
+body:has(.agent-dictation-pill-window) #root {
+ height: 100%;
+ min-height: 100%;
+ overflow: hidden;
+ background: transparent;
+}
diff --git a/src/types/electron.ts b/src/types/electron.ts
index d0c681ee5..7b2f7875b 100644
--- a/src/types/electron.ts
+++ b/src/types/electron.ts
@@ -981,10 +981,41 @@ declare global {
onToggleTranslation?: (callback: () => void) => () => void;
onStartDictation?: (callback: () => void) => () => void;
onStopDictation?: (callback: () => void) => () => void;
- onPrepareDictation?: (callback: () => void) => () => void;
+ onPrepareDictation?: (
+ callback: (options?: { inputKind?: "dictation" | "assistant" | "translation" }) => void
+ ) => () => void;
onCancelDictationPreparation?: (callback: () => void) => () => void;
+ onCancelDictation?: (callback: () => void) => () => void;
micWarmHoldChanged?: (active: boolean) => void;
- dictationLifecycleStateChanged: (state: "idle" | "recording" | "processing") => void;
+ dictationLifecycleStateChanged: (
+ state: "idle" | "preparing" | "recording" | "processing",
+ inputKind?: "dictation" | "assistant" | "translation"
+ ) => void;
+ dictationAudioLevelChanged?: (level: number) => void;
+ toggleAgentPanelDictation?: () => Promise<{ success: boolean }>;
+ cancelAgentPanelDictation?: () => Promise<{ success: boolean }>;
+ getAgentDictationPillState?: () => Promise<{
+ lifecycle: "idle" | "preparing" | "recording" | "processing";
+ interactive: boolean;
+ horizontalDirection: "left" | "right";
+ }>;
+ resizeAgentDictationPillToContent?: (surfaceHeight: number | null) => Promise<{
+ success: boolean;
+ changed?: boolean;
+ bounds?: { x: number; y: number; width: number; height: number };
+ message?: string;
+ }>;
+ setAgentDictationPillInteractivity?: (interactive: boolean) => Promise<{ success: boolean }>;
+ onAgentDictationPillStateChanged?: (
+ callback: (state: {
+ lifecycle: "idle" | "preparing" | "recording" | "processing";
+ interactive: boolean;
+ horizontalDirection: "left" | "right";
+ }) => void
+ ) => () => void;
+ onAgentDictationPillAudioLevelChanged?: (callback: (level: number) => void) => () => void;
+ showAgentDictationFinalTranscript?: (text: string) => void;
+ onAgentDictationPillFinalTranscript?: (callback: (text: string) => void) => () => void;
// STT config
getSttConfig?: () => Promise<
diff --git a/test/components/pillCommandMenu.test.js b/test/components/pillCommandMenu.test.js
new file mode 100644
index 000000000..de2c6bac2
--- /dev/null
+++ b/test/components/pillCommandMenu.test.js
@@ -0,0 +1,37 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const { createElement } = require("react");
+const { renderToStaticMarkup } = require("react-dom/server");
+const { createRendererServer, installBrowserGlobals } = require("../lib/rendererTestHarness");
+
+// The harness renders i18n keys verbatim (no i18next instance is initialized),
+// so assertions match on the raw translation key rather than resolved copy.
+async function renderMenu(t, props) {
+ installBrowserGlobals(t);
+ const vite = await createRendererServer(t, {
+ cachePrefix: "openwhispr-pill-command-menu-test-",
+ });
+ const mod = await vite.ssrLoadModule("/components/dictation/PillCommandMenu.tsx");
+ return renderToStaticMarkup(
+ createElement(mod.PillCommandMenu, {
+ buttonRef: { current: null },
+ isRecording: false,
+ agentAllowed: true,
+ isHovered: false,
+ setWindowInteractivity: () => {},
+ onToggleListening: () => {},
+ onAskAssistant: () => {},
+ onHide: () => {},
+ onClose: () => {},
+ ...props,
+ })
+ );
+}
+
+test("the command menu hides Ask Assistant while a recording is active", async (t) => {
+ const idleMarkup = await renderMenu(t, { isRecording: false });
+ assert.match(idleMarkup, /askAssistant/);
+
+ const recordingMarkup = await renderMenu(t, { isRecording: true });
+ assert.doesNotMatch(recordingMarkup, /askAssistant/);
+});
diff --git a/test/helpers/agentDictationPillIpc.test.js b/test/helpers/agentDictationPillIpc.test.js
new file mode 100644
index 000000000..3e345cbae
--- /dev/null
+++ b/test/helpers/agentDictationPillIpc.test.js
@@ -0,0 +1,274 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const Module = require("node:module");
+
+const handlersModulePath = require.resolve("../../src/helpers/ipcHandlers");
+const originalLoad = Module._load;
+
+// Captures every ipcMain.handle/on registration so the registered handler
+// closures can be invoked directly against a fake `this`, mirroring the
+// scaffolding in test/helpers/retryTranscriptionHandler.test.js.
+const handlers = new Map();
+const onHandlers = new Map();
+
+const electronStub = {
+ app: {
+ getPath: () => "/tmp",
+ getName: () => "test",
+ getVersion: () => "0.0.0",
+ isPackaged: false,
+ on: () => {},
+ requestSingleInstanceLock: () => true,
+ },
+ ipcMain: {
+ handle: (channel, fn) => handlers.set(channel, fn),
+ on: (channel, fn) => onHandlers.set(channel, fn),
+ removeHandler: () => {},
+ },
+ net: {
+ fetch: async () => ({
+ ok: true,
+ status: 200,
+ json: async () => ({}),
+ text: async () => "{}",
+ }),
+ },
+ BrowserWindow: class BrowserWindow {
+ static getAllWindows() {
+ return [];
+ }
+ static fromWebContents() {
+ return null;
+ }
+ },
+ shell: {},
+ dialog: {},
+ screen: { getPrimaryDisplay: () => ({ workAreaSize: { width: 0, height: 0 } }) },
+ systemPreferences: { getMediaAccessStatus: () => "granted" },
+ session: { fromPartition: () => ({}) },
+ clipboard: {},
+ nativeImage: {},
+ globalShortcut: {},
+ utilityProcess: {},
+ MessageChannelMain: class {},
+};
+
+// Kept installed for the whole file: some helpers are require()d lazily at
+// handler invocation time, not at module load.
+Module._load = function loadWithMocks(request, parent, isMain) {
+ if (request === "electron") return electronStub;
+ if (parent?.filename === handlersModulePath) {
+ if (request === "./cortiTranscription") {
+ return { transcribeAudio: async () => ({ text: "corti text" }) };
+ }
+ if (request === "./tinfoilTranscription") {
+ return {
+ transcribeWithTinfoil: async () => ({ text: "tinfoil text", model: "tinfoil-model" }),
+ getTinfoilChatModels: () => [],
+ };
+ }
+ if (request === "./windowBroadcast") {
+ return { broadcastToWindows: () => {} };
+ }
+ }
+ return originalLoad.call(this, request, parent, isMain);
+};
+
+// A permissive `this` for setupHandlers: registration only stores closures, so
+// any manager not exercised by the pill handlers can be an inert stub.
+function anything() {
+ return new Proxy(function () {}, {
+ get: (t, prop) => {
+ if (prop === Symbol.toPrimitive || prop === "toString") return () => "";
+ if (prop === "then") return undefined;
+ return anything();
+ },
+ apply: () => anything(),
+ });
+}
+
+// `target` stays a plain object (not the Proxy) so tests can reassign
+// `target.windowManager` between cases and have the already-registered
+// handler closures observe the swap on their next invocation — they read
+// `this.windowManager` fresh each call, they don't capture it at registration.
+let target;
+function buildFakeThis() {
+ target = {
+ sessionId: "test-session",
+ };
+ return new Proxy(target, {
+ get: (t, prop) => (prop in t ? t[prop] : anything()),
+ });
+}
+
+function installWindowManager(stub) {
+ target.windowManager = stub;
+}
+
+function makeWindowManagerStub() {
+ const calls = { toggle: 0, cancel: 0, lifecycle: [], levels: [] };
+ const mainContents = {};
+ const pillContents = {};
+ const stub = {
+ mainWindow: { isDestroyed: () => false, webContents: mainContents },
+ agentDictationPillWindow: { isDestroyed: () => false, webContents: pillContents },
+ getAgentDictationPillState: () => ({
+ lifecycle: "idle",
+ interactive: true,
+ horizontalDirection: "left",
+ }),
+ sendToggleDictation: () => {
+ calls.toggle += 1;
+ },
+ sendCancelActiveDictation: () => {
+ calls.cancel += 1;
+ },
+ setDictationLifecycleState: (state, kind) => {
+ calls.lifecycle.push([state, kind]);
+ },
+ setDictationAudioLevel: (level) => {
+ calls.levels.push(level);
+ },
+ resizeAgentDictationPillToContent: () => ({ success: true }),
+ setAgentDictationPillInteractivity: () => undefined,
+ };
+ return { stub, calls, mainContents, pillContents };
+}
+
+test.before(() => {
+ delete require.cache[handlersModulePath];
+ const IPCHandlers = require(handlersModulePath);
+ const Ctor = IPCHandlers.default || IPCHandlers;
+ Ctor.prototype.setupHandlers.call(buildFakeThis());
+ assert.ok(
+ handlers.get("toggle-agent-panel-dictation"),
+ "toggle-agent-panel-dictation must be registered"
+ );
+ assert.ok(
+ handlers.get("cancel-agent-panel-dictation"),
+ "cancel-agent-panel-dictation must be registered"
+ );
+ assert.ok(
+ handlers.get("get-agent-dictation-pill-state"),
+ "get-agent-dictation-pill-state must be registered"
+ );
+ assert.ok(
+ handlers.get("resize-agent-dictation-pill-to-content"),
+ "resize-agent-dictation-pill-to-content must be registered"
+ );
+ assert.ok(
+ handlers.get("set-agent-dictation-pill-interactivity"),
+ "set-agent-dictation-pill-interactivity must be registered"
+ );
+ assert.ok(
+ onHandlers.get("dictation-lifecycle-state-changed"),
+ "dictation-lifecycle-state-changed must be registered"
+ );
+ assert.ok(
+ onHandlers.get("dictation-audio-level-changed"),
+ "dictation-audio-level-changed must be registered"
+ );
+});
+
+test.after(() => {
+ Module._load = originalLoad;
+});
+
+test("pill-scoped handlers reject foreign senders", async () => {
+ const { stub, calls } = makeWindowManagerStub();
+ installWindowManager(stub);
+ const stranger = { sender: {} };
+
+ assert.deepEqual(await handlers.get("toggle-agent-panel-dictation")(stranger), {
+ success: false,
+ });
+ assert.deepEqual(await handlers.get("cancel-agent-panel-dictation")(stranger), {
+ success: false,
+ });
+ assert.deepEqual(await handlers.get("get-agent-dictation-pill-state")(stranger), {
+ lifecycle: "idle",
+ interactive: false,
+ horizontalDirection: "left",
+ });
+ assert.deepEqual(await handlers.get("resize-agent-dictation-pill-to-content")(stranger, 240), {
+ success: false,
+ });
+ assert.deepEqual(await handlers.get("set-agent-dictation-pill-interactivity")(stranger, true), {
+ success: false,
+ });
+ assert.equal(calls.toggle, 0);
+ assert.equal(calls.cancel, 0);
+});
+
+test("a stale pill click cannot toggle or cancel a capture it does not own", async () => {
+ const { stub, calls, pillContents } = makeWindowManagerStub();
+ stub.getAgentDictationPillState = () => ({
+ lifecycle: "idle",
+ interactive: false,
+ horizontalDirection: "left",
+ });
+ installWindowManager(stub);
+ const pillEvent = { sender: pillContents };
+
+ assert.deepEqual(await handlers.get("toggle-agent-panel-dictation")(pillEvent), {
+ success: false,
+ });
+ assert.deepEqual(await handlers.get("cancel-agent-panel-dictation")(pillEvent), {
+ success: false,
+ });
+ assert.equal(calls.toggle, 0);
+ assert.equal(calls.cancel, 0);
+});
+
+test("an interactive pill click reaches the dictation toggle and cancel", async () => {
+ const { stub, calls, pillContents } = makeWindowManagerStub();
+ installWindowManager(stub);
+ const pillEvent = { sender: pillContents };
+
+ assert.deepEqual(await handlers.get("toggle-agent-panel-dictation")(pillEvent), {
+ success: true,
+ });
+ assert.deepEqual(await handlers.get("cancel-agent-panel-dictation")(pillEvent), {
+ success: true,
+ });
+ assert.equal(calls.toggle, 1);
+ assert.equal(calls.cancel, 1);
+});
+
+test("audio levels are accepted only from the dictation renderer", () => {
+ const { stub, calls, mainContents } = makeWindowManagerStub();
+ installWindowManager(stub);
+ const levelHandler = onHandlers.get("dictation-audio-level-changed");
+
+ levelHandler({ sender: {} }, 0.5);
+ assert.deepEqual(calls.levels, []);
+ levelHandler({ sender: mainContents }, 0.5);
+ assert.deepEqual(calls.levels, [0.5]);
+});
+
+test("lifecycle reports are accepted only from the dictation renderer", () => {
+ const { stub, calls, mainContents } = makeWindowManagerStub();
+ installWindowManager(stub);
+ const lifecycleHandler = onHandlers.get("dictation-lifecycle-state-changed");
+
+ lifecycleHandler({ sender: {} }, "recording", "dictation");
+ assert.deepEqual(calls.lifecycle, []);
+ lifecycleHandler({ sender: mainContents }, "recording", "dictation");
+ assert.deepEqual(calls.lifecycle, [["recording", "dictation"]]);
+});
+
+// Bonus: the third `ipcMain.on` handler added alongside the two above shares
+// the same dictation-renderer sender gate.
+test("the final-transcript relay is accepted only from the dictation renderer", () => {
+ const { stub, mainContents } = makeWindowManagerStub();
+ const shown = [];
+ stub.showAgentDictationFinalTranscript = (text) => shown.push(text);
+ installWindowManager(stub);
+ const finalTranscriptHandler = onHandlers.get("show-agent-dictation-final-transcript");
+ assert.ok(finalTranscriptHandler, "show-agent-dictation-final-transcript must be registered");
+
+ finalTranscriptHandler({ sender: {} }, "hello world");
+ assert.deepEqual(shown, []);
+ finalTranscriptHandler({ sender: mainContents }, "hello world");
+ assert.deepEqual(shown, ["hello world"]);
+});
diff --git a/test/helpers/dictationLifecycle.test.js b/test/helpers/dictationLifecycle.test.js
index 7f69428c2..79019d354 100644
--- a/test/helpers/dictationLifecycle.test.js
+++ b/test/helpers/dictationLifecycle.test.js
@@ -6,6 +6,7 @@ const {
normalizeDictationLifecycle,
shouldIgnoreDictationHotkey,
isDictationRecording,
+ resolveAgentDictationPillState,
shouldBlockDictationWhilePanelOpen,
} = require("../../src/helpers/dictationLifecycle");
@@ -27,16 +28,85 @@ test("unknown lifecycle input fails closed to idle", () => {
assert.equal(isDictationRecording({}), false);
});
-test("regular dictation is blocked while the assistant panel is open", () => {
+test("the Agent companion mirrors only ordinary dictation lifecycle", () => {
+ assert.deepEqual(resolveAgentDictationPillState("recording", "dictation"), {
+ lifecycle: "recording",
+ interactive: true,
+ });
+ assert.deepEqual(resolveAgentDictationPillState("processing", "dictation"), {
+ lifecycle: "processing",
+ interactive: true,
+ });
+ assert.deepEqual(resolveAgentDictationPillState("recording", "assistant"), {
+ lifecycle: "idle",
+ interactive: false,
+ });
+ assert.deepEqual(resolveAgentDictationPillState("processing", "translation"), {
+ lifecycle: "idle",
+ interactive: false,
+ });
+});
+
+test("regular dictation remains available while the assistant panel is open", () => {
+ assert.equal(
+ shouldBlockDictationWhilePanelOpen({
+ assistantPanelOpen: true,
+ assistantPanelBusy: true,
+ inputKind: "dictation",
+ companionAvailable: true,
+ }),
+ false
+ );
+});
+
+test("regular dictation is blocked while the open panel lacks a live companion", () => {
+ // The open panel hands plain dictation's visuals to the companion pill; if
+ // that window is still loading or its load failed, the recording would be
+ // invisible, so it must not start.
+ assert.equal(
+ shouldBlockDictationWhilePanelOpen({
+ assistantPanelOpen: true,
+ inputKind: "dictation",
+ companionAvailable: false,
+ }),
+ true
+ );
+ // With the panel closed the main pill owns the visuals; companion
+ // availability is irrelevant.
+ assert.equal(
+ shouldBlockDictationWhilePanelOpen({
+ assistantPanelOpen: false,
+ inputKind: "dictation",
+ companionAvailable: false,
+ }),
+ false
+ );
+});
+
+test("regular dictation is blocked while a busy assistant has not opened its panel", () => {
+ // The companion pill only exists once the panel opens; before that, a busy
+ // assistant suppresses the main pill too, so a recording would be invisible.
assert.equal(
- shouldBlockDictationWhilePanelOpen({ assistantPanelOpen: true, voiceAgentRequested: false }),
+ shouldBlockDictationWhilePanelOpen({
+ assistantPanelOpen: false,
+ assistantPanelBusy: true,
+ inputKind: "dictation",
+ }),
true
);
+ assert.equal(
+ shouldBlockDictationWhilePanelOpen({
+ assistantPanelOpen: false,
+ assistantPanelBusy: false,
+ inputKind: "dictation",
+ }),
+ false
+ );
});
test("the assistant hotkey can still record an in-panel follow-up", () => {
assert.equal(
- shouldBlockDictationWhilePanelOpen({ assistantPanelOpen: true, voiceAgentRequested: true }),
+ shouldBlockDictationWhilePanelOpen({ assistantPanelOpen: true, inputKind: "assistant" }),
false
);
});
@@ -46,7 +116,7 @@ test("the assistant hotkey is blocked while the open panel is busy", () => {
shouldBlockDictationWhilePanelOpen({
assistantPanelOpen: true,
assistantPanelBusy: true,
- voiceAgentRequested: true,
+ inputKind: "assistant",
}),
true
);
@@ -57,15 +127,37 @@ test("the assistant hotkey is blocked while an initial response thinks before th
shouldBlockDictationWhilePanelOpen({
assistantPanelOpen: false,
assistantPanelBusy: true,
- voiceAgentRequested: true,
+ inputKind: "assistant",
}),
true
);
});
-test("regular dictation resumes after the assistant panel closes", () => {
+test("translation remains blocked while the assistant panel owns the shared surface", () => {
assert.equal(
- shouldBlockDictationWhilePanelOpen({ assistantPanelOpen: false, voiceAgentRequested: false }),
+ shouldBlockDictationWhilePanelOpen({ assistantPanelOpen: true, inputKind: "translation" }),
+ true
+ );
+ assert.equal(
+ shouldBlockDictationWhilePanelOpen({ assistantPanelOpen: false, inputKind: "translation" }),
false
);
});
+
+test("mic preparation is a first-class lifecycle mirrored only for ordinary dictation", () => {
+ assert.equal(normalizeDictationLifecycle("preparing"), "preparing");
+ assert.equal(shouldIgnoreDictationHotkey("preparing"), false);
+ assert.equal(isDictationRecording("preparing"), false);
+ assert.deepEqual(resolveAgentDictationPillState("preparing", "dictation"), {
+ lifecycle: "preparing",
+ interactive: true,
+ });
+ assert.deepEqual(resolveAgentDictationPillState("preparing", "assistant"), {
+ lifecycle: "idle",
+ interactive: false,
+ });
+ assert.deepEqual(resolveAgentDictationPillState("preparing", "translation"), {
+ lifecycle: "idle",
+ interactive: false,
+ });
+});
diff --git a/test/helpers/dictationRouting.test.js b/test/helpers/dictationRouting.test.js
index d3709415d..3e2513558 100644
--- a/test/helpers/dictationRouting.test.js
+++ b/test/helpers/dictationRouting.test.js
@@ -730,3 +730,16 @@ test("wake-word language is undefined when no usable hint exists", async () => {
);
assert.equal(resolveWakeWordLanguage({}), undefined);
});
+
+test("lifecycle input kind prefers assistant, then translation, then dictation", async () => {
+ const { resolveLifecycleInputKind } = await load();
+ assert.equal(
+ resolveLifecycleInputKind({ voiceAgentRequested: true, translationRequested: true }),
+ "assistant"
+ );
+ assert.equal(
+ resolveLifecycleInputKind({ voiceAgentRequested: false, translationRequested: true }),
+ "translation"
+ );
+ assert.equal(resolveLifecycleInputKind({}), "dictation");
+});
diff --git a/test/helpers/preloadAuthBridge.test.js b/test/helpers/preloadAuthBridge.test.js
index 33c96cf6d..362a2f4ed 100644
--- a/test/helpers/preloadAuthBridge.test.js
+++ b/test/helpers/preloadAuthBridge.test.js
@@ -117,6 +117,39 @@ test("assistant busy state is forwarded to the main-process hotkey guard", async
assert.deepEqual(invocations, [["set-assistant-panel-busy", true]]);
});
+test("dictation lifecycle and audio levels preserve companion routing metadata", () => {
+ const { api, sends } = loadPreloadApi();
+
+ api.dictationLifecycleStateChanged("recording", "assistant");
+ api.dictationAudioLevelChanged(0.42);
+
+ assert.deepEqual(sends, [
+ ["dictation-lifecycle-state-changed", "recording", "assistant"],
+ ["dictation-audio-level-changed", 0.42],
+ ]);
+});
+
+test("the Agent companion owns only its scoped window bridges", async () => {
+ const { api, invocations, sends } = loadPreloadApi();
+
+ await api.resizeAgentDictationPillToContent(240);
+ await api.resizeAgentDictationPillToContent(null);
+ await api.setAgentDictationPillInteractivity(true);
+ await api.cancelAgentPanelDictation();
+ api.showAgentDictationFinalTranscript("recovered text");
+
+ assert.deepEqual(invocations, [
+ ["resize-agent-dictation-pill-to-content", 240],
+ ["resize-agent-dictation-pill-to-content", null],
+ ["set-agent-dictation-pill-interactivity", true],
+ ["cancel-agent-panel-dictation"],
+ ]);
+ assert.deepEqual(
+ sends.filter(([channel]) => channel === "show-agent-dictation-final-transcript"),
+ [["show-agent-dictation-final-transcript", "recovered text"]]
+ );
+});
+
test("agent streaming forwards correlated start and cancel messages", () => {
const { api, sends } = loadPreloadApi();
const messages = [{ role: "user", content: "hello" }];
@@ -178,3 +211,15 @@ test("agent streaming listeners strip Electron events and preserve correlation",
assert.equal(listeners.has("cloud-agent-stream-error"), false);
assert.equal(listeners.has("cloud-agent-stream-end"), false);
});
+
+test("prepare-dictation forwards the input kind without the Electron event", () => {
+ const { api, listeners } = loadPreloadApi();
+ const received = [];
+ const dispose = api.onPrepareDictation((options) => received.push(options));
+
+ listeners.get("prepare-dictation")?.({ senderId: 1 }, { inputKind: "assistant" });
+
+ dispose();
+ assert.deepEqual(received, [{ inputKind: "assistant" }]);
+ assert.equal(listeners.has("prepare-dictation"), false);
+});
diff --git a/test/helpers/useAudioRecordingPreparingReset.test.js b/test/helpers/useAudioRecordingPreparingReset.test.js
new file mode 100644
index 000000000..9a088a10c
--- /dev/null
+++ b/test/helpers/useAudioRecordingPreparingReset.test.js
@@ -0,0 +1,116 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const React = require("react");
+const { createRoot } = require("react-dom/client");
+const {
+ createRendererServer,
+ installBrowserGlobals,
+ installHookDom,
+} = require("../lib/rendererTestHarness");
+
+// A minimal AudioManager stand-in whose startRecording() fails without ever
+// invoking the onStateChange callback registered via setCallbacks — this
+// mirrors the real failure path (mic-open rejection, permission denial,
+// etc.), where only onError fires. reportLifecycle's own report inside
+// performStartRecording, and its finally-block reset, are the only things
+// this test exercises.
+const FAKE_AUDIO_MANAGER_SOURCE = `
+export default class FakeAudioManager {
+ constructor() {
+ this.voiceAgentRequested = false;
+ this.translationRequested = false;
+ this.sttConfig = { success: true };
+ }
+ getState() {
+ return {};
+ }
+ setCallbacks() {}
+ setVoiceAgentRequested(value) {
+ this.voiceAgentRequested = value;
+ }
+ setAssistantSelectionContext() {}
+ setTranslationRequested(value) {
+ this.translationRequested = value;
+ }
+ shouldUseStreaming() {
+ return false;
+ }
+ prepareMicCapture() {}
+ cancelPreparedMicCapture() {}
+ cleanup() {}
+ async startRecording() {
+ return false;
+ }
+}
+`;
+
+test("a failed dictation start reports the lifecycle back to idle instead of sticking on preparing", async (t) => {
+ // t.after hooks run in registration order, so this unmount must be
+ // registered before installBrowserGlobals/installHookDom's own cleanup —
+ // otherwise window/document are already torn down when unmount runs.
+ let root = null;
+ t.after(async () => {
+ if (root) await React.act(async () => root.unmount());
+ });
+
+ const reported = [];
+ const noopDispose = () => () => {};
+ installBrowserGlobals(t, {
+ window: {
+ electronAPI: {
+ // The mount effect registers all seven of these unconditionally (or
+ // via optional chaining); onToggleDictation in particular is called
+ // without "?.", so it must exist even though this test drives
+ // startRecording() directly rather than through any of these events.
+ onToggleDictation: noopDispose,
+ onToggleVoiceAgent: noopDispose,
+ onToggleTranslation: noopDispose,
+ onStartDictation: noopDispose,
+ onPrepareDictation: noopDispose,
+ onCancelDictationPreparation: noopDispose,
+ onStopDictation: noopDispose,
+ dictationLifecycleStateChanged: (state, inputKind) =>
+ reported.push(`${state}:${inputKind}`),
+ },
+ },
+ });
+ const container = installHookDom(t);
+ // The start path awaits two animation frames before opening the mic;
+ // resolve them synchronously instead of riding out the 250ms/frame
+ // fallback timeout twice in this test.
+ globalThis.requestAnimationFrame = (callback) => {
+ callback();
+ return 1;
+ };
+
+ const vite = await createRendererServer(t, {
+ cachePrefix: "openwhispr-audio-recording-preparing-reset-",
+ mockModules: {
+ "/helpers/audioManager": FAKE_AUDIO_MANAGER_SOURCE,
+ },
+ });
+ const { useAudioRecording } = await vite.ssrLoadModule("/hooks/useAudioRecording.js");
+
+ let api;
+ function Harness() {
+ api = useAudioRecording(() => {}, { onDemoEvent: () => {} });
+ return null;
+ }
+
+ root = createRoot(container);
+ await React.act(async () => {
+ root.render(React.createElement(Harness));
+ });
+
+ // The mount effect reports its own "idle" reset; isolate the assertion to
+ // what performStartRecording itself reports.
+ reported.length = 0;
+
+ let started;
+ await React.act(async () => {
+ started = await api.startRecording();
+ });
+
+ assert.equal(started, false);
+ assert.deepEqual(reported, ["preparing:dictation", "idle:dictation"]);
+});
diff --git a/test/helpers/voicePillPresentation.test.js b/test/helpers/voicePillPresentation.test.js
index e1fc6b305..202f7acd7 100644
--- a/test/helpers/voicePillPresentation.test.js
+++ b/test/helpers/voicePillPresentation.test.js
@@ -620,3 +620,112 @@ test("an Agent follow-up keeps the existing response modal open while thinking",
thinking: true,
});
});
+
+test("a collapsed transcript stays reopenable while its result is processing", async () => {
+ const { resolveCompanionPillInteractive } = await load();
+
+ assert.equal(
+ resolveCompanionPillInteractive({
+ mainProcessInteractive: true,
+ surfaceInteractive: true,
+ isProcessing: true,
+ canReopenLiveTranscript: true,
+ }),
+ true
+ );
+ assert.equal(
+ resolveCompanionPillInteractive({
+ mainProcessInteractive: true,
+ surfaceInteractive: true,
+ isProcessing: true,
+ canReopenLiveTranscript: false,
+ }),
+ false
+ );
+ assert.equal(
+ resolveCompanionPillInteractive({
+ mainProcessInteractive: false,
+ surfaceInteractive: true,
+ isProcessing: false,
+ canReopenLiveTranscript: true,
+ }),
+ false
+ );
+ assert.equal(
+ resolveCompanionPillInteractive({
+ mainProcessInteractive: true,
+ surfaceInteractive: false,
+ isProcessing: false,
+ canReopenLiveTranscript: false,
+ }),
+ false
+ );
+});
+
+test("final Agent actions keep the idle pill hidden until the panel finishes closing", async () => {
+ const { shouldSuppressPillForAssistantActions } = await load();
+
+ assert.equal(
+ shouldSuppressPillForAssistantActions({
+ assistantOpen: true,
+ footerPillVisible: false,
+ assistantClosing: false,
+ hasLiveActivity: false,
+ }),
+ true
+ );
+ assert.equal(
+ shouldSuppressPillForAssistantActions({
+ assistantOpen: true,
+ footerPillVisible: false,
+ assistantClosing: true,
+ hasLiveActivity: false,
+ }),
+ true
+ );
+ assert.equal(
+ shouldSuppressPillForAssistantActions({
+ assistantOpen: true,
+ footerPillVisible: true,
+ assistantClosing: false,
+ hasLiveActivity: false,
+ }),
+ false
+ );
+ assert.equal(
+ shouldSuppressPillForAssistantActions({
+ assistantOpen: false,
+ footerPillVisible: false,
+ assistantClosing: false,
+ hasLiveActivity: true,
+ }),
+ false
+ );
+});
+
+test("activity handed back at close intent stays visible through the content fade", async () => {
+ const { shouldSuppressPillForAssistantActions } = await load();
+
+ // The companion hides at close INTENT while `assistantOpen` stays true until
+ // the fade completes: suppressing here is the both-hidden gap.
+ assert.equal(
+ shouldSuppressPillForAssistantActions({
+ assistantOpen: true,
+ footerPillVisible: false,
+ assistantClosing: true,
+ hasLiveActivity: true,
+ }),
+ false
+ );
+ // Before close intent the footer still owns the visuals, so a companion
+ // recording must not surface a second pill here.
+ assert.equal(
+ shouldSuppressPillForAssistantActions({
+ assistantOpen: true,
+ footerPillVisible: false,
+ assistantClosing: false,
+ hasLiveActivity: true,
+ }),
+ true
+ );
+});
diff --git a/test/helpers/windowManagerAssistantPanel.test.js b/test/helpers/windowManagerAssistantPanel.test.js
index 6443f8c28..746136fd1 100644
--- a/test/helpers/windowManagerAssistantPanel.test.js
+++ b/test/helpers/windowManagerAssistantPanel.test.js
@@ -1,6 +1,9 @@
const test = require("node:test");
const assert = require("node:assert/strict");
const Module = require("node:module");
+const requestedMainWindowPositions = [];
+const createdBrowserWindows = [];
+const screenListeners = [];
// Same stub set as windowManagerMeetingNotification.test.js: WindowManager
// pulls in electron + sibling managers at require time.
@@ -9,8 +12,43 @@ Module._load = function loadWindowManagerWithStubs(request, parent, isMain) {
if (request === "electron") {
return {
app: { on: () => undefined },
- screen: { getPrimaryDisplay: () => ({}), getDisplayMatching: () => ({ workArea: { x: 0, y: 0, width: 1440, height: 900 } }), getDisplayNearestPoint: () => ({ workArea: { x: 0, y: 0, width: 1440, height: 900 } }) },
- BrowserWindow: class {},
+ screen: {
+ getPrimaryDisplay: () => ({}),
+ getDisplayMatching: () => ({ workArea: { x: 0, y: 0, width: 1440, height: 900 } }),
+ getDisplayNearestPoint: () => ({ workArea: { x: 0, y: 0, width: 1440, height: 900 } }),
+ on: (event, listener) => screenListeners.push({ event, listener }),
+ },
+ BrowserWindow: class FakeBrowserWindow {
+ constructor(options) {
+ this.options = options;
+ this.protectionCalls = [];
+ this.closeCalls = 0;
+ this.setBoundsCalls = 0;
+ this.visible = false;
+ this.bounds = { x: 0, y: 0, width: 0, height: 0 };
+ this.windowListeners = new Map();
+ this.sent = [];
+ this.webContentsListeners = new Map();
+ this.webContents = {
+ on: (event, listener) => this.webContentsListeners.set(event, listener),
+ send: (channel, payload) => this.sent.push({ channel, payload }),
+ };
+ createdBrowserWindows.push(this);
+ }
+ on(event, listener) { this.windowListeners.set(event, listener); }
+ setContentProtection(value) { this.protectionCalls.push(value); }
+ setIgnoreMouseEvents() {}
+ loadFile() { return Promise.resolve(); }
+ loadURL() { return Promise.resolve(); }
+ isDestroyed() { return false; }
+ close() { this.closeCalls += 1; this.windowListeners.get("closed")?.(); }
+ getBounds() { return this.bounds; }
+ setBounds(nextBounds) { this.bounds = nextBounds; this.setBoundsCalls += 1; }
+ isVisible() { return this.visible; }
+ showInactive() { this.visible = true; }
+ hide() { this.visible = false; }
+ moveTop() {}
+ },
shell: {},
dialog: {},
};
@@ -38,7 +76,15 @@ Module._load = function loadWindowManagerWithStubs(request, parent, isMain) {
COMPACT: { width: 480, height: 624 },
EXPANDED: { width: 1000, height: 740 },
},
- WindowPositionUtil: { setupAlwaysOnTop: () => undefined, clampToWorkArea: (b) => b, getMainWindowPosition: () => ({ x: 0, y: 0 }), getNotificationPosition: () => ({ x: 0, y: 0 }) },
+ WindowPositionUtil: {
+ setupAlwaysOnTop: () => undefined,
+ clampToWorkArea: (b) => b,
+ getMainWindowPosition: (_display, size, position) => {
+ requestedMainWindowPositions.push(position);
+ return { x: 0, y: 0, ...size };
+ },
+ getNotificationPosition: () => ({ x: 0, y: 0 }),
+ },
fitAssistantWindowToWorkArea: (s) => s,
fitAssistantContentWindowToWorkArea: (h) => ({ width: 466, height: h }),
fitDictationErrorWindowToWorkArea: (s) => s,
@@ -79,9 +125,190 @@ function makeManager(windowState) {
manager.mainWindow = fake.window;
manager.enforceMainWindowOnTop = () => undefined;
manager._notifyMainWindowHorizontalDirection = () => undefined;
+ manager.showAgentDictationPill = () => undefined;
+ manager.hideAgentDictationPill = () => undefined;
return { manager, calls: fake.calls };
}
+test("the Agent companion follows the edge opposite the panel", () => {
+ requestedMainWindowPositions.length = 0;
+ const manager = new WindowManager();
+ const positions = [];
+ manager.mainWindow = {
+ isDestroyed: () => false,
+ getBounds: () => ({ x: 1000, y: 100, width: 400, height: 600 }),
+ };
+ manager.agentDictationPillWindow = {
+ isDestroyed: () => false,
+ setBounds: (bounds) => positions.push(bounds),
+ };
+
+ manager.positionAgentDictationPill();
+
+ assert.deepEqual(positions, [{ x: 0, y: 0, width: 96, height: 96 }]);
+ assert.deepEqual(requestedMainWindowPositions, ["bottom-left"]);
+});
+
+test("the companion grows for Live Transcript and returns to its pill footprint", () => {
+ const manager = new WindowManager();
+ let bounds = { x: 0, y: 0, width: 96, height: 96 };
+ manager.mainWindow = {
+ isDestroyed: () => false,
+ getBounds: () => ({ x: 1000, y: 100, width: 400, height: 600 }),
+ };
+ manager.agentDictationPillWindow = {
+ isDestroyed: () => false,
+ getBounds: () => bounds,
+ setBounds: (nextBounds) => {
+ bounds = nextBounds;
+ },
+ };
+
+ const expanded = manager.resizeAgentDictationPillToContent(240);
+ const collapsed = manager.resizeAgentDictationPillToContent(null);
+
+ assert.equal(expanded.success, true);
+ assert.deepEqual(expanded.bounds, { x: 0, y: 0, width: 466, height: 240 });
+ assert.equal(collapsed.success, true);
+ assert.deepEqual(collapsed.bounds, { x: 0, y: 0, width: 96, height: 96 });
+});
+
+test("the Agent companion ignores Agent voice lifecycle and mirrors plain dictation", () => {
+ const manager = new WindowManager();
+ const messages = [];
+ manager._agentDictationPillReady = true;
+ manager.agentDictationPillWindow = {
+ isDestroyed: () => false,
+ webContents: { send: (channel, payload) => messages.push({ channel, payload }) },
+ };
+
+ manager.setDictationLifecycleState("recording", "assistant");
+ manager.setDictationLifecycleState("recording", "dictation");
+
+ assert.deepEqual(messages, [
+ {
+ channel: "agent-dictation-pill-state-changed",
+ payload: { lifecycle: "idle", interactive: false, horizontalDirection: "left" },
+ },
+ {
+ channel: "agent-dictation-pill-state-changed",
+ payload: { lifecycle: "recording", interactive: true, horizontalDirection: "left" },
+ },
+ ]);
+});
+
+test("the companion receives live audio levels only for ordinary dictation", () => {
+ const manager = new WindowManager();
+ const messages = [];
+ manager._assistantPanelOpen = true;
+ manager._agentDictationPillReady = true;
+ manager.agentDictationPillWindow = {
+ isDestroyed: () => false,
+ webContents: { send: (channel, payload) => messages.push({ channel, payload }) },
+ };
+
+ manager.setDictationLifecycleState("recording", "dictation");
+ messages.length = 0;
+ manager.setDictationAudioLevel(0.42);
+ manager.setDictationLifecycleState("recording", "assistant");
+ manager.setDictationAudioLevel(0.9);
+
+ assert.deepEqual(messages, [
+ { channel: "agent-dictation-pill-audio-level-changed", payload: 0.42 },
+ {
+ channel: "agent-dictation-pill-state-changed",
+ payload: { lifecycle: "idle", interactive: false, horizontalDirection: "left" },
+ },
+ ]);
+});
+
+test("the companion toggles macOS click-through with hover interactivity", () => {
+ const manager = new WindowManager();
+ const ignoreCalls = [];
+ manager.agentDictationPillWindow = {
+ isDestroyed: () => false,
+ setIgnoreMouseEvents: (ignore, opts) => ignoreCalls.push({ ignore, opts }),
+ };
+
+ const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform");
+ Object.defineProperty(process, "platform", { value: "darwin" });
+ try {
+ manager.setAgentDictationPillInteractivity(true);
+ manager.setAgentDictationPillInteractivity(false);
+ // Windows/Linux keep normal hit-testing (forward is unreliable/ignored).
+ Object.defineProperty(process, "platform", { value: "linux" });
+ manager.setAgentDictationPillInteractivity(false);
+ } finally {
+ Object.defineProperty(process, "platform", originalPlatform);
+ }
+
+ assert.deepEqual(ignoreCalls, [
+ { ignore: false, opts: undefined },
+ { ignore: true, opts: { forward: true } },
+ ]);
+});
+
+test("the Agent companion window is created content-protected", () => {
+ createdBrowserWindows.length = 0;
+ const manager = new WindowManager();
+ manager.setOnboardingActive(false);
+ manager._assistantPanelOpen = true;
+ manager.mainWindow = {
+ isDestroyed: () => false,
+ getBounds: () => ({ x: 1000, y: 100, width: 400, height: 600 }),
+ };
+
+ manager.showAgentDictationPill();
+
+ assert.equal(createdBrowserWindows.length, 1);
+ assert.deepEqual(createdBrowserWindows[0].protectionCalls, [true]);
+});
+
+test("the companion cancel control routes through the dictation renderer", () => {
+ const manager = new WindowManager();
+ const channels = [];
+ manager.mainWindow = {
+ isDestroyed: () => false,
+ webContents: { send: (channel) => channels.push(channel) },
+ };
+
+ manager.sendCancelActiveDictation();
+
+ assert.deepEqual(channels, ["cancel-dictation"]);
+});
+
+test("live transcript events are mirrored to the companion only for plain dictation", async () => {
+ const manager = new WindowManager();
+ const mainMessages = [];
+ const companionMessages = [];
+ manager.setOnboardingActive(false);
+ manager._assistantPanelOpen = true;
+ manager._agentDictationPillReady = true;
+ manager.mainWindow = {
+ isDestroyed: () => false,
+ showInactive: () => undefined,
+ webContents: { send: (channel, payload) => mainMessages.push({ channel, payload }) },
+ };
+ manager.agentDictationPillWindow = {
+ isDestroyed: () => false,
+ webContents: {
+ send: (channel, payload) => companionMessages.push({ channel, payload }),
+ },
+ };
+ manager.enforceMainWindowOnTop = () => undefined;
+
+ manager._dictationInputKind = "assistant";
+ await manager.showTranscriptionPreview("agent");
+ manager._dictationInputKind = "dictation";
+ await manager.showTranscriptionPreview("plain");
+
+ assert.deepEqual(mainMessages, [
+ { channel: "preview-text", payload: "agent" },
+ { channel: "preview-text", payload: "plain" },
+ ]);
+ assert.deepEqual(companionMessages, [{ channel: "preview-text", payload: "plain" }]);
+});
+
test("opening the assistant panel surfaces a hidden pill window before focusing it", () => {
const { manager, calls } = makeManager({ visible: false });
manager.setAssistantPanelOpen(true);
@@ -224,3 +451,223 @@ test("a real drag marks the pill as manually positioned", async () => {
await manager.stopWindowDrag();
assert.equal(manager._mainWindowPlacementCoordinator._hasManualPosition, true);
});
+
+test("did-finish-load marks the companion ready, pushes state, and shows it", () => {
+ createdBrowserWindows.length = 0;
+ const manager = new WindowManager();
+ manager.setOnboardingActive(false);
+ manager._assistantPanelOpen = true;
+ manager.mainWindow = {
+ isDestroyed: () => false,
+ getBounds: () => ({ x: 1000, y: 100, width: 400, height: 600 }),
+ };
+
+ manager.showAgentDictationPill();
+ const pill = createdBrowserWindows[0];
+ assert.equal(manager._agentDictationPillReady, false);
+
+ pill.webContentsListeners.get("did-finish-load")();
+
+ assert.equal(manager._agentDictationPillReady, true);
+ assert.deepEqual(pill.sent, [
+ {
+ channel: "agent-dictation-pill-state-changed",
+ payload: { lifecycle: "idle", interactive: true, horizontalDirection: "left" },
+ },
+ ]);
+ assert.equal(pill.visible, true);
+});
+
+test("a crashed companion renderer drops readiness and closes for recreation", () => {
+ createdBrowserWindows.length = 0;
+ const manager = new WindowManager();
+ manager.setOnboardingActive(false);
+ manager._assistantPanelOpen = true;
+ manager.mainWindow = {
+ isDestroyed: () => false,
+ getBounds: () => ({ x: 1000, y: 100, width: 400, height: 600 }),
+ };
+
+ manager.showAgentDictationPill();
+ const pill = createdBrowserWindows[0];
+ pill.webContentsListeners.get("did-finish-load")();
+ assert.equal(manager._agentDictationPillReady, true);
+
+ pill.webContentsListeners.get("render-process-gone")(null, { reason: "crashed" });
+
+ assert.equal(manager._agentDictationPillReady, false);
+ assert.equal(pill.closeCalls, 1);
+ assert.equal(manager.agentDictationPillWindow, null);
+ assert.equal(manager._isAgentDictationPillAvailable(), false);
+});
+
+test("a clean-exit companion renderer teardown leaves readiness untouched", () => {
+ createdBrowserWindows.length = 0;
+ const manager = new WindowManager();
+ manager.setOnboardingActive(false);
+ manager._assistantPanelOpen = true;
+ manager.mainWindow = {
+ isDestroyed: () => false,
+ getBounds: () => ({ x: 1000, y: 100, width: 400, height: 600 }),
+ };
+
+ manager.showAgentDictationPill();
+ const pill = createdBrowserWindows[0];
+ pill.webContentsListeners.get("did-finish-load")();
+ assert.equal(manager._agentDictationPillReady, true);
+
+ pill.webContentsListeners.get("render-process-gone")(null, { reason: "clean-exit" });
+
+ assert.equal(manager._agentDictationPillReady, true);
+ assert.equal(pill.closeCalls, 0);
+ assert.equal(manager.agentDictationPillWindow, pill);
+});
+
+test("prepare-dictation carries the toggle's input kind to the renderer", () => {
+ const manager = new WindowManager();
+ manager.setOnboardingActive(false);
+ manager.hotkeyManager = { isInListeningMode: () => false };
+ const sent = [];
+ manager.mainWindow = {
+ isDestroyed: () => false,
+ webContents: { send: (channel, payload) => sent.push({ channel, payload }) },
+ };
+
+ manager.sendPrepareDictation({ inputKind: "assistant" });
+ manager.sendPrepareDictation();
+
+ assert.deepEqual(sent, [
+ { channel: "prepare-dictation", payload: { inputKind: "assistant" } },
+ { channel: "prepare-dictation", payload: { inputKind: "dictation" } },
+ ]);
+});
+
+test("mic preparation reaches the companion as its own lifecycle", () => {
+ const manager = new WindowManager();
+ const messages = [];
+ manager._agentDictationPillReady = true;
+ manager.agentDictationPillWindow = {
+ isDestroyed: () => false,
+ webContents: { send: (channel, payload) => messages.push({ channel, payload }) },
+ };
+
+ manager.setDictationLifecycleState("preparing", "dictation");
+
+ assert.deepEqual(messages, [
+ {
+ channel: "agent-dictation-pill-state-changed",
+ payload: { lifecycle: "preparing", interactive: true, horizontalDirection: "left" },
+ },
+ ]);
+});
+
+test("error-recovery transcripts mirror to the companion only for plain dictation", () => {
+ const manager = new WindowManager();
+ const messages = [];
+ manager._assistantPanelOpen = true;
+ manager._agentDictationPillReady = true;
+ manager.agentDictationPillWindow = {
+ isDestroyed: () => false,
+ webContents: { send: (channel, payload) => messages.push({ channel, payload }) },
+ };
+
+ manager._dictationInputKind = "assistant";
+ manager.showAgentDictationFinalTranscript("agent");
+ manager._dictationInputKind = "dictation";
+ manager.showAgentDictationFinalTranscript("plain");
+
+ assert.deepEqual(messages, [
+ { channel: "agent-dictation-pill-final-transcript", payload: "plain" },
+ ]);
+});
+
+test("display changes reposition the companion pill", () => {
+ createdBrowserWindows.length = 0;
+ screenListeners.length = 0;
+ const manager = new WindowManager();
+ manager.setOnboardingActive(false);
+ manager._assistantPanelOpen = true;
+ manager.mainWindow = {
+ isDestroyed: () => false,
+ getBounds: () => ({ x: 1000, y: 100, width: 400, height: 600 }),
+ };
+
+ manager.showAgentDictationPill();
+ const pill = createdBrowserWindows[0];
+ pill.webContentsListeners.get("did-finish-load")();
+ const boundsCallsBefore = pill.setBoundsCalls;
+
+ const metricsListener = screenListeners.find((entry) => entry.event === "display-metrics-changed");
+ assert.ok(metricsListener, "display-metrics-changed listener registered");
+ metricsListener.listener();
+
+ assert.equal(pill.setBoundsCalls, boundsCallsBefore + 1);
+ assert.deepEqual(
+ screenListeners.map((entry) => entry.event).sort(),
+ ["display-added", "display-metrics-changed", "display-removed"]
+ );
+});
+
+test("onboarding suppresses the companion pill like every popup surface", () => {
+ createdBrowserWindows.length = 0;
+ const manager = new WindowManager();
+ manager.setOnboardingActive(true);
+ manager._assistantPanelOpen = true;
+ manager.mainWindow = {
+ isDestroyed: () => false,
+ getBounds: () => ({ x: 1000, y: 100, width: 400, height: 600 }),
+ };
+
+ manager.showAgentDictationPill();
+
+ assert.equal(createdBrowserWindows.length, 0);
+});
+
+test("a ready but hidden companion never counts as an available surface", () => {
+ createdBrowserWindows.length = 0;
+ const manager = new WindowManager();
+ manager.setOnboardingActive(false);
+ manager._assistantPanelOpen = true;
+ manager.mainWindow = {
+ isDestroyed: () => false,
+ getBounds: () => ({ x: 1000, y: 100, width: 400, height: 600 }),
+ };
+
+ manager.showAgentDictationPill();
+ const pill = createdBrowserWindows.at(-1);
+ pill.webContentsListeners.get("did-finish-load")();
+ assert.equal(pill.isVisible(), true);
+ assert.equal(manager._shouldBlockDictationInput("dictation"), false);
+
+ // Onboarding hides the pill without dropping readiness; a hidden surface
+ // cannot show a recording, so dictation must fail closed rather than start
+ // invisibly.
+ manager.hideAgentDictationPill();
+ assert.equal(pill.isVisible(), false);
+ assert.equal(manager._shouldBlockDictationInput("dictation"), true);
+ // The blocked press re-kicks the show, so the next press can land.
+ assert.equal(pill.isVisible(), true);
+});
+
+test("entering onboarding hides an already-visible companion pill", () => {
+ createdBrowserWindows.length = 0;
+ const manager = new WindowManager();
+ manager.setOnboardingActive(false);
+ manager._assistantPanelOpen = true;
+ manager.mainWindow = {
+ isDestroyed: () => false,
+ getBounds: () => ({ x: 1000, y: 100, width: 400, height: 600 }),
+ // Entering onboarding cancels any in-flight dictation before it hides
+ // the normal-app surfaces.
+ webContents: { send: () => undefined },
+ };
+
+ manager.showAgentDictationPill();
+ const pill = createdBrowserWindows.at(-1);
+ pill.webContentsListeners.get("did-finish-load")();
+ assert.equal(pill.isVisible(), true);
+
+ manager.setOnboardingActive(true);
+
+ assert.equal(pill.isVisible(), false);
+});
diff --git a/test/helpers/windowManagerMeetingNotification.test.js b/test/helpers/windowManagerMeetingNotification.test.js
index b7afd4c68..746c2ba6b 100644
--- a/test/helpers/windowManagerMeetingNotification.test.js
+++ b/test/helpers/windowManagerMeetingNotification.test.js
@@ -77,7 +77,7 @@ Module._load = function loadWindowManagerWithStubs(request, parent, isMain) {
if (request === "electron") {
return {
app: { on: () => undefined },
- screen: { getPrimaryDisplay: () => ({}) },
+ screen: { getPrimaryDisplay: () => ({}), on: () => undefined },
BrowserWindow: FakeBrowserWindow,
shell: {},
dialog: {},
@@ -238,20 +238,49 @@ test("a busy Assistant blocks its voice hotkey before native side effects", () =
manager._assistantPanelBusy = true;
manager.sendToggleVoiceAgent();
+ // Before the panel opens there is no companion pill to show a plain
+ // recording either, so the busy state blocks ordinary dictation too.
+ manager.sendToggleDictation();
assert.equal(showCount, 0);
assert.equal(prepareCount, 0);
assert.deepEqual(rendererChannels, []);
- manager._assistantPanelBusy = false;
- manager.sendToggleVoiceAgent();
+ // The open panel alone is not enough: until the companion window is live,
+ // a recording would still be invisible, so the press only re-kicks its load.
+ manager._assistantPanelOpen = true;
+ let pillShowCalls = 0;
+ manager.showAgentDictationPill = () => {
+ pillShowCalls += 1;
+ };
+ manager.sendToggleDictation();
+
+ assert.equal(showCount, 0);
+ assert.deepEqual(rendererChannels, []);
+ assert.equal(pillShowCalls, 1);
+
+ manager._agentDictationPillReady = true;
+ manager.agentDictationPillWindow = {
+ isDestroyed: () => false,
+ isVisible: () => true,
+ webContents: { send: () => undefined },
+ };
+ manager.sendToggleDictation();
assert.equal(showCount, 1);
assert.equal(prepareCount, 1);
- assert.deepEqual(rendererChannels, ["toggle-voice-agent"]);
+ assert.deepEqual(rendererChannels, ["toggle-dictation"]);
+ assert.equal(pillShowCalls, 1);
+
+ manager._assistantPanelBusy = false;
+ manager.sendToggleVoiceAgent();
+
+ assert.equal(showCount, 2);
+ assert.equal(prepareCount, 2);
+ assert.deepEqual(rendererChannels, ["toggle-dictation", "toggle-voice-agent"]);
});
-test("a busy Assistant blocks direct push-to-talk prepare and start paths", () => {
+test("push-to-talk dictation follows the companion pill's availability", () => {
const manager = createNormalWindowManager();
const rendererChannels = [];
let showCount = 0;
@@ -272,11 +301,39 @@ test("a busy Assistant blocks direct push-to-talk prepare and start paths", () =
showCount += 1;
};
+ // Busy without an open panel: no surface could show the recording.
manager.sendPrepareDictation();
manager.sendStartDictation();
assert.equal(showCount, 0);
assert.deepEqual(rendererChannels, []);
+
+ // An open panel whose companion window is not live yet keeps PTT dictation
+ // blocked; each press re-kicks the companion load.
+ manager._assistantPanelOpen = true;
+ let pillShowCalls = 0;
+ manager.showAgentDictationPill = () => {
+ pillShowCalls += 1;
+ };
+ manager.sendPrepareDictation();
+ manager.sendStartDictation();
+
+ assert.equal(showCount, 0);
+ assert.deepEqual(rendererChannels, []);
+ assert.equal(pillShowCalls, 2);
+
+ // With a live companion pill, PTT dictation flows again.
+ manager._agentDictationPillReady = true;
+ manager.agentDictationPillWindow = {
+ isDestroyed: () => false,
+ isVisible: () => true,
+ webContents: { send: () => undefined },
+ };
+ manager.sendPrepareDictation();
+ manager.sendStartDictation();
+
+ assert.equal(showCount, 1);
+ assert.deepEqual(rendererChannels, ["prepare-dictation", "start-dictation"]);
});
test("window manager starts fail-closed and suppresses normal-app popup surfaces", async () => {