From b3e7214a561e8f8314d197bda146f57259a20fcb Mon Sep 17 00:00:00 2001
From: Houssem Eddine BENABDALLAH
Date: Tue, 3 Nov 2026 20:15:23 +0100
Subject: [PATCH 1/3] feat: dictate a commit with a microphone button in the
composer
---
resources/js/components/commit-composer.tsx | 8 +
resources/js/components/dictation-button.tsx | 63 +++++++
resources/js/hooks/use-dictation.ts | 169 +++++++++++++++++++
resources/js/lib/dictation.ts | 13 ++
tests/Unit/Dictation.test.ts | 11 ++
tests/Unit/DictationInsertion.test.tsx | 143 ++++++++++++++++
6 files changed, 407 insertions(+)
create mode 100644 resources/js/components/dictation-button.tsx
create mode 100644 resources/js/hooks/use-dictation.ts
create mode 100644 resources/js/lib/dictation.ts
create mode 100644 tests/Unit/Dictation.test.ts
create mode 100644 tests/Unit/DictationInsertion.test.tsx
diff --git a/resources/js/components/commit-composer.tsx b/resources/js/components/commit-composer.tsx
index 1208f3ddcc..55a32965cf 100644
--- a/resources/js/components/commit-composer.tsx
+++ b/resources/js/components/commit-composer.tsx
@@ -20,6 +20,7 @@ import {
PreviewToggle,
useComposerPreview,
} from '@/components/composer-preview';
+import { DictationButton } from '@/components/dictation-button';
import { EmojiPickerButton } from '@/components/emoji-picker';
import { GraphRail, RailAvatar } from '@/components/graph-rail';
import InputError from '@/components/input-error';
@@ -521,6 +522,13 @@ function CommitComposerBody({
+ void;
+ textareaRef: RefObject;
+ maxLength: number;
+ disabled: boolean;
+}) {
+ const dictation = useDictation({
+ body,
+ updateBody,
+ textareaRef,
+ maxLength,
+ });
+ const { isListening, stop } = dictation;
+
+ useEffect(() => {
+ if (disabled && isListening) {
+ stop();
+ }
+ }, [disabled, isListening, stop]);
+
+ if (!dictation.isSupported) {
+ return null;
+ }
+
+ return (
+
+
+
+ );
+}
diff --git a/resources/js/hooks/use-dictation.ts b/resources/js/hooks/use-dictation.ts
new file mode 100644
index 0000000000..4badd8f58c
--- /dev/null
+++ b/resources/js/hooks/use-dictation.ts
@@ -0,0 +1,169 @@
+import type { RefObject } from 'react';
+import {
+ useEffect,
+ useLayoutEffect,
+ useRef,
+ useState,
+ useSyncExternalStore,
+} from 'react';
+import { toast } from 'sonner';
+import { dictatedText } from '@/lib/dictation';
+import { insertAtSelection } from '@/lib/text-selection';
+
+type SpeechRecognitionResultList = ArrayLike<
+ ArrayLike<{ transcript: string }> & { isFinal: boolean }
+>;
+
+/**
+ * The part of the Web Speech API's SpeechRecognition used here, which TypeScript's DOM types don't include.
+ */
+type Recognition = {
+ lang: string;
+ continuous: boolean;
+ interimResults: boolean;
+ onresult:
+ | ((event: {
+ resultIndex: number;
+ results: SpeechRecognitionResultList;
+ }) => void)
+ | null;
+ onerror: ((event: { error: string }) => void) | null;
+ onend: (() => void) | null;
+ start: () => void;
+ stop: () => void;
+ abort: () => void;
+};
+
+type RecognitionConstructor = new () => Recognition;
+
+function recognitionConstructor(): RecognitionConstructor | null {
+ if (typeof window === 'undefined') {
+ return null;
+ }
+
+ const speech = window as unknown as {
+ SpeechRecognition?: RecognitionConstructor;
+ webkitSpeechRecognition?: RecognitionConstructor;
+ };
+
+ return speech.SpeechRecognition ?? speech.webkitSpeechRecognition ?? null;
+}
+
+const subscribe = () => () => {};
+
+/**
+ * Dictation into the composer's textarea with the browser's own speech recognition (Chrome, Edge and Safari have it,
+ * Firefox doesn't). Each finished phrase is inserted where the caret is, as typing would, up to `maxLength`.
+ */
+export function useDictation({
+ body,
+ updateBody,
+ textareaRef,
+ maxLength,
+}: {
+ body: string;
+ updateBody: (body: string) => void;
+ textareaRef: RefObject;
+ maxLength: number;
+}): {
+ isSupported: boolean;
+ isListening: boolean;
+ start: () => void;
+ stop: () => void;
+} {
+ // Unknown while rendering on the server, so the button only appears once the page runs in the browser.
+ const isSupported = useSyncExternalStore(
+ subscribe,
+ () => recognitionConstructor() !== null,
+ () => false,
+ );
+ const [isListening, setIsListening] = useState(false);
+ const recognition = useRef(null);
+ const latest = useRef({ body, updateBody, maxLength });
+ const caret = useRef(null);
+
+ useLayoutEffect(() => {
+ latest.current = { body, updateBody, maxLength };
+
+ const element = textareaRef.current;
+
+ if (caret.current === null || element === null) {
+ return;
+ }
+
+ element.focus();
+ element.setSelectionRange(caret.current, caret.current);
+ caret.current = null;
+ }, [body, updateBody, maxLength, textareaRef]);
+
+ useEffect(() => () => recognition.current?.abort(), []);
+
+ const insert = (transcript: string) => {
+ const { body, updateBody, maxLength } = latest.current;
+ const element = textareaRef.current;
+ const text = dictatedText(
+ body.slice(0, element?.selectionStart ?? body.length),
+ transcript,
+ );
+ const inserted =
+ text === ''
+ ? null
+ : insertAtSelection(body, element, text, maxLength);
+
+ if (inserted !== null) {
+ caret.current = inserted.caret;
+ updateBody(inserted.value);
+ }
+ };
+
+ const start = () => {
+ const Constructor = recognitionConstructor();
+
+ if (Constructor === null || recognition.current !== null) {
+ return;
+ }
+
+ const listener = new Constructor();
+ listener.lang = document.documentElement.lang || navigator.language;
+ listener.continuous = true;
+ listener.interimResults = false;
+ listener.onresult = (event) => {
+ for (
+ let index = event.resultIndex;
+ index < event.results.length;
+ index++
+ ) {
+ const result = event.results[index];
+
+ if (result.isFinal) {
+ insert(result[0].transcript);
+ }
+ }
+ };
+ listener.onerror = (event) => {
+ if (
+ event.error === 'not-allowed' ||
+ event.error === 'service-not-allowed'
+ ) {
+ toast.error('Allow the microphone to dictate your commit.');
+ } else if (
+ event.error !== 'no-speech' &&
+ event.error !== 'aborted'
+ ) {
+ toast.error('Dictation stopped. Try again.');
+ }
+ };
+ listener.onend = () => {
+ recognition.current = null;
+ setIsListening(false);
+ };
+
+ recognition.current = listener;
+ listener.start();
+ setIsListening(true);
+ };
+
+ const stop = () => recognition.current?.stop();
+
+ return { isSupported, isListening, start, stop };
+}
diff --git a/resources/js/lib/dictation.ts b/resources/js/lib/dictation.ts
new file mode 100644
index 0000000000..cd09e8d224
--- /dev/null
+++ b/resources/js/lib/dictation.ts
@@ -0,0 +1,13 @@
+/**
+ * The text to insert for what was said, given the text before the caret: the transcript trimmed, with a space in front
+ * when it would otherwise stick to the previous word. Empty when nothing was said.
+ */
+export function dictatedText(before: string, transcript: string): string {
+ const text = transcript.trim();
+
+ if (text === '') {
+ return '';
+ }
+
+ return before === '' || /\s$/u.test(before) ? text : ` ${text}`;
+}
diff --git a/tests/Unit/Dictation.test.ts b/tests/Unit/Dictation.test.ts
new file mode 100644
index 0000000000..7e787ce8fc
--- /dev/null
+++ b/tests/Unit/Dictation.test.ts
@@ -0,0 +1,11 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { dictatedText } from '../../resources/js/lib/dictation.ts';
+
+void test('dictated text is trimmed and starts a new word after the caret', () => {
+ assert.equal(dictatedText('', ' shipped it '), 'shipped it');
+ assert.equal(dictatedText('Finally', 'shipped it'), ' shipped it');
+ assert.equal(dictatedText('Finally ', 'shipped it'), 'shipped it');
+ assert.equal(dictatedText('Finally\n', 'shipped it'), 'shipped it');
+ assert.equal(dictatedText('Finally', ' '), '');
+});
diff --git a/tests/Unit/DictationInsertion.test.tsx b/tests/Unit/DictationInsertion.test.tsx
new file mode 100644
index 0000000000..04265571a4
--- /dev/null
+++ b/tests/Unit/DictationInsertion.test.tsx
@@ -0,0 +1,143 @@
+///
+import assert from 'node:assert/strict';
+import * as React from 'react';
+import { afterAll, beforeEach, test, vi } from 'vite-plus/test';
+
+let layoutEffect: () => void = () => {};
+const setIsListening = vi.fn();
+
+// Renders the hook once: effects run when the test says React has written the new body.
+vi.doMock('react', () => ({
+ ...React,
+ useLayoutEffect: (effect: () => void) => {
+ layoutEffect = effect;
+ },
+ useEffect: () => {},
+ useRef: (initial: unknown) => ({ current: initial }),
+ useState: (initial: unknown) => [initial, setIsListening],
+ useSyncExternalStore: (_subscribe: unknown, snapshot: () => unknown) =>
+ snapshot(),
+}));
+
+const toastError = vi.fn();
+vi.doMock('sonner', () => ({ toast: { error: toastError } }));
+
+type Listener = {
+ lang: string;
+ continuous: boolean;
+ start: () => void;
+ onresult: (event: {
+ resultIndex: number;
+ results: ({ transcript: string }[] & { isFinal: boolean })[];
+ }) => void;
+ onerror: (event: { error: string }) => void;
+ onend: () => void;
+};
+
+let listener: Listener;
+
+vi.stubGlobal('window', {
+ webkitSpeechRecognition: class {
+ start = vi.fn();
+ stop = vi.fn();
+ abort = vi.fn();
+
+ constructor() {
+ listener = this as unknown as Listener;
+ }
+ },
+});
+vi.stubGlobal('document', { documentElement: { lang: 'fr' } });
+
+afterAll(() => {
+ vi.doUnmock('react');
+ vi.doUnmock('sonner');
+ vi.unstubAllGlobals();
+});
+
+const { useDictation } = await import('../../resources/js/hooks/use-dictation');
+
+function said(transcript: string, isFinal = true) {
+ return Object.assign([{ transcript }], { isFinal });
+}
+
+function textareaAt(selectionStart: number, selectionEnd = selectionStart) {
+ const focus = vi.fn();
+ const setSelectionRange = vi.fn();
+ const textarea = {
+ selectionStart,
+ selectionEnd,
+ focus,
+ setSelectionRange,
+ } as unknown as HTMLTextAreaElement;
+
+ return { textarea, focus, setSelectionRange };
+}
+
+const updateBody = vi.fn();
+
+beforeEach(() => {
+ vi.clearAllMocks();
+});
+
+test('listens in the page language and inserts each finished phrase at the caret', () => {
+ const { textarea, focus, setSelectionRange } = textareaAt(7);
+ const dictation = useDictation({
+ body: 'Shipped today',
+ updateBody,
+ textareaRef: { current: textarea },
+ maxLength: 280,
+ });
+
+ assert.equal(dictation.isSupported, true);
+ dictation.start();
+ assert.equal(listener.lang, 'fr');
+ assert.equal(listener.continuous, true);
+ assert.deepEqual(setIsListening.mock.calls, [[true]]);
+
+ listener.onresult({
+ resultIndex: 0,
+ results: [said('the dark mode', false), said(' the dark mode ')],
+ });
+ layoutEffect();
+
+ assert.deepEqual(updateBody.mock.calls, [['Shipped the dark mode today']]);
+ assert.equal(focus.mock.calls.length, 1);
+ assert.deepEqual(setSelectionRange.mock.calls, [[21, 21]]);
+});
+
+test('ignores silence and phrases that would overflow the commit', () => {
+ const dictation = useDictation({
+ body: 'abc',
+ updateBody,
+ textareaRef: { current: textareaAt(3).textarea },
+ maxLength: 5,
+ });
+
+ dictation.start();
+ listener.onresult({
+ resultIndex: 0,
+ results: [said(' '), said('too long')],
+ });
+
+ assert.equal(updateBody.mock.calls.length, 0);
+});
+
+test('says when the microphone is blocked, but not when nothing was said', () => {
+ const dictation = useDictation({
+ body: '',
+ updateBody,
+ textareaRef: { current: null },
+ maxLength: 280,
+ });
+
+ dictation.start();
+ listener.onerror({ error: 'no-speech' });
+ listener.onerror({ error: 'not-allowed' });
+ listener.onend();
+
+ assert.deepEqual(toastError.mock.calls, [
+ ['Allow the microphone to dictate your commit.'],
+ ]);
+ assert.deepEqual(setIsListening.mock.calls, [[true], [false]]);
+});
From fdb2a4b6cf160b4728d0abed0179dcf31fbeffb2 Mon Sep 17 00:00:00 2001
From: Houssem Eddine BENABDALLAH
Date: Tue, 3 Nov 2026 20:22:20 +0100
Subject: [PATCH 2/3] docs: say in the privacy policy that dictation uses the
browser's speech recognition
---
resources/js/pages/privacy/show.tsx | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/resources/js/pages/privacy/show.tsx b/resources/js/pages/privacy/show.tsx
index f16d29a6f9..4585628057 100644
--- a/resources/js/pages/privacy/show.tsx
+++ b/resources/js/pages/privacy/show.tsx
@@ -251,6 +251,13 @@ export default function Show() {
selects which translation to display. Private messages
are not translated.
+
+ Dictating a commit uses your browser's own speech
+ recognition: we never receive your voice, only the text
+ it writes into the composer. Depending on your browser,
+ the recording may be sent to its maker, such as Google
+ or Apple, to be transcribed, under their privacy policy.
+
From 78a3a2e0542e36999db8d797eb41f3bea40b43d3 Mon Sep 17 00:00:00 2001
From: Houssem Eddine BENABDALLAH
Date: Tue, 3 Nov 2026 20:40:21 +0100
Subject: [PATCH 3/3] fix: keep every phrase heard before the composer
re-renders, drop unwritten ones when the commit is sent, and space dictation
from the next word
---
resources/js/components/dictation-button.tsx | 10 ++---
resources/js/hooks/use-dictation.ts | 22 ++++++++--
resources/js/lib/dictation.ts | 15 +++++--
tests/Unit/Dictation.test.ts | 6 +++
tests/Unit/DictationInsertion.test.tsx | 44 ++++++++++++++++++++
5 files changed, 84 insertions(+), 13 deletions(-)
diff --git a/resources/js/components/dictation-button.tsx b/resources/js/components/dictation-button.tsx
index 1276ed1aaf..0939a6188c 100644
--- a/resources/js/components/dictation-button.tsx
+++ b/resources/js/components/dictation-button.tsx
@@ -7,8 +7,8 @@ import { useDictation } from '@/hooks/use-dictation';
import { cn } from '@/lib/utils';
/**
- * Writes the commit by voice where the caret is. Hidden in browsers without speech recognition, and stops listening
- * once the commit is being sent, so nothing said after lands in the next one.
+ * Writes the commit by voice where the caret is. Hidden in browsers without speech recognition, and drops whatever
+ * wasn't written yet once the commit is being sent, so nothing lands in the next one.
*/
export function DictationButton({
body,
@@ -29,13 +29,13 @@ export function DictationButton({
textareaRef,
maxLength,
});
- const { isListening, stop } = dictation;
+ const { isListening, stop, abort } = dictation;
useEffect(() => {
if (disabled && isListening) {
- stop();
+ abort();
}
- }, [disabled, isListening, stop]);
+ }, [disabled, isListening, abort]);
if (!dictation.isSupported) {
return null;
diff --git a/resources/js/hooks/use-dictation.ts b/resources/js/hooks/use-dictation.ts
index 4badd8f58c..4609cd94db 100644
--- a/resources/js/hooks/use-dictation.ts
+++ b/resources/js/hooks/use-dictation.ts
@@ -70,6 +70,7 @@ export function useDictation({
isListening: boolean;
start: () => void;
stop: () => void;
+ abort: () => void;
} {
// Unknown while rendering on the server, so the button only appears once the page runs in the browser.
const isSupported = useSyncExternalStore(
@@ -98,20 +99,30 @@ export function useDictation({
useEffect(() => () => recognition.current?.abort(), []);
+ // Phrases can arrive before React has written the previous one, so each insertion moves the body and caret on
+ // right away for the next, instead of waiting for the render.
const insert = (transcript: string) => {
const { body, updateBody, maxLength } = latest.current;
- const element = textareaRef.current;
+ const selection =
+ caret.current === null
+ ? textareaRef.current
+ : {
+ selectionStart: caret.current,
+ selectionEnd: caret.current,
+ };
const text = dictatedText(
- body.slice(0, element?.selectionStart ?? body.length),
+ body.slice(0, selection?.selectionStart ?? body.length),
transcript,
+ body.slice(selection?.selectionEnd ?? body.length),
);
const inserted =
text === ''
? null
- : insertAtSelection(body, element, text, maxLength);
+ : insertAtSelection(body, selection, text, maxLength);
if (inserted !== null) {
caret.current = inserted.caret;
+ latest.current = { ...latest.current, body: inserted.value };
updateBody(inserted.value);
}
};
@@ -163,7 +174,10 @@ export function useDictation({
setIsListening(true);
};
+ // Keeps what was already heard, for a stop the user asked for.
const stop = () => recognition.current?.stop();
+ // Drops what wasn't written yet, for when the commit is sent and the composer is about to be cleared.
+ const abort = () => recognition.current?.abort();
- return { isSupported, isListening, start, stop };
+ return { isSupported, isListening, start, stop, abort };
}
diff --git a/resources/js/lib/dictation.ts b/resources/js/lib/dictation.ts
index cd09e8d224..b9201d0174 100644
--- a/resources/js/lib/dictation.ts
+++ b/resources/js/lib/dictation.ts
@@ -1,13 +1,20 @@
/**
- * The text to insert for what was said, given the text before the caret: the transcript trimmed, with a space in front
- * when it would otherwise stick to the previous word. Empty when nothing was said.
+ * The text to insert for what was said, given the text before and after the caret: the transcript trimmed, with a space
+ * on either side where it would otherwise stick to a word. Empty when nothing was said.
*/
-export function dictatedText(before: string, transcript: string): string {
+export function dictatedText(
+ before: string,
+ transcript: string,
+ after = '',
+): string {
const text = transcript.trim();
if (text === '') {
return '';
}
- return before === '' || /\s$/u.test(before) ? text : ` ${text}`;
+ const space = (side: string) =>
+ side === '' || /\s/u.test(side) ? '' : ' ';
+
+ return space(before.slice(-1)) + text + space(after.slice(0, 1));
}
diff --git a/tests/Unit/Dictation.test.ts b/tests/Unit/Dictation.test.ts
index 7e787ce8fc..9791bc1b5c 100644
--- a/tests/Unit/Dictation.test.ts
+++ b/tests/Unit/Dictation.test.ts
@@ -9,3 +9,9 @@ void test('dictated text is trimmed and starts a new word after the caret', () =
assert.equal(dictatedText('Finally\n', 'shipped it'), 'shipped it');
assert.equal(dictatedText('Finally', ' '), '');
});
+
+void test('dictated text before a word is kept apart from it', () => {
+ assert.equal(dictatedText('', 'Finally', 'shipped it'), 'Finally ');
+ assert.equal(dictatedText('We ', 'finally', ' shipped'), 'finally');
+ assert.equal(dictatedText('We', 'finally', 'shipped'), ' finally ');
+});
diff --git a/tests/Unit/DictationInsertion.test.tsx b/tests/Unit/DictationInsertion.test.tsx
index 04265571a4..f247a34bee 100644
--- a/tests/Unit/DictationInsertion.test.tsx
+++ b/tests/Unit/DictationInsertion.test.tsx
@@ -26,6 +26,7 @@ type Listener = {
lang: string;
continuous: boolean;
start: () => void;
+ abort: () => void;
onresult: (event: {
resultIndex: number;
results: ({ transcript: string }[] & { isFinal: boolean })[];
@@ -106,6 +107,49 @@ test('listens in the page language and inserts each finished phrase at the caret
assert.deepEqual(setSelectionRange.mock.calls, [[21, 21]]);
});
+test('keeps every phrase heard before React writes the body, in the order they were said', () => {
+ const { textarea, setSelectionRange } = textareaAt(7);
+ const dictation = useDictation({
+ body: 'Shipped today',
+ updateBody,
+ textareaRef: { current: textarea },
+ maxLength: 280,
+ });
+
+ dictation.start();
+ listener.onresult({
+ resultIndex: 0,
+ results: [said('the dark mode'), said('for everyone')],
+ });
+ listener.onresult({
+ resultIndex: 2,
+ results: [said('x'), said('x'), said('at last')],
+ });
+ layoutEffect();
+
+ assert.deepEqual(updateBody.mock.calls.at(-1), [
+ 'Shipped the dark mode for everyone at last today',
+ ]);
+ assert.deepEqual(setSelectionRange.mock.calls, [[42, 42]]);
+});
+
+test('aborts without writing what was still being heard, for when the commit is sent', () => {
+ const dictation = useDictation({
+ body: '',
+ updateBody,
+ textareaRef: { current: null },
+ maxLength: 280,
+ });
+
+ dictation.start();
+ dictation.abort();
+
+ assert.equal(
+ (listener.abort as ReturnType).mock.calls.length,
+ 1,
+ );
+});
+
test('ignores silence and phrases that would overflow the commit', () => {
const dictation = useDictation({
body: 'abc',