Skip to content

The open alternative to Salesforce, designed for AI.

Add dictation to the AI chat composer (#25073)

Félix Malfait72a9c9ce92bb
diff --git a/packages/twenty-front/src/modules/ai/components/AiChatEditorSection.tsx b/packages/twenty-front/src/modules/ai/components/AiChatEditorSection.tsx
index 0f447bb1ab8..b5505b57fe5 100644
--- a/packages/twenty-front/src/modules/ai/components/AiChatEditorSection.tsx
+++ b/packages/twenty-front/src/modules/ai/components/AiChatEditorSection.tsx
@@ -1,3 +1,5 @@
+import { useState } from 'react';
+
import { styled } from '@linaria/react';
import { EditorContent } from '@tiptap/react';
import { useLingui } from '@lingui/react/macro';
@@ -12,12 +14,16 @@ import { AIChatNoMoreBillingCreditsBanner } from '@/ai/components/AIChatNoMoreBi
import { AiChatStandaloneError } from '@/ai/components/AiChatStandaloneError';
import { AgentChatContextPreview } from '@/ai/components/internal/AgentChatContextPreview';
import { AgentChatFileUploadButton } from '@/ai/components/internal/AgentChatFileUploadButton';
+import { AiChatDictationButton } from '@/ai/dictation/components/AiChatDictationButton';
+import { AiChatDictationEffect } from '@/ai/dictation/components/AiChatDictationEffect';
+import { AiChatDictationHint } from '@/ai/dictation/components/AiChatDictationHint';
import { AiChatContextUsageButton } from '@/ai/components/internal/AiChatContextUsageButton';
import { AiChatEditorFocusEffect } from '@/ai/components/internal/AiChatEditorFocusEffect';
import { AiChatSkeletonLoader } from '@/ai/components/internal/AiChatSkeletonLoader';
import { SendMessageButton } from '@/ai/components/internal/SendMessageButton';
import { useAgentChatModelId } from '@/ai/hooks/useAgentChatModelId';
import { useAiChatEditor } from '@/ai/hooks/useAiChatEditor';
+import { useInsertDictatedText } from '@/ai/dictation/hooks/useInsertDictatedText';
import { useIsAiChatComposerCentered } from '@/ai/hooks/useIsAiChatComposerCentered';
import { useAiModelOptions } from '@/ai/hooks/useAiModelOptions';
import { useHasReachedAiChatCreditsCap } from '@/ai/hooks/useHasReachedAiChatCreditsCap';
@@ -164,6 +170,9 @@ export const AiChatEditorSection = () => {
const { editor, handleSendAndClear } = useAiChatEditor();
+ const insertDictatedText = useInsertDictatedText(editor);
+ const [dictationInterimText, setDictationInterimText] = useState('');
+
const pendingQuestion = useAtomComponentSelectorValue(
agentChatPendingQuestionComponentSelector,
);
@@ -171,6 +180,10 @@ export const AiChatEditorSection = () => {
return (
<>
<AiChatEditorFocusEffect editor={editor} />
+ <AiChatDictationEffect
+ onInterimText={setDictationInterimText}
+ onFinalText={insertDictatedText}
+ />
<AiChatEmptyState isCentered={isComposerCentered} />
<AiChatStandaloneError />
<AiChatSkeletonLoader />
@@ -191,9 +204,11 @@ export const AiChatEditorSection = () => {
<StyledEditorWrapper isMobile={isMobile}>
<EditorContent editor={editor} />
</StyledEditorWrapper>
+ <AiChatDictationHint interimText={dictationInterimText} />
<StyledButtonsContainer>
<StyledLeftButtonsContainer>
<AgentChatFileUploadButton />
+ <AiChatDictationButton />
<AiChatContextUsageButton />
</StyledLeftButtonsContainer>
<StyledRightButtonsContainer>
diff --git a/packages/twenty-front/src/modules/ai/dictation/components/AiChatDictationButton.tsx b/packages/twenty-front/src/modules/ai/dictation/components/AiChatDictationButton.tsx
new file mode 100644
index 00000000000..53667889588
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/components/AiChatDictationButton.tsx
@@ -0,0 +1,26 @@
+import { t } from '@lingui/core/macro';
+import { IconMicrophone } from 'twenty-ui/icon';
+import { IconButton } from 'twenty-ui/input';
+
+import { useDictation } from '@/ai/dictation/hooks/useDictation';
+
+export const AiChatDictationButton = () => {
+ const { isAvailable, isRecording, toggleDictation } = useDictation();
+
+ if (!isAvailable) {
+ return null;
+ }
+
+ const ariaLabel = isRecording ? t`Stop dictation` : t`Start dictation`;
+
+ return (
+ <IconButton
+ variant="tertiary"
+ size="small"
+ accent={isRecording ? 'danger' : 'default'}
+ onClick={toggleDictation}
+ Icon={IconMicrophone}
+ ariaLabel={ariaLabel}
+ />
+ );
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/components/AiChatDictationEffect.tsx b/packages/twenty-front/src/modules/ai/dictation/components/AiChatDictationEffect.tsx
new file mode 100644
index 00000000000..d872724bc2a
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/components/AiChatDictationEffect.tsx
@@ -0,0 +1,124 @@
+import { useStore } from 'jotai';
+import { useCallback, useEffect, useMemo } from 'react';
+import { isDefined } from 'twenty-shared/utils';
+
+import { AGENT_CHAT_SEND_MESSAGE_EVENT_NAME } from '@/ai/constants/AgentChatSendMessageEventName';
+import { createWebSpeechDictationEngine } from '@/ai/dictation/engines/createWebSpeechDictationEngine';
+import { useDictationAvailability } from '@/ai/dictation/hooks/useDictationAvailability';
+import { dictationEngineState } from '@/ai/dictation/states/dictationEngineState';
+import { hasWebSpeechProvenSilentState } from '@/ai/dictation/states/hasWebSpeechProvenSilentState';
+import { isDictationRecordingState } from '@/ai/dictation/states/isDictationRecordingState';
+import { getDictationFailureMessage } from '@/ai/dictation/utils/getDictationFailureMessage';
+import { getDictationLanguage } from '@/ai/dictation/utils/getDictationLanguage';
+import { readDictationSurface } from '@/ai/dictation/utils/readDictationSurface';
+import { currentWorkspaceMemberState } from '@/auth/states/currentWorkspaceMemberState';
+import { useListenToBrowserEvent } from '@/browser-event/hooks/useListenToBrowserEvent';
+import { useSnackBar } from '@/ui/feedback/snack-bar-manager/hooks/useSnackBar';
+import { useAtomState } from '@/ui/utilities/state/jotai/hooks/useAtomState';
+import { useSetAtomState } from '@/ui/utilities/state/jotai/hooks/useSetAtomState';
+
+type AiChatDictationEffectProps = {
+ onInterimText: (text: string) => void;
+ onFinalText: (text: string) => void;
+};
+
+export const AiChatDictationEffect = ({
+ onInterimText,
+ onFinalText,
+}: AiChatDictationEffectProps) => {
+ const isSupported = useDictationAvailability();
+ const store = useStore();
+
+ const [dictationEngine, setDictationEngine] =
+ useAtomState(dictationEngineState);
+ const setIsDictationRecording = useSetAtomState(isDictationRecordingState);
+ const setHasWebSpeechProvenSilent = useSetAtomState(
+ hasWebSpeechProvenSilentState,
+ );
+ const { enqueueErrorSnackBar } = useSnackBar();
+
+ const { isIOS } = useMemo(() => readDictationSurface(), []);
+
+ useEffect(() => {
+ if (!isSupported) {
+ return;
+ }
+
+ const createdEngine = createWebSpeechDictationEngine({
+ isIOS,
+ // Read from the store rather than subscribed to, so a language change
+ // neither re-renders this nor rebuilds the engine; the next session
+ // picks it up.
+ getLanguage: () =>
+ getDictationLanguage(
+ store.get(currentWorkspaceMemberState.atom)?.locale,
+ ),
+ });
+
+ setDictationEngine(createdEngine);
+
+ return () => {
+ createdEngine.dispose();
+ setDictationEngine(null);
+ };
+ }, [isSupported, isIOS, store, setDictationEngine]);
+
+ // Separate from construction so fresh handler identities re-subscribe instead
+ // of tearing down a live recording.
+ useEffect(() => {
+ if (!isDefined(dictationEngine)) {
+ return;
+ }
+
+ return dictationEngine.subscribe((event) => {
+ switch (event.type) {
+ case 'interim':
+ onInterimText(event.text);
+ break;
+ case 'final':
+ onFinalText(event.text);
+ break;
+ case 'state':
+ setIsDictationRecording(event.state === 'recording');
+ // The session took its pending words with it, settled or not.
+ if (event.state === 'idle') {
+ onInterimText('');
+ }
+ break;
+ case 'error':
+ // Remembered only where a silent engine stays silent. A desktop
+ // browser that missed one start — a cold speech service, a blip
+ // reaching it — would otherwise lose the button for the life of the
+ // origin, with clearing site data the only way back.
+ if (event.reason === 'engine-silent' && isIOS) {
+ setHasWebSpeechProvenSilent(true);
+ }
+ enqueueErrorSnackBar({
+ message: getDictationFailureMessage(event.reason),
+ });
+ break;
+ }
+ });
+ }, [
+ dictationEngine,
+ isIOS,
+ onInterimText,
+ onFinalText,
+ setIsDictationRecording,
+ setHasWebSpeechProvenSilent,
+ enqueueErrorSnackBar,
+ ]);
+
+ // Both send paths dispatch this, so dictation does not have to be lifted into
+ // the composer to be stopped by one.
+ const handleSendMessage = useCallback(() => {
+ dictationEngine?.cancel();
+ }, [dictationEngine]);
+
+ useListenToBrowserEvent({
+ eventName: AGENT_CHAT_SEND_MESSAGE_EVENT_NAME,
+ onBrowserEvent: handleSendMessage,
+ });
+
+ return null;
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/components/AiChatDictationHint.tsx b/packages/twenty-front/src/modules/ai/dictation/components/AiChatDictationHint.tsx
new file mode 100644
index 00000000000..e02657383f6
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/components/AiChatDictationHint.tsx
@@ -0,0 +1,28 @@
+import { styled } from '@linaria/react';
+import { isNonEmptyString } from '@sniptt/guards';
+import { themeCssVariables } from 'twenty-ui/theme-constants';
+
+const StyledHint = styled.div`
+ color: ${themeCssVariables.font.color.light};
+ font-size: ${themeCssVariables.font.size.sm};
+ font-style: italic;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+`;
+
+type AiChatDictationHintProps = {
+ interimText: string;
+};
+
+export const AiChatDictationHint = ({
+ interimText,
+}: AiChatDictationHintProps) => {
+ if (!isNonEmptyString(interimText)) {
+ return null;
+ }
+
+ // Announced politely so a screen-reader user hears the recognition working
+ // without it interrupting whatever they are reading.
+ return <StyledHint aria-live="polite">{interimText}</StyledHint>;
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/components/__tests__/AiChatDictationEffect.test.tsx b/packages/twenty-front/src/modules/ai/dictation/components/__tests__/AiChatDictationEffect.test.tsx
new file mode 100644
index 00000000000..5b58cb4eedd
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/components/__tests__/AiChatDictationEffect.test.tsx
@@ -0,0 +1,70 @@
+import { act, render } from '@testing-library/react';
+import { getDefaultStore } from 'jotai';
+
+import { AiChatDictationEffect } from '@/ai/dictation/components/AiChatDictationEffect';
+import { dictationEngineState } from '@/ai/dictation/states/dictationEngineState';
+import { hasWebSpeechProvenSilentState } from '@/ai/dictation/states/hasWebSpeechProvenSilentState';
+import { type WebSpeechRecognitionConstructor } from '@/ai/dictation/types/WebSpeechRecognitionConstructor';
+
+type SpeechRecognitionTestWindow = {
+ SpeechRecognition?: WebSpeechRecognitionConstructor;
+};
+
+jest.mock('@/ui/feedback/snack-bar-manager/hooks/useSnackBar', () => ({
+ useSnackBar: () => ({ enqueueErrorSnackBar: jest.fn() }),
+}));
+
+const renderEffect = () =>
+ render(
+ <AiChatDictationEffect onInterimText={jest.fn()} onFinalText={jest.fn()} />,
+ );
+
+const readEngine = () => getDefaultStore().get(dictationEngineState.atom);
+
+describe('AiChatDictationEffect', () => {
+ beforeEach(() => {
+ localStorage.clear();
+ getDefaultStore().set(hasWebSpeechProvenSilentState.atom, false);
+ (window as SpeechRecognitionTestWindow).SpeechRecognition =
+ function SpeechRecognition() {} as unknown as WebSpeechRecognitionConstructor;
+ Object.defineProperty(navigator, 'mediaDevices', {
+ value: { getUserMedia: jest.fn() },
+ configurable: true,
+ });
+ Object.defineProperty(window, 'isSecureContext', {
+ value: true,
+ configurable: true,
+ });
+ });
+
+ afterEach(() => {
+ delete (window as SpeechRecognitionTestWindow).SpeechRecognition;
+ act(() => {
+ getDefaultStore().set(dictationEngineState.atom, null);
+ });
+ });
+
+ // The control renders on the engine's presence, so publishing it is what
+ // makes dictation appear at all.
+ it('publishes an engine on a surface that can dictate', () => {
+ renderEffect();
+
+ expect(readEngine()).not.toBeNull();
+ });
+
+ it('withdraws the engine when it unmounts', () => {
+ const { unmount } = renderEffect();
+
+ unmount();
+
+ expect(readEngine()).toBeNull();
+ });
+
+ it('publishes no engine on a browser with no speech recognition', () => {
+ delete (window as SpeechRecognitionTestWindow).SpeechRecognition;
+
+ renderEffect();
+
+ expect(readEngine()).toBeNull();
+ });
+});
diff --git a/packages/twenty-front/src/modules/ai/dictation/constants/DictationLivenessTimeoutInMs.ts b/packages/twenty-front/src/modules/ai/dictation/constants/DictationLivenessTimeoutInMs.ts
new file mode 100644
index 00000000000..398ad716234
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/constants/DictationLivenessTimeoutInMs.ts
@@ -0,0 +1,4 @@
+// Long enough that a slow engine start is not mistaken for a dead one, short
+// enough that a user on a surface where the API never emits is not left
+// talking to nothing.
+export const DICTATION_LIVENESS_TIMEOUT_IN_MS = 2500;
diff --git a/packages/twenty-front/src/modules/ai/dictation/engines/__tests__/dictationEngineLifecycle.test.ts b/packages/twenty-front/src/modules/ai/dictation/engines/__tests__/dictationEngineLifecycle.test.ts
new file mode 100644
index 00000000000..ad843a74003
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/engines/__tests__/dictationEngineLifecycle.test.ts
@@ -0,0 +1,358 @@
+import { createWebSpeechDictationEngine } from '@/ai/dictation/engines/createWebSpeechDictationEngine';
+import { type DictationEngineEvent } from '@/ai/dictation/types/DictationEngineEvent';
+import { type WebSpeechRecognitionConstructor } from '@/ai/dictation/types/WebSpeechRecognitionConstructor';
+import { type WebSpeechRecognitionEvent } from '@/ai/dictation/types/WebSpeechRecognitionEvent';
+import { type WebSpeechRecognitionInstance } from '@/ai/dictation/types/WebSpeechRecognitionInstance';
+
+// endSession is the test's stand-in for the recognizer reporting it finished,
+// which is the only thing that releases the started slot below.
+type FakeRecognition = WebSpeechRecognitionInstance & {
+ start: jest.Mock;
+ stop: jest.Mock;
+ abort: jest.Mock;
+ endSession: () => void;
+};
+
+type SpeechRecognitionTestWindow = {
+ SpeechRecognition?: WebSpeechRecognitionConstructor;
+};
+
+const createDeferred = <TValue>() => {
+ let resolve: (value: TValue) => void = () => {};
+ const promise = new Promise<TValue>((resolvePromise) => {
+ resolve = resolvePromise;
+ });
+
+ return { promise, resolve };
+};
+
+const createFakeStream = () => {
+ const stop = jest.fn();
+
+ return {
+ stream: { getTracks: () => [{ stop }] } as unknown as MediaStream,
+ stop,
+ };
+};
+
+const mockGetUserMedia = (implementation: () => Promise<MediaStream>) => {
+ Object.defineProperty(navigator, 'mediaDevices', {
+ value: { getUserMedia: jest.fn(implementation) },
+ configurable: true,
+ });
+};
+
+// Models the spec's [[started]] slot, so a test cannot assert a sequence a real
+// recognizer would refuse: start() throws while the previous session is still
+// started, and only the end event releases it.
+const stubSpeechRecognition = () => {
+ const instances: FakeRecognition[] = [];
+
+ (window as SpeechRecognitionTestWindow).SpeechRecognition =
+ function SpeechRecognition(this: FakeRecognition) {
+ let isStarted = false;
+
+ this.start = jest.fn(() => {
+ if (isStarted) {
+ throw new DOMException(
+ 'recognition has already started',
+ 'InvalidStateError',
+ );
+ }
+
+ isStarted = true;
+ });
+ this.stop = jest.fn();
+ this.abort = jest.fn();
+ this.endSession = () => {
+ isStarted = false;
+ this.onend?.();
+ };
+
+ instances.push(this);
+ } as unknown as WebSpeechRecognitionConstructor;
+
+ return instances;
+};
+
+const buildResultEvent = ({
+ transcript,
+ isFinal,
+}: {
+ transcript: string;
+ isFinal: boolean;
+}) =>
+ ({
+ resultIndex: 0,
+ results: [Object.assign([{ transcript }], { isFinal })],
+ }) as unknown as WebSpeechRecognitionEvent;
+
+describe('createWebSpeechDictationEngine', () => {
+ let instances: FakeRecognition[] = [];
+
+ const createTestEngine = ({
+ isIOS = false,
+ getLanguage = () => 'en-US',
+ }: { isIOS?: boolean; getLanguage?: () => string } = {}) =>
+ createWebSpeechDictationEngine({ isIOS, getLanguage });
+
+ const collectEvents = (engine: {
+ subscribe: (listener: (event: DictationEngineEvent) => void) => () => void;
+ }) => {
+ const events: DictationEngineEvent[] = [];
+
+ engine.subscribe((event) => events.push(event));
+
+ return events;
+ };
+
+ const readStates = (events: DictationEngineEvent[]) =>
+ events.flatMap((event) => (event.type === 'state' ? [event.state] : []));
+
+ beforeEach(() => {
+ const { stream } = createFakeStream();
+
+ mockGetUserMedia(() => Promise.resolve(stream));
+ instances = stubSpeechRecognition();
+ });
+
+ afterEach(() => {
+ jest.restoreAllMocks();
+ delete (window as SpeechRecognitionTestWindow).SpeechRecognition;
+ });
+
+ // getUserMedia resolves whenever the user answers the permission prompt, which
+ // can be long after the caller gave up. The engine has to notice.
+ it('does not start recognition when stopped during the microphone warm-up', async () => {
+ const deferred = createDeferred<MediaStream>();
+ const { stream } = createFakeStream();
+
+ mockGetUserMedia(() => deferred.promise);
+
+ const engine = createTestEngine({ isIOS: true });
+ const startPromise = engine.start();
+
+ engine.stop();
+ deferred.resolve(stream);
+ await startPromise;
+
+ expect(instances).toHaveLength(0);
+ });
+
+ it('releases a microphone that arrives after the engine was disposed', async () => {
+ const deferred = createDeferred<MediaStream>();
+ const { stream, stop } = createFakeStream();
+
+ mockGetUserMedia(() => deferred.promise);
+
+ const engine = createTestEngine({ isIOS: true });
+ const startPromise = engine.start();
+
+ engine.dispose();
+ deferred.resolve(stream);
+ await startPromise;
+
+ expect(stop).toHaveBeenCalledTimes(1);
+ expect(instances).toHaveLength(0);
+ });
+
+ it('starts recognition when the warm-up completes uninterrupted', async () => {
+ const engine = createTestEngine({ isIOS: true });
+
+ await engine.start();
+
+ expect(instances[0]?.start).toHaveBeenCalledTimes(1);
+ });
+
+ // A result that settles an utterance carries no interim for it, so without an
+ // explicit clear the hint keeps showing words already inserted below it.
+ it('clears the interim hint when an utterance settles', async () => {
+ const engine = createTestEngine();
+ const events = collectEvents(engine);
+
+ await engine.start();
+
+ instances[0]?.onresult?.(
+ buildResultEvent({ transcript: 'hello there', isFinal: true }),
+ );
+
+ expect(events).toContainEqual({ type: 'final', text: 'hello there' });
+ expect(events).toContainEqual({ type: 'interim', text: '' });
+ });
+
+ // Sending takes the composer's content with it, so a half-heard utterance
+ // belongs to neither the sent message nor the next draft.
+ it('discards in-flight audio on cancel without delivering a result', async () => {
+ const engine = createTestEngine();
+
+ await engine.start();
+ engine.cancel();
+
+ expect(instances[0]?.abort).toHaveBeenCalledTimes(1);
+ });
+
+ // Re-instantiating per press is what produces the iOS system chime and the
+ // first-attempt failures, so a recognizer that finished is used again.
+ it('reuses the recognizer once it has reported the session ended', async () => {
+ const engine = createTestEngine({ isIOS: true });
+
+ await engine.start();
+ engine.stop();
+ instances[0]?.endSession();
+
+ await engine.start();
+
+ expect(instances).toHaveLength(1);
+ expect(instances[0]?.start).toHaveBeenCalledTimes(2);
+ });
+
+ // iOS can end a session without firing onend, and a recognizer that never
+ // reported its end throws InvalidStateError on the next start().
+ it('replaces a recognizer that never reported the session ended', async () => {
+ const engine = createTestEngine({ isIOS: true });
+ const events = collectEvents(engine);
+
+ await engine.start();
+ engine.stop();
+
+ // Deliberately no end event: this is the platform behaviour being guarded.
+ await engine.start();
+
+ expect(instances).toHaveLength(2);
+ expect(instances[1]?.start).toHaveBeenCalledTimes(1);
+ expect(events).not.toContainEqual({
+ type: 'error',
+ reason: 'engine-error',
+ });
+ });
+
+ // The caller only starts again from 'idle', so a state left at 'recording'
+ // wedges the button into offering to stop a session that is already over.
+ it.each(['stop', 'cancel'] as const)(
+ 'reports idle on %s even when onend never fires',
+ async (method) => {
+ const engine = createTestEngine({ isIOS: true });
+ const events = collectEvents(engine);
+
+ await engine.start();
+ engine[method]();
+
+ expect(readStates(events).at(-1)).toBe('idle');
+ },
+ );
+
+ // The listener must not outlive its session: onend is what normally removes
+ // it, and iOS can end a session without firing onend.
+ it.each(['stop', 'cancel'] as const)(
+ 'removes the visibility listener on %s even when onend never fires',
+ async (method) => {
+ const removeEventListener = jest.spyOn(document, 'removeEventListener');
+ const engine = createTestEngine({ isIOS: true });
+
+ await engine.start();
+ engine[method]();
+
+ expect(removeEventListener).toHaveBeenCalledWith(
+ 'visibilitychange',
+ expect.any(Function),
+ );
+ },
+ );
+
+ // A session ends once. onend arriving after an explicit stop must not report
+ // a second one, or a caller counting session ends sees two per session.
+ it('reports idle once when stop is followed by onend', async () => {
+ const engine = createTestEngine();
+ const events = collectEvents(engine);
+
+ await engine.start();
+ engine.stop();
+ instances[0]?.endSession();
+
+ expect(readStates(events).filter((state) => state === 'idle')).toHaveLength(
+ 1,
+ );
+ });
+
+ // Every message send cancels, dictating or not, so cancelling an idle engine
+ // is the common case rather than an edge one.
+ it('does nothing when cancelling an engine that is not dictating', () => {
+ const engine = createTestEngine();
+ const events = collectEvents(engine);
+
+ engine.cancel();
+
+ expect(instances).toHaveLength(0);
+ expect(events).toEqual([]);
+ });
+
+ // stop() clears the session eagerly but the recognizer can still be settling.
+ // A send in that window must abort it, or its last final result is inserted
+ // into the composer the send just cleared.
+ it('still aborts a settling recognizer when cancelled after stop', async () => {
+ const engine = createTestEngine();
+
+ await engine.start();
+ engine.stop();
+ engine.cancel();
+
+ expect(instances[0]?.abort).toHaveBeenCalledTimes(1);
+ });
+
+ // An error ends the session, and iOS can skip the end event that follows it.
+ it('reports the failure and ends the session on a recognizer error', async () => {
+ const engine = createTestEngine({ isIOS: true });
+ const events = collectEvents(engine);
+
+ await engine.start();
+ instances[0]?.onerror?.({ error: 'audio-capture' });
+
+ expect(events).toContainEqual({ type: 'error', reason: 'no-device' });
+ expect(readStates(events).at(-1)).toBe('idle');
+ });
+
+ // The API reads lang at start(), so a speaker who changes their language mid
+ // session keeps that session and gets the new one on their next press —
+ // rebuilding the engine to apply it would abort what they are saying.
+ it('reads the language at the start of each session', async () => {
+ const languages = ['en-US', 'fr-FR'];
+ const engine = createTestEngine({
+ getLanguage: () => languages.shift() ?? 'en-US',
+ });
+
+ await engine.start();
+
+ expect(instances[0]?.lang).toBe('en-US');
+
+ engine.stop();
+ instances[0]?.endSession();
+
+ await engine.start();
+
+ expect(instances).toHaveLength(1);
+ expect(instances[0]?.lang).toBe('fr-FR');
+ });
+
+ // The end event of a session that is already over must not abandon a press
+ // that is still warming up its microphone, or that press is silently lost.
+ it('keeps a start warming up when a previous session finally reports its end', async () => {
+ const engine = createTestEngine();
+
+ await engine.start();
+ engine.stop();
+
+ const deferred = createDeferred<MediaStream>();
+ const { stream } = createFakeStream();
+
+ mockGetUserMedia(() => deferred.promise);
+
+ const startPromise = engine.start();
+
+ instances[0]?.endSession();
+ deferred.resolve(stream);
+ await startPromise;
+
+ expect(instances).toHaveLength(1);
+ expect(instances[0]?.start).toHaveBeenCalledTimes(2);
+ });
+});
diff --git a/packages/twenty-front/src/modules/ai/dictation/engines/createWebSpeechDictationEngine.ts b/packages/twenty-front/src/modules/ai/dictation/engines/createWebSpeechDictationEngine.ts
new file mode 100644
index 00000000000..28e424e5349
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/engines/createWebSpeechDictationEngine.ts
@@ -0,0 +1,291 @@
+import { isNonEmptyString } from '@sniptt/guards';
+import { isDefined } from 'twenty-shared/utils';
+
+import { DICTATION_LIVENESS_TIMEOUT_IN_MS } from '@/ai/dictation/constants/DictationLivenessTimeoutInMs';
+import { type DictationEngine } from '@/ai/dictation/types/DictationEngine';
+import { type DictationFailureReason } from '@/ai/dictation/types/DictationFailureReason';
+import { type WebSpeechRecognitionErrorEvent } from '@/ai/dictation/types/WebSpeechRecognitionErrorEvent';
+import { type WebSpeechRecognitionEvent } from '@/ai/dictation/types/WebSpeechRecognitionEvent';
+import { type WebSpeechRecognitionInstance } from '@/ai/dictation/types/WebSpeechRecognitionInstance';
+import { createDictationEventEmitter } from '@/ai/dictation/utils/createDictationEventEmitter';
+import { createLivenessWatchdog } from '@/ai/dictation/utils/createLivenessWatchdog';
+import { getSpeechRecognitionConstructor } from '@/ai/dictation/utils/getSpeechRecognitionConstructor';
+import { mapMediaDeviceError } from '@/ai/dictation/utils/mapMediaDeviceError';
+import { mapSpeechRecognitionError } from '@/ai/dictation/utils/mapSpeechRecognitionError';
+import { unlockAudioContext } from '@/ai/dictation/utils/unlockAudioContext';
+import { warmUpMicrophone } from '@/ai/dictation/utils/warmUpMicrophone';
+
+const readTranscripts = (event: WebSpeechRecognitionEvent) => {
+ let finalText = '';
+ let interimText = '';
+
+ for (let index = event.resultIndex; index < event.results.length; index++) {
+ const result = event.results[index];
+ const transcript = result[0]?.transcript ?? '';
+
+ if (result.isFinal) {
+ finalText += transcript;
+ } else {
+ interimText += transcript;
+ }
+ }
+
+ return { finalText, interimText };
+};
+
+export const createWebSpeechDictationEngine = ({
+ isIOS,
+ getLanguage,
+}: {
+ isIOS: boolean;
+ getLanguage: () => string;
+}): DictationEngine => {
+ const emitter = createDictationEventEmitter();
+
+ // Reused for the engine's lifetime: re-instantiating per press produces the
+ // iOS system chime and the first-attempt failures.
+ let recognition: WebSpeechRecognitionInstance | null = null;
+ let isActive = false;
+ // The recognizer's own started flag outlives the session the UI sees: stop()
+ // and abort() only release it when the recognizer reports the session ended,
+ // and start() throws InvalidStateError until then.
+ let isRecognizerRunning = false;
+ // A stop issued during the microphone warm-up has nothing to stop yet, so the
+ // generation is what lets the resumed startup notice it was abandoned.
+ let sessionGeneration = 0;
+
+ const watchdog = createLivenessWatchdog({
+ timeoutInMs: DICTATION_LIVENESS_TIMEOUT_IN_MS,
+ onSilent: () => {
+ emitter.emit({ type: 'error', reason: 'engine-silent' });
+ stopRecognition();
+ },
+ });
+
+ // An abandoned recognizer must not report into the session that replaces it.
+ const discardRecognition = () => {
+ if (isDefined(recognition)) {
+ recognition.onaudiostart = null;
+ recognition.onresult = null;
+ recognition.onerror = null;
+ recognition.onend = null;
+ }
+
+ recognition = null;
+ isRecognizerRunning = false;
+ };
+
+ // Announces that the session is over and undoes what start() set up. Every
+ // ending funnels through here so it cannot drift between callers and cannot
+ // run twice, and onend is
+ // deliberately not trusted to arrive — iOS can end a session without firing
+ // it, and leaving any of this to it wedges dictation. A stuck isActive
+ // refuses every later start, a state left at 'recording' leaves the button
+ // offering to stop a session that is already over, and a listener outliving
+ // its session calls back into a stopped engine.
+ const endSession = ({
+ evenWhenIdle = false,
+ }: { evenWhenIdle?: boolean } = {}) => {
+ if (!isActive && !evenWhenIdle) {
+ return;
+ }
+
+ isActive = false;
+ watchdog.disarm();
+ document.removeEventListener('visibilitychange', handleVisibilityChange);
+
+ emitter.emit({ type: 'state', state: 'idle' });
+ };
+
+ // Asked to end the session, rather than told it ended. The recognizer is told
+ // even when the session already reads as over: stop() clears isActive eagerly
+ // but the recognizer can still be settling and deliver one last final result,
+ // so a cancel arriving in that window has to abort it — otherwise that text
+ // lands in a composer the send just cleared. Ending a session that was never
+ // told to stop (onend, onerror) must not bump the generation, or a recognizer
+ // reporting a previous session would abandon the start already warming up.
+ const requestSessionEnd = (
+ recognitionAction: 'stop' | 'abort',
+ { evenWhenIdle = false }: { evenWhenIdle?: boolean } = {},
+ ) => {
+ sessionGeneration++;
+
+ // A no-op on a recognizer that is not running.
+ if (isDefined(recognition)) {
+ recognition[recognitionAction]();
+ }
+
+ endSession({ evenWhenIdle });
+ };
+
+ const stopRecognition = () => {
+ requestSessionEnd('stop');
+ };
+
+ const handleVisibilityChange = () => {
+ // A session that survives backgrounding on iOS only recovers on reload.
+ if (document.visibilityState === 'hidden') {
+ stopRecognition();
+ }
+ };
+
+ const buildRecognition = (): WebSpeechRecognitionInstance | null => {
+ const SpeechRecognitionConstructor = getSpeechRecognitionConstructor();
+
+ if (!isDefined(SpeechRecognitionConstructor)) {
+ return null;
+ }
+
+ const instance = new SpeechRecognitionConstructor();
+
+ // Continuous mode never releases the iOS microphone and never delivers a
+ // result.
+ instance.continuous = !isIOS;
+ instance.interimResults = true;
+
+ instance.onaudiostart = () => {
+ watchdog.noteActivity();
+ };
+
+ instance.onresult = (event: WebSpeechRecognitionEvent) => {
+ watchdog.noteActivity();
+
+ const { finalText, interimText } = readTranscripts(event);
+
+ if (isNonEmptyString(finalText)) {
+ emitter.emit({ type: 'final', text: finalText });
+ }
+
+ // Emitted even when empty: the result that settles an utterance carries
+ // no interim for it, so the hint would keep showing words that are
+ // already in the document.
+ emitter.emit({ type: 'interim', text: interimText });
+ };
+
+ instance.onerror = (event: WebSpeechRecognitionErrorEvent) => {
+ const reason = mapSpeechRecognitionError(event.error);
+
+ if (isDefined(reason)) {
+ emitter.emit({ type: 'error', reason });
+ }
+
+ // An error terminates the session — the spec fires end after it — but the
+ // WebKit surfaces this engine is written around can skip that, and waiting
+ // for it would leave the button offering to stop a session that is over.
+ // isRecognizerRunning deliberately stays set: only onend proves the
+ // recognizer released itself, so the next start replaces it instead.
+ endSession();
+ };
+
+ instance.onend = () => {
+ isRecognizerRunning = false;
+ endSession();
+ };
+
+ return instance;
+ };
+
+ // A press that never reached the recognizer still has to return the button to
+ // idle, and there is nothing yet to tear down when it does.
+ const abandonStartup = (reason?: DictationFailureReason) => {
+ if (isDefined(reason)) {
+ emitter.emit({ type: 'error', reason });
+ }
+
+ emitter.emit({ type: 'state', state: 'idle' });
+ };
+
+ return {
+ start: async () => {
+ if (isActive) {
+ return;
+ }
+
+ const generation = ++sessionGeneration;
+ const isAbandoned = () => generation !== sessionGeneration;
+
+ emitter.emit({ type: 'state', state: 'recording' });
+
+ try {
+ await warmUpMicrophone();
+ } catch (error) {
+ abandonStartup(mapMediaDeviceError(error));
+
+ return;
+ }
+
+ if (isAbandoned()) {
+ abandonStartup();
+
+ return;
+ }
+
+ // iOS only: a context created outside a user gesture is suspended there,
+ // and a suspended one blocks the capture path recognition runs on.
+ // Everywhere else it is a create/resume/close the press pays for nothing.
+ if (isIOS) {
+ await unlockAudioContext();
+
+ if (isAbandoned()) {
+ abandonStartup();
+
+ return;
+ }
+ }
+
+ // A recognizer that never reported its session ended cannot be started
+ // again, so a press inside that window gets a fresh one rather than an
+ // InvalidStateError.
+ if (isRecognizerRunning) {
+ discardRecognition();
+ }
+
+ recognition = recognition ?? buildRecognition();
+
+ if (!isDefined(recognition)) {
+ abandonStartup('unsupported-surface');
+
+ return;
+ }
+
+ // Read per session rather than per engine: the API takes lang at start(),
+ // so a speaker who changes their language does not need the engine torn
+ // down and rebuilt — and a session in flight is not aborted to apply it.
+ recognition.lang = getLanguage();
+
+ isActive = true;
+ document.addEventListener('visibilitychange', handleVisibilityChange);
+ watchdog.arm();
+
+ try {
+ recognition.start();
+ } catch {
+ emitter.emit({ type: 'error', reason: 'engine-error' });
+ endSession();
+
+ return;
+ }
+
+ isRecognizerRunning = true;
+ },
+
+ stop: stopRecognition,
+
+ // A send takes the composer's content with it, so a half-heard utterance
+ // belongs to neither the sent message nor the next draft. abort() ends the
+ // session without delivering a result, unlike stop().
+ cancel: () => {
+ requestSessionEnd('abort');
+ },
+
+ dispose: () => {
+ // evenWhenIdle because disposal has to release the recognizer and let a
+ // caller holding interim text clear it whether or not a session was live.
+ requestSessionEnd('abort', { evenWhenIdle: true });
+ discardRecognition();
+ emitter.clear();
+ },
+
+ subscribe: emitter.subscribe,
+ };
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/hooks/__tests__/useDictationAvailability.test.tsx b/packages/twenty-front/src/modules/ai/dictation/hooks/__tests__/useDictationAvailability.test.tsx
new file mode 100644
index 00000000000..de71992a64a
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/hooks/__tests__/useDictationAvailability.test.tsx
@@ -0,0 +1,67 @@
+import { act, renderHook } from '@testing-library/react';
+import { getDefaultStore } from 'jotai';
+
+import { useDictationAvailability } from '@/ai/dictation/hooks/useDictationAvailability';
+import { hasWebSpeechProvenSilentState } from '@/ai/dictation/states/hasWebSpeechProvenSilentState';
+import { type WebSpeechRecognitionConstructor } from '@/ai/dictation/types/WebSpeechRecognitionConstructor';
+import { useSetAtomState } from '@/ui/utilities/state/jotai/hooks/useSetAtomState';
+
+type SpeechRecognitionTestWindow = {
+ SpeechRecognition?: WebSpeechRecognitionConstructor;
+};
+
+const renderAvailability = () =>
+ renderHook(() => ({
+ isAvailable: useDictationAvailability(),
+ setHasWebSpeechProvenSilent: useSetAtomState(hasWebSpeechProvenSilentState),
+ }));
+
+describe('useDictationAvailability', () => {
+ beforeEach(() => {
+ localStorage.clear();
+ getDefaultStore().set(hasWebSpeechProvenSilentState.atom, false);
+ // SpeechRecognition is absent from the DOM lib because it never became a
+ // standard, so the global is reached through the same structural type the
+ // engine declares.
+ (window as unknown as SpeechRecognitionTestWindow).SpeechRecognition =
+ function SpeechRecognition() {} as unknown as WebSpeechRecognitionConstructor;
+ Object.defineProperty(navigator, 'mediaDevices', {
+ value: { getUserMedia: jest.fn() },
+ configurable: true,
+ });
+ Object.defineProperty(window, 'isSecureContext', {
+ value: true,
+ configurable: true,
+ });
+ });
+
+ afterEach(() => {
+ delete (window as unknown as SpeechRecognitionTestWindow).SpeechRecognition;
+ });
+
+ it('offers dictation on a browser with a speech engine', () => {
+ const { result } = renderAvailability();
+
+ expect(result.current.isAvailable).toBe(true);
+ });
+
+ it('refuses when the browser has no speech engine', () => {
+ delete (window as unknown as SpeechRecognitionTestWindow).SpeechRecognition;
+
+ const { result } = renderAvailability();
+
+ expect(result.current.isAvailable).toBe(false);
+ });
+
+ // Offering the same dead button again only costs the user another recording,
+ // and waiting for a remount to hide it costs one more.
+ it('withdraws dictation the moment the engine proves itself silent', () => {
+ const { result } = renderAvailability();
+
+ act(() => {
+ result.current.setHasWebSpeechProvenSilent(true);
+ });
+
+ expect(result.current.isAvailable).toBe(false);
+ });
+});
diff --git a/packages/twenty-front/src/modules/ai/dictation/hooks/__tests__/useInsertDictatedText.test.ts b/packages/twenty-front/src/modules/ai/dictation/hooks/__tests__/useInsertDictatedText.test.ts
new file mode 100644
index 00000000000..a70294e544f
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/hooks/__tests__/useInsertDictatedText.test.ts
@@ -0,0 +1,58 @@
+import { renderHook } from '@testing-library/react';
+import { Editor } from '@tiptap/core';
+import { Bold } from '@tiptap/extension-bold';
+import { Document } from '@tiptap/extension-document';
+import { Italic } from '@tiptap/extension-italic';
+import { Paragraph } from '@tiptap/extension-paragraph';
+import { Text } from '@tiptap/extension-text';
+
+import { useInsertDictatedText } from '@/ai/dictation/hooks/useInsertDictatedText';
+
+const renderInsert = (editor: Editor | null) =>
+ renderHook(() => useInsertDictatedText(editor)).result.current;
+
+describe('useInsertDictatedText', () => {
+ let editor: Editor;
+
+ beforeEach(() => {
+ // The composer's schema carries marks, which is what makes a bare string
+ // insertion parse as HTML rather than land literally.
+ editor = new Editor({
+ extensions: [Document, Paragraph, Text, Bold, Italic],
+ content: '<p></p>',
+ });
+ });
+
+ afterEach(() => {
+ editor?.destroy();
+ });
+
+ it('should write what was said rather than parsing it as markup', () => {
+ renderInsert(editor)('wrap it in <b>bold</b> and AT&T');
+
+ expect(editor.getText()).toBe('wrap it in <b>bold</b> and AT&T');
+ });
+
+ it('should separate an utterance from the words already there', () => {
+ const insert = renderInsert(editor);
+
+ insert('hello');
+ insert('world');
+
+ expect(editor.getText()).toBe('hello world');
+ });
+
+ it('should not open an empty composer with a space', () => {
+ renderInsert(editor)('hello');
+
+ expect(editor.getText()).toBe('hello');
+ });
+
+ it('should not double the space the speaker already left', () => {
+ editor.commands.insertContent('hello ');
+
+ renderInsert(editor)('world');
+
+ expect(editor.getText()).toBe('hello world');
+ });
+});
diff --git a/packages/twenty-front/src/modules/ai/dictation/hooks/useDictation.ts b/packages/twenty-front/src/modules/ai/dictation/hooks/useDictation.ts
new file mode 100644
index 00000000000..eaeb57a4331
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/hooks/useDictation.ts
@@ -0,0 +1,33 @@
+import { useCallback } from 'react';
+import { isDefined } from 'twenty-shared/utils';
+
+import { dictationEngineState } from '@/ai/dictation/states/dictationEngineState';
+import { isDictationRecordingState } from '@/ai/dictation/states/isDictationRecordingState';
+import { useAtomStateValue } from '@/ui/utilities/state/jotai/hooks/useAtomStateValue';
+
+// The engine's lifecycle belongs to AiChatDictationEffect; this only reads what
+// it published and drives it.
+export const useDictation = () => {
+ const dictationEngine = useAtomStateValue(dictationEngineState);
+ const isDictationRecording = useAtomStateValue(isDictationRecordingState);
+
+ const toggleDictation = useCallback(() => {
+ if (!isDefined(dictationEngine)) {
+ return;
+ }
+
+ if (isDictationRecording) {
+ dictationEngine.stop();
+
+ return;
+ }
+
+ void dictationEngine.start();
+ }, [dictationEngine, isDictationRecording]);
+
+ return {
+ isAvailable: isDefined(dictationEngine),
+ isRecording: isDictationRecording,
+ toggleDictation,
+ };
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/hooks/useDictationAvailability.ts b/packages/twenty-front/src/modules/ai/dictation/hooks/useDictationAvailability.ts
new file mode 100644
index 00000000000..6e96b7d372b
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/hooks/useDictationAvailability.ts
@@ -0,0 +1,21 @@
+import { useMemo } from 'react';
+
+import { hasWebSpeechProvenSilentState } from '@/ai/dictation/states/hasWebSpeechProvenSilentState';
+import { readDictationSurface } from '@/ai/dictation/utils/readDictationSurface';
+import { resolveDictationAvailability } from '@/ai/dictation/utils/resolveDictationAvailability';
+import { useAtomStateValue } from '@/ui/utilities/state/jotai/hooks/useAtomStateValue';
+
+export const useDictationAvailability = (): boolean => {
+ const hasWebSpeechProvenSilent = useAtomStateValue(
+ hasWebSpeechProvenSilentState,
+ );
+
+ // Every field the surface reports is fixed for the life of the page; the
+ // remembered failure is the only part of availability that moves.
+ const isSurfaceCapable = useMemo(
+ () => resolveDictationAvailability(readDictationSurface()),
+ [],
+ );
+
+ return isSurfaceCapable && !hasWebSpeechProvenSilent;
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/hooks/useInsertDictatedText.ts b/packages/twenty-front/src/modules/ai/dictation/hooks/useInsertDictatedText.ts
new file mode 100644
index 00000000000..4020d548d41
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/hooks/useInsertDictatedText.ts
@@ -0,0 +1,39 @@
+import { isNonEmptyString } from '@sniptt/guards';
+import { type Editor } from '@tiptap/react';
+import { useCallback } from 'react';
+import { isDefined } from 'twenty-shared/utils';
+
+// Only settled text is written to the document. Interim results are shown
+// beside the composer instead, because tracking a replaceable range inside
+// ProseMirror breaks as soon as the user edits while dictating — and they do,
+// since the composer stays focused throughout.
+export const useInsertDictatedText = (editor: Editor | null) =>
+ useCallback(
+ (text: string) => {
+ if (!isDefined(editor) || !isNonEmptyString(text)) {
+ return;
+ }
+
+ const { from } = editor.state.selection;
+ // A bare string is parsed as HTML against the editor's schema, so a
+ // transcript containing "<b>" loses the tag and gains a mark. A text node
+ // writes what was actually said.
+ const precedingCharacter = editor.state.doc.textBetween(
+ Math.max(from - 1, 0),
+ from,
+ );
+ // Neither engine prefixes a space, and every press is a fresh utterance.
+ const needsSeparator =
+ isNonEmptyString(precedingCharacter) && !/\s/.test(precedingCharacter);
+
+ editor
+ .chain()
+ .focus()
+ .insertContent({
+ type: 'text',
+ text: needsSeparator ? ` ${text}` : text,
+ })
+ .run();
+ },
+ [editor],
+ );
diff --git a/packages/twenty-front/src/modules/ai/dictation/states/dictationEngineState.ts b/packages/twenty-front/src/modules/ai/dictation/states/dictationEngineState.ts
new file mode 100644
index 00000000000..30e50d5d6bf
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/states/dictationEngineState.ts
@@ -0,0 +1,9 @@
+import { type DictationEngine } from '@/ai/dictation/types/DictationEngine';
+import { createAtomState } from '@/ui/utilities/state/jotai/utils/createAtomState';
+
+// Only set while a surface can dictate, so its presence is what the control
+// reads to decide whether to render at all.
+export const dictationEngineState = createAtomState<DictationEngine | null>({
+ key: 'ai/dictationEngine',
+ defaultValue: null,
+});
diff --git a/packages/twenty-front/src/modules/ai/dictation/states/hasWebSpeechProvenSilentState.ts b/packages/twenty-front/src/modules/ai/dictation/states/hasWebSpeechProvenSilentState.ts
new file mode 100644
index 00000000000..24f0414af78
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/states/hasWebSpeechProvenSilentState.ts
@@ -0,0 +1,11 @@
+import { createAtomState } from '@/ui/utilities/state/jotai/utils/createAtomState';
+
+// Remembered per browser because a silent engine is a property of this WebView
+// rather than of the workspace or the user: once one has accepted start() and
+// then said nothing, offering the button again only costs another recording.
+export const hasWebSpeechProvenSilentState = createAtomState<boolean>({
+ key: 'ai/hasWebSpeechProvenSilent',
+ defaultValue: false,
+ useLocalStorage: true,
+ localStorageOptions: { getOnInit: true },
+});
diff --git a/packages/twenty-front/src/modules/ai/dictation/states/isDictationRecordingState.ts b/packages/twenty-front/src/modules/ai/dictation/states/isDictationRecordingState.ts
new file mode 100644
index 00000000000..394c823c0fc
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/states/isDictationRecordingState.ts
@@ -0,0 +1,6 @@
+import { createAtomState } from '@/ui/utilities/state/jotai/utils/createAtomState';
+
+export const isDictationRecordingState = createAtomState<boolean>({
+ key: 'ai/isDictationRecording',
+ defaultValue: false,
+});
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/DictationEngine.ts b/packages/twenty-front/src/modules/ai/dictation/types/DictationEngine.ts
new file mode 100644
index 00000000000..4cd1b17203b
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/DictationEngine.ts
@@ -0,0 +1,9 @@
+import { type DictationEngineListener } from '@/ai/dictation/types/DictationEngineListener';
+
+export type DictationEngine = {
+ start: () => Promise<void>;
+ stop: () => void;
+ cancel: () => void;
+ dispose: () => void;
+ subscribe: (listener: DictationEngineListener) => () => void;
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/DictationEngineEvent.ts b/packages/twenty-front/src/modules/ai/dictation/types/DictationEngineEvent.ts
new file mode 100644
index 00000000000..e548dbcc01d
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/DictationEngineEvent.ts
@@ -0,0 +1,8 @@
+import { type DictationEngineState } from '@/ai/dictation/types/DictationEngineState';
+import { type DictationFailureReason } from '@/ai/dictation/types/DictationFailureReason';
+
+export type DictationEngineEvent =
+ | { type: 'interim'; text: string }
+ | { type: 'final'; text: string }
+ | { type: 'state'; state: DictationEngineState }
+ | { type: 'error'; reason: DictationFailureReason };
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/DictationEngineListener.ts b/packages/twenty-front/src/modules/ai/dictation/types/DictationEngineListener.ts
new file mode 100644
index 00000000000..c111bfda00c
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/DictationEngineListener.ts
@@ -0,0 +1,3 @@
+import { type DictationEngineEvent } from '@/ai/dictation/types/DictationEngineEvent';
+
+export type DictationEngineListener = (event: DictationEngineEvent) => void;
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/DictationEngineState.ts b/packages/twenty-front/src/modules/ai/dictation/types/DictationEngineState.ts
new file mode 100644
index 00000000000..abb3870b8b0
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/DictationEngineState.ts
@@ -0,0 +1 @@
+export type DictationEngineState = 'idle' | 'recording';
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/DictationEventEmitter.ts b/packages/twenty-front/src/modules/ai/dictation/types/DictationEventEmitter.ts
new file mode 100644
index 00000000000..d5c00dc0878
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/DictationEventEmitter.ts
@@ -0,0 +1,8 @@
+import { type DictationEngineEvent } from '@/ai/dictation/types/DictationEngineEvent';
+import { type DictationEngineListener } from '@/ai/dictation/types/DictationEngineListener';
+
+export type DictationEventEmitter = {
+ subscribe: (listener: DictationEngineListener) => () => void;
+ emit: (event: DictationEngineEvent) => void;
+ clear: () => void;
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/DictationFailureReason.ts b/packages/twenty-front/src/modules/ai/dictation/types/DictationFailureReason.ts
new file mode 100644
index 00000000000..5612cce9bcc
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/DictationFailureReason.ts
@@ -0,0 +1,9 @@
+export type DictationFailureReason =
+ | 'permission-denied'
+ | 'no-device'
+ | 'unsupported-surface'
+ // iOS exposes webkitSpeechRecognition in contexts where it never emits, so
+ // feature detection reports success while dictation does nothing.
+ | 'engine-silent'
+ | 'network'
+ | 'engine-error';
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/DictationSurface.ts b/packages/twenty-front/src/modules/ai/dictation/types/DictationSurface.ts
new file mode 100644
index 00000000000..3795165b75b
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/DictationSurface.ts
@@ -0,0 +1,8 @@
+export type DictationSurface = {
+ isIOS: boolean;
+ isStandaloneDisplayMode: boolean;
+ isThirdPartyIOSBrowser: boolean;
+ hasSpeechRecognition: boolean;
+ hasMediaDevices: boolean;
+ isSecureContext: boolean;
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/LivenessWatchdog.ts b/packages/twenty-front/src/modules/ai/dictation/types/LivenessWatchdog.ts
new file mode 100644
index 00000000000..84482f84721
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/LivenessWatchdog.ts
@@ -0,0 +1,5 @@
+export type LivenessWatchdog = {
+ arm: () => void;
+ noteActivity: () => void;
+ disarm: () => void;
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionAlternative.ts b/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionAlternative.ts
new file mode 100644
index 00000000000..98da32c45ff
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionAlternative.ts
@@ -0,0 +1,3 @@
+export type WebSpeechRecognitionAlternative = {
+ transcript: string;
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionConstructor.ts b/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionConstructor.ts
new file mode 100644
index 00000000000..1a49cc9a6d0
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionConstructor.ts
@@ -0,0 +1,4 @@
+import { type WebSpeechRecognitionInstance } from '@/ai/dictation/types/WebSpeechRecognitionInstance';
+
+export type WebSpeechRecognitionConstructor =
+ new () => WebSpeechRecognitionInstance;
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionErrorEvent.ts b/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionErrorEvent.ts
new file mode 100644
index 00000000000..59378a898b6
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionErrorEvent.ts
@@ -0,0 +1,3 @@
+export type WebSpeechRecognitionErrorEvent = {
+ error: string;
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionEvent.ts b/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionEvent.ts
new file mode 100644
index 00000000000..ff787b207e4
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionEvent.ts
@@ -0,0 +1,6 @@
+import { type WebSpeechRecognitionResultList } from '@/ai/dictation/types/WebSpeechRecognitionResultList';
+
+export type WebSpeechRecognitionEvent = {
+ resultIndex: number;
+ results: WebSpeechRecognitionResultList;
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionInstance.ts b/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionInstance.ts
new file mode 100644
index 00000000000..22011bad84a
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionInstance.ts
@@ -0,0 +1,17 @@
+import { type WebSpeechRecognitionErrorEvent } from '@/ai/dictation/types/WebSpeechRecognitionErrorEvent';
+import { type WebSpeechRecognitionEvent } from '@/ai/dictation/types/WebSpeechRecognitionEvent';
+
+// The Web Speech API is not in TypeScript's DOM lib because it never became a
+// standard, so the parts this engine touches are declared structurally.
+export type WebSpeechRecognitionInstance = {
+ continuous: boolean;
+ interimResults: boolean;
+ lang: string;
+ start: () => void;
+ stop: () => void;
+ abort: () => void;
+ onaudiostart: (() => void) | null;
+ onresult: ((event: WebSpeechRecognitionEvent) => void) | null;
+ onerror: ((event: WebSpeechRecognitionErrorEvent) => void) | null;
+ onend: (() => void) | null;
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionResult.ts b/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionResult.ts
new file mode 100644
index 00000000000..4f43f870d7c
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionResult.ts
@@ -0,0 +1,6 @@
+import { type WebSpeechRecognitionAlternative } from '@/ai/dictation/types/WebSpeechRecognitionAlternative';
+
+export type WebSpeechRecognitionResult = {
+ isFinal: boolean;
+ [index: number]: WebSpeechRecognitionAlternative;
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionResultList.ts b/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionResultList.ts
new file mode 100644
index 00000000000..56c5658c5dd
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/types/WebSpeechRecognitionResultList.ts
@@ -0,0 +1,6 @@
+import { type WebSpeechRecognitionResult } from '@/ai/dictation/types/WebSpeechRecognitionResult';
+
+export type WebSpeechRecognitionResultList = {
+ length: number;
+ [index: number]: WebSpeechRecognitionResult;
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/createDictationEventEmitter.test.ts b/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/createDictationEventEmitter.test.ts
new file mode 100644
index 00000000000..0c6b184642b
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/createDictationEventEmitter.test.ts
@@ -0,0 +1,55 @@
+import { createDictationEventEmitter } from '@/ai/dictation/utils/createDictationEventEmitter';
+
+describe('createDictationEventEmitter', () => {
+ it('delivers events to every subscriber', () => {
+ const emitter = createDictationEventEmitter();
+ const first = jest.fn();
+ const second = jest.fn();
+
+ emitter.subscribe(first);
+ emitter.subscribe(second);
+ emitter.emit({ type: 'final', text: 'hello' });
+
+ expect(first).toHaveBeenCalledWith({ type: 'final', text: 'hello' });
+ expect(second).toHaveBeenCalledWith({ type: 'final', text: 'hello' });
+ });
+
+ it('stops delivering after unsubscribe', () => {
+ const emitter = createDictationEventEmitter();
+ const listener = jest.fn();
+
+ const unsubscribe = emitter.subscribe(listener);
+
+ unsubscribe();
+ emitter.emit({ type: 'state', state: 'idle' });
+
+ expect(listener).not.toHaveBeenCalled();
+ });
+
+ // A listener that tears itself down on its own event must not stop the ones
+ // registered after it from being called for that same event.
+ it('still reaches later listeners when an earlier one unsubscribes mid-emit', () => {
+ const emitter = createDictationEventEmitter();
+ const later = jest.fn();
+
+ const unsubscribeFirst = emitter.subscribe(() => {
+ unsubscribeFirst();
+ });
+
+ emitter.subscribe(later);
+ emitter.emit({ type: 'state', state: 'recording' });
+
+ expect(later).toHaveBeenCalledTimes(1);
+ });
+
+ it('drops every listener on clear', () => {
+ const emitter = createDictationEventEmitter();
+ const listener = jest.fn();
+
+ emitter.subscribe(listener);
+ emitter.clear();
+ emitter.emit({ type: 'state', state: 'idle' });
+
+ expect(listener).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/createLivenessWatchdog.test.ts b/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/createLivenessWatchdog.test.ts
new file mode 100644
index 00000000000..c43ed157a93
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/createLivenessWatchdog.test.ts
@@ -0,0 +1,88 @@
+import { createLivenessWatchdog } from '@/ai/dictation/utils/createLivenessWatchdog';
+
+describe('createLivenessWatchdog', () => {
+ const TIMEOUT_IN_MS = 2500;
+
+ beforeEach(() => {
+ jest.useFakeTimers();
+ });
+
+ afterEach(() => {
+ jest.useRealTimers();
+ });
+
+ it('reports silence when nothing happens before the timeout', () => {
+ const onSilent = jest.fn();
+ const watchdog = createLivenessWatchdog({
+ timeoutInMs: TIMEOUT_IN_MS,
+ onSilent,
+ });
+
+ watchdog.arm();
+ jest.advanceTimersByTime(TIMEOUT_IN_MS);
+
+ expect(onSilent).toHaveBeenCalledTimes(1);
+ });
+
+ it('stays quiet when activity arrives in time', () => {
+ const onSilent = jest.fn();
+ const watchdog = createLivenessWatchdog({
+ timeoutInMs: TIMEOUT_IN_MS,
+ onSilent,
+ });
+
+ watchdog.arm();
+ jest.advanceTimersByTime(TIMEOUT_IN_MS - 1);
+ watchdog.noteActivity();
+ jest.advanceTimersByTime(TIMEOUT_IN_MS * 2);
+
+ expect(onSilent).not.toHaveBeenCalled();
+ });
+
+ it('stays quiet after being disarmed', () => {
+ const onSilent = jest.fn();
+ const watchdog = createLivenessWatchdog({
+ timeoutInMs: TIMEOUT_IN_MS,
+ onSilent,
+ });
+
+ watchdog.arm();
+ watchdog.disarm();
+ jest.advanceTimersByTime(TIMEOUT_IN_MS * 2);
+
+ expect(onSilent).not.toHaveBeenCalled();
+ });
+
+ // A second session must be judged on its own silence, not excused by the
+ // activity of the one before it.
+ it('forgets activity from a previous session when re-armed', () => {
+ const onSilent = jest.fn();
+ const watchdog = createLivenessWatchdog({
+ timeoutInMs: TIMEOUT_IN_MS,
+ onSilent,
+ });
+
+ watchdog.arm();
+ watchdog.noteActivity();
+
+ watchdog.arm();
+ jest.advanceTimersByTime(TIMEOUT_IN_MS);
+
+ expect(onSilent).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not stack timers when armed twice', () => {
+ const onSilent = jest.fn();
+ const watchdog = createLivenessWatchdog({
+ timeoutInMs: TIMEOUT_IN_MS,
+ onSilent,
+ });
+
+ watchdog.arm();
+ jest.advanceTimersByTime(TIMEOUT_IN_MS - 100);
+ watchdog.arm();
+ jest.advanceTimersByTime(TIMEOUT_IN_MS);
+
+ expect(onSilent).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/getDictationLanguage.test.ts b/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/getDictationLanguage.test.ts
new file mode 100644
index 00000000000..2df2645e494
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/getDictationLanguage.test.ts
@@ -0,0 +1,20 @@
+import { getDictationLanguage } from '@/ai/dictation/utils/getDictationLanguage';
+
+describe('getDictationLanguage', () => {
+ it('uses the workspace member locale', () => {
+ expect(getDictationLanguage('fr-FR')).toBe('fr-FR');
+ });
+
+ it.each([undefined, null, ''])(
+ 'falls back to the source locale for %p',
+ (locale) => {
+ expect(getDictationLanguage(locale)).toBe('en');
+ },
+ );
+
+ // The pseudo locale is a translation-coverage tool, not a language anything
+ // can be recognised in.
+ it('falls back to the source locale for the pseudo locale', () => {
+ expect(getDictationLanguage('pseudo-en')).toBe('en');
+ });
+});
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/mapSpeechRecognitionError.test.ts b/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/mapSpeechRecognitionError.test.ts
new file mode 100644
index 00000000000..762b4b7074c
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/mapSpeechRecognitionError.test.ts
@@ -0,0 +1,19 @@
+import { mapSpeechRecognitionError } from '@/ai/dictation/utils/mapSpeechRecognitionError';
+
+describe('mapSpeechRecognitionError', () => {
+ it.each([
+ ['not-allowed', 'permission-denied'],
+ ['service-not-allowed', 'permission-denied'],
+ ['audio-capture', 'no-device'],
+ ['network', 'network'],
+ ['language-not-supported', 'engine-error'],
+ ])('maps %s to %s', (error, expected) => {
+ expect(mapSpeechRecognitionError(error)).toBe(expected);
+ });
+
+ // Both are ordinary endings rather than failures: one is the user pressing
+ // stop, the other is a quiet room.
+ it.each(['aborted', 'no-speech'])('treats %s as a normal ending', (error) => {
+ expect(mapSpeechRecognitionError(error)).toBeUndefined();
+ });
+});
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/resolveDictationAvailability.test.ts b/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/resolveDictationAvailability.test.ts
new file mode 100644
index 00000000000..ef2ae53b140
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/resolveDictationAvailability.test.ts
@@ -0,0 +1,77 @@
+import { type DictationSurface } from '@/ai/dictation/types/DictationSurface';
+import { resolveDictationAvailability } from '@/ai/dictation/utils/resolveDictationAvailability';
+
+const CAPABLE_DESKTOP_SURFACE: DictationSurface = {
+ isIOS: false,
+ isStandaloneDisplayMode: false,
+ isThirdPartyIOSBrowser: false,
+ hasSpeechRecognition: true,
+ hasMediaDevices: true,
+ isSecureContext: true,
+};
+
+describe('resolveDictationAvailability', () => {
+ it('offers dictation on a capable desktop browser', () => {
+ expect(resolveDictationAvailability(CAPABLE_DESKTOP_SURFACE)).toBe(true);
+ });
+
+ it('refuses without a secure context, since the microphone is gated on it', () => {
+ expect(
+ resolveDictationAvailability({
+ ...CAPABLE_DESKTOP_SURFACE,
+ isSecureContext: false,
+ }),
+ ).toBe(false);
+ });
+
+ it('refuses without speech recognition', () => {
+ expect(
+ resolveDictationAvailability({
+ ...CAPABLE_DESKTOP_SURFACE,
+ hasSpeechRecognition: false,
+ }),
+ ).toBe(false);
+ });
+
+ // The Web Speech API is exposed in these iOS contexts but never emits, so
+ // they are refused before a recording is spent proving it.
+ it('refuses an installed iOS app', () => {
+ expect(
+ resolveDictationAvailability({
+ ...CAPABLE_DESKTOP_SURFACE,
+ isIOS: true,
+ isStandaloneDisplayMode: true,
+ }),
+ ).toBe(false);
+ });
+
+ it('refuses a third-party iOS browser', () => {
+ expect(
+ resolveDictationAvailability({
+ ...CAPABLE_DESKTOP_SURFACE,
+ isIOS: true,
+ isThirdPartyIOSBrowser: true,
+ }),
+ ).toBe(false);
+ });
+
+ it('still offers dictation in iOS Safari itself', () => {
+ expect(
+ resolveDictationAvailability({
+ ...CAPABLE_DESKTOP_SURFACE,
+ isIOS: true,
+ }),
+ ).toBe(true);
+ });
+
+ // The engine warms the microphone through getUserMedia before recognition, so
+ // a WebView exposing SpeechRecognition without it fails on every press.
+ it('refuses a surface with no microphone capture support', () => {
+ expect(
+ resolveDictationAvailability({
+ ...CAPABLE_DESKTOP_SURFACE,
+ hasMediaDevices: false,
+ }),
+ ).toBe(false);
+ });
+});
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/unlockAudioContext.test.ts b/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/unlockAudioContext.test.ts
new file mode 100644
index 00000000000..2c31c73ef97
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/__tests__/unlockAudioContext.test.ts
@@ -0,0 +1,56 @@
+import { unlockAudioContext } from '@/ai/dictation/utils/unlockAudioContext';
+
+type AudioContextTestWindow = {
+ AudioContext?: typeof AudioContext;
+};
+
+const stubAudioContext = ({
+ doesResumeReject = false,
+}: { doesResumeReject?: boolean } = {}) => {
+ const close = jest.fn(() => Promise.resolve());
+ const resume = jest.fn(() =>
+ doesResumeReject
+ ? Promise.reject(new DOMException('not allowed', 'InvalidStateError'))
+ : Promise.resolve(),
+ );
+
+ (window as AudioContextTestWindow).AudioContext = function AudioContext(
+ this: Record<string, unknown>,
+ ) {
+ this.state = 'suspended';
+ this.resume = resume;
+ this.close = close;
+ } as unknown as typeof AudioContext;
+
+ return { close, resume };
+};
+
+describe('unlockAudioContext', () => {
+ afterEach(() => {
+ delete (window as AudioContextTestWindow).AudioContext;
+ });
+
+ it('releases the context it opened', async () => {
+ const { close, resume } = stubAudioContext();
+
+ await unlockAudioContext();
+
+ expect(resume).toHaveBeenCalledTimes(1);
+ expect(close).toHaveBeenCalledTimes(1);
+ });
+
+ // A browser allows only a handful of live contexts, and resume() rejecting is
+ // routine on the surface this exists for, so leaking one per press would
+ // exhaust the pool the unlock depends on.
+ it('releases the context even when resuming it fails', async () => {
+ const { close } = stubAudioContext({ doesResumeReject: true });
+
+ await expect(unlockAudioContext()).resolves.toBeUndefined();
+
+ expect(close).toHaveBeenCalledTimes(1);
+ });
+
+ it('does nothing on a browser with no audio context', async () => {
+ await expect(unlockAudioContext()).resolves.toBeUndefined();
+ });
+});
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/createDictationEventEmitter.ts b/packages/twenty-front/src/modules/ai/dictation/utils/createDictationEventEmitter.ts
new file mode 100644
index 00000000000..c9d62d85c25
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/createDictationEventEmitter.ts
@@ -0,0 +1,26 @@
+import { type DictationEventEmitter } from '@/ai/dictation/types/DictationEventEmitter';
+import { type DictationEngineListener } from '@/ai/dictation/types/DictationEngineListener';
+
+export const createDictationEventEmitter = (): DictationEventEmitter => {
+ const listeners = new Set<DictationEngineListener>();
+
+ return {
+ // Iterating a copy so a listener that unsubscribes on its own event cannot
+ // skip the listener registered after it.
+ emit: (event) => {
+ for (const listener of Array.from(listeners)) {
+ listener(event);
+ }
+ },
+ subscribe: (listener) => {
+ listeners.add(listener);
+
+ return () => {
+ listeners.delete(listener);
+ };
+ },
+ clear: () => {
+ listeners.clear();
+ },
+ };
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/createLivenessWatchdog.ts b/packages/twenty-front/src/modules/ai/dictation/utils/createLivenessWatchdog.ts
new file mode 100644
index 00000000000..631d9697245
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/createLivenessWatchdog.ts
@@ -0,0 +1,41 @@
+import { type LivenessWatchdog } from '@/ai/dictation/types/LivenessWatchdog';
+// iOS can accept start() and then emit nothing at all, so liveness is measured
+// rather than assumed. Kept free of browser APIs beyond timers so the rule that
+// decides whether dictation is working can be tested without a microphone.
+export const createLivenessWatchdog = ({
+ timeoutInMs,
+ onSilent,
+}: {
+ timeoutInMs: number;
+ onSilent: () => void;
+}): LivenessWatchdog => {
+ let timer: ReturnType<typeof setTimeout> | null = null;
+ let hasSeenActivity = false;
+
+ const clear = () => {
+ if (timer !== null) {
+ clearTimeout(timer);
+ timer = null;
+ }
+ };
+
+ return {
+ arm: () => {
+ clear();
+ hasSeenActivity = false;
+ timer = setTimeout(() => {
+ timer = null;
+ if (!hasSeenActivity) {
+ onSilent();
+ }
+ }, timeoutInMs);
+ },
+ // Any sign of life counts, not just a transcript: audio opening proves the
+ // engine is running, and a slow speaker should not read as a dead engine.
+ noteActivity: () => {
+ hasSeenActivity = true;
+ clear();
+ },
+ disarm: clear,
+ };
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/getDictationFailureMessage.ts b/packages/twenty-front/src/modules/ai/dictation/utils/getDictationFailureMessage.ts
new file mode 100644
index 00000000000..052afc821a7
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/getDictationFailureMessage.ts
@@ -0,0 +1,25 @@
+import { t } from '@lingui/core/macro';
+import { assertUnreachable } from 'twenty-shared/utils';
+
+import { type DictationFailureReason } from '@/ai/dictation/types/DictationFailureReason';
+
+export const getDictationFailureMessage = (
+ reason: DictationFailureReason,
+): string => {
+ switch (reason) {
+ case 'permission-denied':
+ return t`Microphone access is blocked. Allow it in your browser settings to dictate.`;
+ case 'no-device':
+ return t`No microphone is available. Connect one and try again.`;
+ case 'unsupported-surface':
+ return t`Dictation is not supported in this browser.`;
+ case 'engine-silent':
+ return t`Dictation did not respond in this browser. Try Safari, or type instead.`;
+ case 'network':
+ return t`Speech recognition could not be reached. Check your connection.`;
+ case 'engine-error':
+ return t`Dictation failed. Try again.`;
+ default:
+ return assertUnreachable(reason);
+ }
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/getDictationLanguage.ts b/packages/twenty-front/src/modules/ai/dictation/utils/getDictationLanguage.ts
new file mode 100644
index 00000000000..b371a120583
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/getDictationLanguage.ts
@@ -0,0 +1,16 @@
+import { APP_LOCALES, SOURCE_LOCALE } from 'twenty-shared/translations';
+import { normalizeLocale } from 'twenty-shared/utils';
+
+// Only the on-device engine needs this: the Web Speech API recognises exactly
+// one language per session and cannot detect it, so a wrong guess produces
+// confident nonsense rather than an error. The speaker's Twenty language beats
+// navigator.language, which is the browser UI's rather than the speaker's.
+export const getDictationLanguage = (
+ workspaceMemberLocale?: string | null,
+): string => {
+ const locale = normalizeLocale(workspaceMemberLocale ?? null);
+
+ // The pseudo locale is a translation-coverage tool, not a language anything
+ // can be recognised in.
+ return locale === APP_LOCALES['pseudo-en'] ? SOURCE_LOCALE : locale;
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/getSpeechRecognitionConstructor.ts b/packages/twenty-front/src/modules/ai/dictation/utils/getSpeechRecognitionConstructor.ts
new file mode 100644
index 00000000000..244311e6519
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/getSpeechRecognitionConstructor.ts
@@ -0,0 +1,17 @@
+import { type WebSpeechRecognitionConstructor } from '@/ai/dictation/types/WebSpeechRecognitionConstructor';
+
+type SpeechRecognitionWindow = {
+ SpeechRecognition?: WebSpeechRecognitionConstructor;
+ webkitSpeechRecognition?: WebSpeechRecognitionConstructor;
+};
+
+export const getSpeechRecognitionConstructor = ():
+ | WebSpeechRecognitionConstructor
+ | undefined => {
+ const speechRecognitionWindow = window as unknown as SpeechRecognitionWindow;
+
+ return (
+ speechRecognitionWindow.SpeechRecognition ??
+ speechRecognitionWindow.webkitSpeechRecognition
+ );
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/mapMediaDeviceError.ts b/packages/twenty-front/src/modules/ai/dictation/utils/mapMediaDeviceError.ts
new file mode 100644
index 00000000000..3d4640b7dde
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/mapMediaDeviceError.ts
@@ -0,0 +1,22 @@
+import { type DictationFailureReason } from '@/ai/dictation/types/DictationFailureReason';
+
+// getUserMedia rejects with a DOMException whose name is the only stable part
+// of the failure; the message is browser-specific prose.
+export const mapMediaDeviceError = (error: unknown): DictationFailureReason => {
+ const name = error instanceof Error ? error.name : '';
+
+ switch (name) {
+ case 'NotAllowedError':
+ case 'SecurityError':
+ return 'permission-denied';
+ case 'NotFoundError':
+ case 'OverconstrainedError':
+ return 'no-device';
+ // The device exists but another application holds it, which the user fixes
+ // the same way they would a missing one.
+ case 'NotReadableError':
+ return 'no-device';
+ default:
+ return 'engine-error';
+ }
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/mapSpeechRecognitionError.ts b/packages/twenty-front/src/modules/ai/dictation/utils/mapSpeechRecognitionError.ts
new file mode 100644
index 00000000000..fcc8d2cfcb5
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/mapSpeechRecognitionError.ts
@@ -0,0 +1,24 @@
+import { type DictationFailureReason } from '@/ai/dictation/types/DictationFailureReason';
+
+// 'aborted' is absent on purpose: it is what a deliberate stop() produces, and
+// treating it as a failure would surface an error every time a user finishes.
+export const mapSpeechRecognitionError = (
+ error: string,
+): DictationFailureReason | undefined => {
+ switch (error) {
+ case 'not-allowed':
+ case 'service-not-allowed':
+ return 'permission-denied';
+ case 'audio-capture':
+ return 'no-device';
+ case 'network':
+ return 'network';
+ case 'aborted':
+ // The engine ran and heard nothing, which is a quiet room rather than a
+ // broken engine — the session just ends with no transcript.
+ case 'no-speech':
+ return undefined;
+ default:
+ return 'engine-error';
+ }
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/readDictationSurface.ts b/packages/twenty-front/src/modules/ai/dictation/utils/readDictationSurface.ts
new file mode 100644
index 00000000000..25de76ac9f3
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/readDictationSurface.ts
@@ -0,0 +1,37 @@
+import { isDefined } from 'twenty-shared/utils';
+
+import { getSpeechRecognitionConstructor } from '@/ai/dictation/utils/getSpeechRecognitionConstructor';
+import { type DictationSurface } from '@/ai/dictation/types/DictationSurface';
+
+// Every browser shipped for iOS is WKWebView underneath, so these are detected
+// by name rather than by engine — the engine would report Safari for all of them.
+const THIRD_PARTY_IOS_BROWSER_PATTERN = /CriOS|FxiOS|EdgiOS|OPiOS/;
+const IOS_DEVICE_PATTERN = /iPad|iPhone|iPod/;
+
+type StandaloneNavigator = { standalone?: boolean };
+
+const getIsIOS = (userAgent: string): boolean =>
+ IOS_DEVICE_PATTERN.test(userAgent) ||
+ // iPadOS reports itself as a Mac; the touch points are what give it away.
+ (navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1);
+
+// matchMedia is missing from some embedded WebViews, which are exactly the
+// surfaces this module exists to survive, so its absence falls back to the
+// legacy iOS flag rather than throwing.
+const getIsStandaloneDisplayMode = (): boolean =>
+ (isDefined(window.matchMedia) &&
+ window.matchMedia('(display-mode: standalone)').matches) ||
+ (navigator as StandaloneNavigator).standalone === true;
+
+export const readDictationSurface = (): DictationSurface => {
+ const userAgent = navigator.userAgent;
+
+ return {
+ isIOS: getIsIOS(userAgent),
+ isStandaloneDisplayMode: getIsStandaloneDisplayMode(),
+ isThirdPartyIOSBrowser: THIRD_PARTY_IOS_BROWSER_PATTERN.test(userAgent),
+ hasSpeechRecognition: isDefined(getSpeechRecognitionConstructor()),
+ hasMediaDevices: isDefined(navigator.mediaDevices?.getUserMedia),
+ isSecureContext: window.isSecureContext,
+ };
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/resolveDictationAvailability.ts b/packages/twenty-front/src/modules/ai/dictation/utils/resolveDictationAvailability.ts
new file mode 100644
index 00000000000..908d92e436f
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/resolveDictationAvailability.ts
@@ -0,0 +1,20 @@
+import { type DictationSurface } from '@/ai/dictation/types/DictationSurface';
+
+// On iOS the Web Speech API is exposed inside installed PWAs and third-party
+// browsers (all WKWebView) but never emits, so these surfaces would otherwise
+// cost the user a recording before failing.
+const isWebSpeechKnownDead = (surface: DictationSurface) =>
+ surface.isIOS &&
+ (surface.isStandaloneDisplayMode || surface.isThirdPartyIOSBrowser);
+
+// hasMediaDevices matters even though recognition does its own capture: the
+// engine warms the microphone through getUserMedia first, so a WebView that
+// exposes SpeechRecognition without it would offer a button that fails on
+// every press. Opening a microphone at all is gated on a secure context.
+export const resolveDictationAvailability = (
+ surface: DictationSurface,
+): boolean =>
+ surface.isSecureContext &&
+ surface.hasSpeechRecognition &&
+ surface.hasMediaDevices &&
+ !isWebSpeechKnownDead(surface);
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/unlockAudioContext.ts b/packages/twenty-front/src/modules/ai/dictation/utils/unlockAudioContext.ts
new file mode 100644
index 00000000000..f3effa3e937
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/unlockAudioContext.ts
@@ -0,0 +1,52 @@
+import { isDefined } from 'twenty-shared/utils';
+
+type AudioContextWindow = {
+ AudioContext?: typeof AudioContext;
+ webkitAudioContext?: typeof AudioContext;
+};
+
+// close() rejects on a context that never finished opening, and releasing one
+// is never worth failing a start over.
+const closeQuietly = async (audioContext: AudioContext): Promise<void> => {
+ try {
+ await audioContext.close();
+ } catch {
+ return;
+ }
+};
+
+// iOS suspends any AudioContext created outside a user gesture, and a suspended
+// context blocks the capture path speech recognition runs on. Failures are
+// swallowed: this improves the odds of a clean start and is never the reason to
+// refuse one.
+export const unlockAudioContext = async (): Promise<void> => {
+ const audioContextWindow = window as unknown as AudioContextWindow;
+ const AudioContextConstructor =
+ audioContextWindow.AudioContext ?? audioContextWindow.webkitAudioContext;
+
+ if (!isDefined(AudioContextConstructor)) {
+ return;
+ }
+
+ let audioContext: AudioContext | undefined;
+
+ try {
+ audioContext = new AudioContextConstructor();
+
+ if (audioContext.state === 'suspended') {
+ await audioContext.resume();
+ }
+ } catch {
+ // See above: a failed unlock costs the odds of a clean start, nothing more.
+ } finally {
+ // Closed here rather than after resume(), because resume() rejecting is
+ // exactly when the context would otherwise be leaked — and a rejection is
+ // expected on the surface this exists for, where the gesture that permits
+ // it can have expired during the microphone warm-up. A browser allows only
+ // a handful of live contexts, each holding an audio render thread, so
+ // leaking one per press would starve the capture path this is unlocking.
+ if (isDefined(audioContext)) {
+ await closeQuietly(audioContext);
+ }
+ }
+};
diff --git a/packages/twenty-front/src/modules/ai/dictation/utils/warmUpMicrophone.ts b/packages/twenty-front/src/modules/ai/dictation/utils/warmUpMicrophone.ts
new file mode 100644
index 00000000000..efacf0d8481
--- /dev/null
+++ b/packages/twenty-front/src/modules/ai/dictation/utils/warmUpMicrophone.ts
@@ -0,0 +1,12 @@
+// Opening and immediately releasing the microphone on the user's gesture is
+// what makes the first dictation attempt work on iOS: WebKit otherwise starts
+// recognition against an audio stack that is still initialising and returns no
+// result at all. The tracks are stopped straight away — the warm-up exists for
+// its side effect on the audio stack, not to hold a stream open.
+export const warmUpMicrophone = async (): Promise<void> => {
+ const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+
+ for (const track of stream.getTracks()) {
+ track.stop();
+ }
+};
diff --git a/packages/twenty-ui/src/icon/components/TablerIcons.ts b/packages/twenty-ui/src/icon/components/TablerIcons.ts
index cdb30ffe601..d110593a4d1 100644
--- a/packages/twenty-ui/src/icon/components/TablerIcons.ts
+++ b/packages/twenty-ui/src/icon/components/TablerIcons.ts
@@ -289,6 +289,7 @@ export {
IconMaximize,
IconMessage,
IconMessageCirclePlus,
+ IconMicrophone,
IconMinus,
IconMoneybag,
IconMoodSmile,
diff --git a/packages/twenty-ui/src/icon/constants/TwentyIconDictionary.ts b/packages/twenty-ui/src/icon/constants/TwentyIconDictionary.ts
index 052f8048c16..93081bbbb05 100644
--- a/packages/twenty-ui/src/icon/constants/TwentyIconDictionary.ts
+++ b/packages/twenty-ui/src/icon/constants/TwentyIconDictionary.ts
@@ -571,6 +571,17 @@ export const TWENTY_ICON_DICTIONARY = [
avoidWhen:
'Representing a general file collection, import, or upload action.',
},
+ {
+ key: 'dictation',
+ label: 'Dictation',
+ category: 'general',
+ iconName: 'IconMicrophone',
+ tablerName: 'microphone',
+ keywords: ['dictation', 'voice input', 'speech to text', 'microphone'],
+ useWhen: 'Representing voice input or a dictation control.',
+ avoidWhen:
+ 'Representing audio playback, a call recording, or a phone number.',
+ },
{
key: 'app',
label: 'App',
diff --git a/packages/twenty-ui/src/icon/icon-dictionary.md b/packages/twenty-ui/src/icon/icon-dictionary.md
index 9872ca7628c..007fd3c169e 100644
--- a/packages/twenty-ui/src/icon/icon-dictionary.md
+++ b/packages/twenty-ui/src/icon/icon-dictionary.md
@@ -115,6 +115,7 @@ import { IconHierarchy } from 'twenty-ui/icon';
| Notification | `IconBell` | `bell` | Representing notifications or notification settings. | Representing an error severity, favorite, or decorative star. | notification, notice, notification settings, alert |
| Files | `IconFiles` | `files` | Representing a collection of files or a files section. | Representing one file, an attachment, or an upload action. | files, file collection, documents, file section |
| Attachments | `IconPaperclip` | `paperclip` | Representing attachments or an attachment relationship. | Representing a general file collection, import, or upload action. | attachment, attachments, attached file, record attachment |
+| Dictation | `IconMicrophone` | `microphone` | Representing voice input or a dictation control. | Representing audio playback, a call recording, or a phone number. | dictation, voice input, speech to text, microphone |
| App | `IconApps` | `apps` | Representing an application or the apps platform. | Representing a widget, integration, or one navigation item. | app, application, Twenty app |
| Navigation Sidebar | `IconLayoutSidebar` | `layout-sidebar` | Representing the application navigation sidebar. | Representing a destination inside the navigation menu. | navigation sidebar, sidebar, left navigation |
| Iframe | `IconFrame` | `frame` | Representing an iframe or embedded external page. | Representing a native page layout or browser window. | iframe, embedded page, web frame |
diff --git a/packages/twenty-ui/src/icon/index.ts b/packages/twenty-ui/src/icon/index.ts
index 018381c0500..261f7715944 100644
--- a/packages/twenty-ui/src/icon/index.ts
+++ b/packages/twenty-ui/src/icon/index.ts
@@ -344,6 +344,7 @@ export {
IconMaximize,
IconMessage,
IconMessageCirclePlus,
+ IconMicrophone,
IconMinus,
IconMoneybag,
IconMoodSmile,