Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

fix: keep IME confirmation Enter from sending the chat On macOS, Safari, Chrome, and Edge fire Enter when a Japanese candidate is confirmed. That key was treated as send, so the message went out before the user finished typing. (#2450)

Wallgau5d28a2e76f32
diff --git a/frontend/app/chat/_components/chat-input.test.tsx b/frontend/app/chat/_components/chat-input.test.tsx
index c44a1b5f0..d3e4fd899 100644
--- a/frontend/app/chat/_components/chat-input.test.tsx
+++ b/frontend/app/chat/_components/chat-input.test.tsx
@@ -4,9 +4,10 @@
* The component has many dependencies; we stub the ones that would otherwise
* require a full backend or complex provider stack.
*/
-import { screen } from "@testing-library/react";
+import { fireEvent, screen } from "@testing-library/react";
import { describe, expect, it, vi } from "vitest";
import { renderWithProviders } from "@/test-utils/render";
+import type { KnowledgeFilterData } from "../_types/types";
import { ChatInput } from "./chat-input";
vi.mock("@/contexts/brand-context", async (importOriginal) => ({
@@ -21,8 +22,12 @@ vi.mock("@/hooks/use-supported-file-types", () => ({
}),
}));
+const { filtersQuery } = vi.hoisted(() => ({
+ filtersQuery: vi.fn(() => ({ data: [] as KnowledgeFilterData[] })),
+}));
+
vi.mock("@/app/api/queries/useGetAllFiltersQuery", () => ({
- useGetAllFiltersQuery: () => ({ data: [] }),
+ useGetAllFiltersQuery: filtersQuery,
}));
const defaultProps = {
@@ -43,6 +48,20 @@ const defaultProps = {
onFileSelected: vi.fn(),
};
+const docsFilter: KnowledgeFilterData = {
+ id: "docs",
+ name: "Docs",
+ description: "Documentation",
+ query_data: "{}",
+ owner: "me",
+ created_at: "",
+ updated_at: "",
+};
+
+function chatBox() {
+ return screen.getByPlaceholderText<HTMLTextAreaElement>("Ask a question...");
+}
+
describe("ChatInput", () => {
// Line 71: useSupportedFileTypes is called on every render; mounting the
// component exercises it.
@@ -51,4 +70,116 @@ describe("ChatInput", () => {
// The textarea is the primary interactive element
expect(document.body).toBeTruthy();
});
+
+ it("forwards Enter so the parent can submit", () => {
+ const onKeyDown = vi.fn();
+ renderWithProviders(<ChatInput {...defaultProps} onKeyDown={onKeyDown} />);
+
+ fireEvent.keyDown(chatBox(), { key: "Enter" });
+
+ expect(onKeyDown).toHaveBeenCalledOnce();
+ });
+
+ it("does not forward Enter that confirms an IME candidate", () => {
+ const onKeyDown = vi.fn();
+ renderWithProviders(<ChatInput {...defaultProps} onKeyDown={onKeyDown} />);
+ const box = chatBox();
+
+ fireEvent.keyDown(box, { key: "Enter", isComposing: true });
+ fireEvent.keyDown(box, { key: "Enter", keyCode: 229 });
+
+ expect(onKeyDown).not.toHaveBeenCalled();
+ });
+
+ it("does not forward the Enter Safari fires immediately after compositionend", () => {
+ const onKeyDown = vi.fn();
+ renderWithProviders(<ChatInput {...defaultProps} onKeyDown={onKeyDown} />);
+ const box = chatBox();
+
+ fireEvent.compositionStart(box);
+ fireEvent.compositionEnd(box);
+ const cancelled = fireEvent.keyDown(box, { key: "Enter" });
+
+ expect(onKeyDown).not.toHaveBeenCalled();
+ expect(cancelled).toBe(false);
+ });
+
+ it("forwards a second Enter that lands inside the IME confirmation window", () => {
+ let now = 1_000;
+ const nowSpy = vi.spyOn(performance, "now").mockImplementation(() => now);
+ const onKeyDown = vi.fn();
+ renderWithProviders(<ChatInput {...defaultProps} onKeyDown={onKeyDown} />);
+ const box = chatBox();
+
+ fireEvent.compositionEnd(box);
+ now = 1_010;
+ fireEvent.keyDown(box, { key: "Enter" });
+ fireEvent.keyDown(box, { key: "Enter" });
+
+ expect(onKeyDown).toHaveBeenCalledOnce();
+ nowSpy.mockRestore();
+ });
+
+ it("forwards Enter again once the IME confirmation window has passed", () => {
+ let now = 1_000;
+ const nowSpy = vi.spyOn(performance, "now").mockImplementation(() => now);
+ const onKeyDown = vi.fn();
+ renderWithProviders(<ChatInput {...defaultProps} onKeyDown={onKeyDown} />);
+ const box = chatBox();
+
+ fireEvent.compositionEnd(box);
+ now = 1_050;
+ fireEvent.keyDown(box, { key: "Enter" });
+
+ expect(onKeyDown).toHaveBeenCalledOnce();
+ nowSpy.mockRestore();
+ });
+
+ it("forwards Enter after blur clears a finished composition", () => {
+ const onKeyDown = vi.fn();
+ renderWithProviders(<ChatInput {...defaultProps} onKeyDown={onKeyDown} />);
+ const box = chatBox();
+
+ fireEvent.compositionEnd(box);
+ fireEvent.blur(box);
+ fireEvent.keyDown(box, { key: "Enter" });
+
+ expect(onKeyDown).toHaveBeenCalledOnce();
+ });
+
+ it("does not select a knowledge filter when Enter confirms an IME candidate", () => {
+ filtersQuery.mockReturnValue({ data: [docsFilter] });
+ const onFilterSelect = vi.fn();
+ const props = { ...defaultProps, onFilterSelect, input: "" };
+ const { rerender } = renderWithProviders(<ChatInput {...props} />);
+ const box = chatBox();
+
+ fireEvent.change(box, { target: { value: "@" } });
+ rerender(<ChatInput {...props} input="@" />);
+ box.selectionStart = 1;
+
+ fireEvent.keyDown(box, { key: "Enter", isComposing: true });
+ expect(onFilterSelect).not.toHaveBeenCalled();
+
+ fireEvent.keyDown(box, { key: "Enter" });
+ expect(onFilterSelect).toHaveBeenCalledWith(docsFilter);
+ });
+
+ it("does not select a knowledge filter when Space cycles an IME candidate", () => {
+ filtersQuery.mockReturnValue({ data: [docsFilter] });
+ const onFilterSelect = vi.fn();
+ const props = { ...defaultProps, onFilterSelect, input: "" };
+ const { rerender } = renderWithProviders(<ChatInput {...props} />);
+ const box = chatBox();
+
+ fireEvent.change(box, { target: { value: "@" } });
+ rerender(<ChatInput {...props} input="@" />);
+ box.selectionStart = 1;
+
+ fireEvent.keyDown(box, { key: " ", isComposing: true });
+ expect(onFilterSelect).not.toHaveBeenCalled();
+
+ fireEvent.keyDown(box, { key: " " });
+ expect(onFilterSelect).toHaveBeenCalledWith(docsFilter);
+ });
});
diff --git a/frontend/app/chat/_components/chat-input.tsx b/frontend/app/chat/_components/chat-input.tsx
index e2b8d1514..9b43e15f3 100644
--- a/frontend/app/chat/_components/chat-input.tsx
+++ b/frontend/app/chat/_components/chat-input.tsx
@@ -11,8 +11,10 @@ import {
} from "@/components/ui/popover";
import { useIsCloudBrand } from "@/contexts/brand-context";
import { useFileDrag } from "@/hooks/use-file-drag";
+import { useImeComposition } from "@/hooks/use-ime-composition";
import { useSupportedFileTypes } from "@/hooks/use-supported-file-types";
import type { FilterColor } from "@/lib/filter-constants";
+import type { ImeCompositionState } from "@/lib/ime-composition";
import { cn } from "@/lib/utils";
import { useGetAllFiltersQuery } from "../../api/queries/useGetAllFiltersQuery";
import type { KnowledgeFilterData } from "../_types/types";
@@ -22,6 +24,8 @@ import { SelectedKnowledgeFilter } from "./selected-knowledge-filter";
export interface ChatInputHandle {
focusInput: () => void;
clickFileInput: () => void;
+ /** Snapshot of the open or just-finished IME session, including `now`. */
+ getImeState: () => ImeCompositionState;
}
interface ChatInputProps {
@@ -34,7 +38,10 @@ interface ChatInputProps {
uploadedFile: File | null;
onSubmit: (e: React.FormEvent) => void;
onChange: (value: string) => void;
- onKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
+ onKeyDown: (
+ e: React.KeyboardEvent<HTMLTextAreaElement>,
+ imeState: ImeCompositionState,
+ ) => void;
onFilterSelect: (filter: KnowledgeFilterData | null) => void;
onFilePickerClick: () => void;
setSelectedFilter: (filter: KnowledgeFilterData | null) => void;
@@ -64,6 +71,7 @@ export function ChatInput({
}: ChatInputProps & { ref?: React.Ref<ChatInputHandle> }) {
const inputRef = useRef<HTMLTextAreaElement>(null);
const fileInputRef = useRef<HTMLInputElement>(null);
+ const ime = useImeComposition();
const [isWrapped, setIsWrapped] = useState(false);
const isMultiline = input.includes("\n") || isWrapped;
const isDragging = useFileDrag();
@@ -108,6 +116,7 @@ export function ChatInput({
clickFileInput: () => {
fileInputRef.current?.click();
},
+ getImeState: () => ime.readState(),
}));
const handleFilePickerChange = (e: React.ChangeEvent<HTMLInputElement>) => {
@@ -258,6 +267,14 @@ export function ChatInput({
};
const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+ // One snapshot for this keydown, shared with the parent submit handler.
+ // Confirming a Kanji (or other IME) candidate fires Enter and must not
+ // select a filter or submit the message.
+ const imeState = ime.readState();
+ if (ime.blockEnter(e, imeState)) {
+ return;
+ }
+
if (isFilterDropdownOpen) {
if (e.key === "Escape") {
e.preventDefault();
@@ -299,6 +316,10 @@ export function ChatInput({
}
if (e.key === " ") {
+ // Space cycles IME candidates. A space after compositionend is a real space.
+ if (ime.isImeCandidateKey(e.nativeEvent)) {
+ return;
+ }
// Select filter on space if we're typing an @ mention
const cursorPos = e.currentTarget.selectionStart || 0;
const textBeforeCursor = input.slice(0, cursorPos);
@@ -314,7 +335,7 @@ export function ChatInput({
}
// Pass through to parent onKeyDown for other key handling
- onKeyDown(e);
+ onKeyDown(e, imeState);
};
return (
@@ -418,6 +439,7 @@ export function ChatInput({
ref={inputRef}
value={input}
onChange={handleChange}
+ {...ime.inputProps}
onKeyDown={handleKeyDown}
maxRows={7}
autoComplete="off"
diff --git a/frontend/app/chat/page.test.tsx b/frontend/app/chat/page.test.tsx
index 79e8b17ba..8824ba817 100644
--- a/frontend/app/chat/page.test.tsx
+++ b/frontend/app/chat/page.test.tsx
@@ -11,7 +11,7 @@
* ChatPage is not exported; we mount via the default export ProtectedChatPage
* and stub ProtectedRoute to a passthrough.
*/
-import { act, screen, waitFor } from "@testing-library/react";
+import { act, fireEvent, screen, waitFor } from "@testing-library/react";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { authPresets, makeUser, withAuth } from "@/test-utils/fixtures/auth";
import { renderWithProviders } from "@/test-utils/render";
@@ -127,12 +127,42 @@ vi.mock("@/app/chat/_components/assistant-message", () => ({
),
}));
+const { imeStateHolder, submitSpy } = vi.hoisted(() => ({
+ imeStateHolder: {
+ current: { composing: false, compositionEndedAt: 0, now: 0 },
+ },
+ submitSpy: vi.fn((event: { preventDefault: () => void }) => {
+ event.preventDefault();
+ }),
+}));
+
vi.mock("@/app/chat/_components/chat-input", () => {
- const { forwardRef } = require("react");
+ const { forwardRef, useImperativeHandle } = require("react");
return {
- ChatInput: forwardRef((_props: unknown, _ref: unknown) => (
- <div data-testid="chat-input" />
- )),
+ ChatInput: forwardRef(
+ (
+ props: {
+ onChange?: (value: string) => void;
+ onKeyDown?: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
+ },
+ ref: React.Ref<{ getImeState: () => unknown }>,
+ ) => {
+ useImperativeHandle(ref, () => ({
+ focusInput() {},
+ clickFileInput() {},
+ getImeState: () => imeStateHolder.current,
+ }));
+ return (
+ <form onSubmit={submitSpy}>
+ <textarea
+ data-testid="chat-input"
+ onChange={(e) => props.onChange?.(e.target.value)}
+ onKeyDown={props.onKeyDown}
+ />
+ </form>
+ );
+ },
+ ),
};
});
@@ -155,7 +185,15 @@ import ProtectedChatPage from "./page";
// ── Tests ────────────────────────────────────────────────────────────────────
describe("ChatPage — coverage for diff-flagged lines", () => {
- beforeEach(() => vi.useFakeTimers());
+ beforeEach(() => {
+ vi.useFakeTimers();
+ imeStateHolder.current = {
+ composing: false,
+ compositionEndedAt: 0,
+ now: 0,
+ };
+ submitSpy.mockClear();
+ });
afterEach(() => {
vi.useRealTimers();
vi.restoreAllMocks();
@@ -216,6 +254,51 @@ describe("ChatPage — coverage for diff-flagged lines", () => {
});
});
+ it("does not submit when Enter confirms an IME candidate", () => {
+ vi.useRealTimers();
+ renderWithProviders(<ProtectedChatPage />, {
+ providers: ["auth"],
+ auth: authPresets.noAuthMode,
+ });
+ const input = screen.getByTestId("chat-input");
+
+ expect(fireEvent.keyDown(input, { key: "Enter", isComposing: true })).toBe(
+ true,
+ );
+ expect(fireEvent.keyDown(input, { key: "Enter", keyCode: 229 })).toBe(true);
+ });
+
+ it("does not submit the Enter Safari fires just after composition ends", () => {
+ vi.useRealTimers();
+ imeStateHolder.current = {
+ composing: false,
+ compositionEndedAt: 1_000,
+ now: 1_010,
+ };
+ renderWithProviders(<ProtectedChatPage />, {
+ providers: ["auth"],
+ auth: authPresets.noAuthMode,
+ });
+ const input = screen.getByTestId("chat-input");
+ fireEvent.change(input, { target: { value: "日本語" } });
+
+ expect(fireEvent.keyDown(input, { key: "Enter" })).toBe(false);
+ expect(submitSpy).not.toHaveBeenCalled();
+ });
+
+ it("prevents a newline and submits when Enter is not an IME confirmation", () => {
+ vi.useRealTimers();
+ renderWithProviders(<ProtectedChatPage />, {
+ providers: ["auth"],
+ auth: authPresets.noAuthMode,
+ });
+ const input = screen.getByTestId("chat-input");
+ fireEvent.change(input, { target: { value: "hello" } });
+
+ expect(fireEvent.keyDown(input, { key: "Enter" })).toBe(false);
+ expect(submitSpy).toHaveBeenCalledOnce();
+ });
+
it("replaces the placeholder greeting after mount in no-auth mode", async () => {
vi.useRealTimers();
renderWithProviders(<ProtectedChatPage />, {
diff --git a/frontend/app/chat/page.tsx b/frontend/app/chat/page.tsx
index 0f7444fe7..edc7de182 100644
--- a/frontend/app/chat/page.tsx
+++ b/frontend/app/chat/page.tsx
@@ -22,6 +22,11 @@ import {
} from "@/lib/chat-stream-errors";
import { FILE_CONFIRMATION, FILES_REGEX } from "@/lib/constants";
import { buildSearchPayloadFilters } from "@/lib/filter-normalization";
+import {
+ EMPTY_IME_STATE,
+ handleInputKeyDown,
+ type ImeCompositionState,
+} from "@/lib/ime-composition";
import { uploadFileForContext } from "@/lib/upload-utils";
import { resolveDisplayName } from "@/lib/user";
import { cn } from "@/lib/utils";
@@ -961,6 +966,38 @@ function ChatPage() {
handleSendMessage(suggestion);
};
+ const handleChatInputKeyDown = (
+ e: React.KeyboardEvent<HTMLTextAreaElement>,
+ imeState?: ImeCompositionState,
+ ) => {
+ // Handle backspace for filter clearing
+ if (e.key === "Backspace" && selectedFilter && input.trim() === "") {
+ e.preventDefault();
+ if (isFilterHighlighted) {
+ // Second backspace - remove the filter
+ setConversationFilter(null);
+ setIsFilterHighlighted(false);
+ } else {
+ // First backspace - highlight the filter
+ setIsFilterHighlighted(true);
+ }
+ return;
+ }
+
+ handleInputKeyDown(
+ e,
+ imeState ?? chatInputRef.current?.getImeState() ?? EMPTY_IME_STATE,
+ () => {
+ if (input.trim() && !loading) {
+ const form = e.currentTarget.closest("form");
+ if (form) {
+ form.requestSubmit();
+ }
+ }
+ },
+ );
+ };
+
return (
<>
{/* Full-screen drag & drop overlay */}
@@ -1180,37 +1217,7 @@ function ChatPage() {
uploadedFile={uploadedFile}
onSubmit={handleSubmit}
onChange={setInput}
- onKeyDown={(e) => {
- // Handle backspace for filter clearing
- if (
- e.key === "Backspace" &&
- selectedFilter &&
- input.trim() === ""
- ) {
- e.preventDefault();
- if (isFilterHighlighted) {
- // Second backspace - remove the filter
- setConversationFilter(null);
- setIsFilterHighlighted(false);
- } else {
- // First backspace - highlight the filter
- setIsFilterHighlighted(true);
- }
- return;
- }
-
- // Handle Enter key for form submission
- if (e.key === "Enter" && !e.shiftKey) {
- e.preventDefault();
- if (input.trim() && !loading) {
- // Trigger form submission by finding the form and calling submit
- const form = e.currentTarget.closest("form");
- if (form) {
- form.requestSubmit();
- }
- }
- }
- }}
+ onKeyDown={handleChatInputKeyDown}
ingestViaChat={settings?.ingest_via_chat ?? false}
onFilterSelect={handleFilterSelect}
onFilePickerClick={handleFilePickerClick}
diff --git a/frontend/hooks/use-ime-composition.test.ts b/frontend/hooks/use-ime-composition.test.ts
new file mode 100644
index 000000000..eae776489
--- /dev/null
+++ b/frontend/hooks/use-ime-composition.test.ts
@@ -0,0 +1,105 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useImeComposition } from "./use-ime-composition";
+
+const plainEnter = { isComposing: false, keyCode: 13 };
+
+function enterEvent(nativeEvent = plainEnter) {
+ return {
+ key: "Enter",
+ shiftKey: false,
+ preventDefault: vi.fn(),
+ nativeEvent,
+ };
+}
+
+describe("useImeComposition", () => {
+ it("blocks the Enter Safari fires just after composition ends, then allows a later Enter", () => {
+ let now = 1_000;
+ const nowSpy = vi.spyOn(performance, "now").mockImplementation(() => now);
+ const { result } = renderHook(() => useImeComposition());
+
+ result.current.inputProps.onCompositionStart();
+ expect(result.current.readState().composing).toBe(true);
+ expect(result.current.blockEnter(enterEvent())).toBe(true);
+
+ now = 1_020;
+ result.current.inputProps.onCompositionEnd();
+ const leftover = enterEvent();
+ expect(result.current.blockEnter(leftover)).toBe(true);
+ expect(leftover.preventDefault).toHaveBeenCalledOnce();
+
+ now = 1_080;
+ const send = enterEvent();
+ expect(result.current.blockEnter(send)).toBe(false);
+ expect(send.preventDefault).not.toHaveBeenCalled();
+
+ nowSpy.mockRestore();
+ });
+
+ it("lets a second Enter send inside the Safari confirmation window", () => {
+ let now = 1_000;
+ const nowSpy = vi.spyOn(performance, "now").mockImplementation(() => now);
+ const onSubmit = vi.fn();
+ const { result } = renderHook(() => useImeComposition(onSubmit));
+
+ result.current.inputProps.onCompositionEnd();
+ now = 1_010;
+ const confirm = enterEvent();
+ result.current.handleKeyDown(confirm);
+ expect(onSubmit).not.toHaveBeenCalled();
+ expect(confirm.preventDefault).toHaveBeenCalledOnce();
+
+ const send = enterEvent();
+ result.current.handleKeyDown(send);
+ expect(send.preventDefault).toHaveBeenCalledOnce();
+ expect(onSubmit).toHaveBeenCalledOnce();
+
+ nowSpy.mockRestore();
+ });
+
+ it("clears a finished composition on blur so the next Enter sends", () => {
+ const { result } = renderHook(() => useImeComposition());
+
+ result.current.inputProps.onCompositionEnd();
+ result.current.inputProps.onBlur();
+
+ expect(result.current.readState()).toEqual({
+ composing: false,
+ compositionEndedAt: 0,
+ now: 0,
+ });
+ expect(result.current.blockEnter(enterEvent())).toBe(false);
+ });
+
+ it("submits on Enter through the props a future field spreads on", () => {
+ const onSubmit = vi.fn();
+ const { result, rerender } = renderHook(
+ ({ submit }) => useImeComposition(submit),
+ { initialProps: { submit: onSubmit } },
+ );
+
+ const send = enterEvent();
+ result.current.inputProps.onKeyDown(send);
+ expect(send.preventDefault).toHaveBeenCalledOnce();
+ expect(onSubmit).toHaveBeenCalledOnce();
+
+ const nextSubmit = vi.fn();
+ rerender({ submit: nextSubmit });
+ result.current.inputProps.onCompositionStart();
+ result.current.handleKeyDown(enterEvent());
+ expect(nextSubmit).not.toHaveBeenCalled();
+ });
+
+ it("treats Space during composition as a candidate key and a later Space as a real space", () => {
+ const { result } = renderHook(() => useImeComposition());
+
+ result.current.inputProps.onCompositionStart();
+ expect(
+ result.current.isImeCandidateKey({ isComposing: true, keyCode: 32 }),
+ ).toBe(true);
+
+ result.current.inputProps.onCompositionEnd();
+ expect(result.current.isImeCandidateKey(plainEnter)).toBe(false);
+ });
+});
diff --git a/frontend/hooks/use-ime-composition.ts b/frontend/hooks/use-ime-composition.ts
new file mode 100644
index 000000000..eccb99e9b
--- /dev/null
+++ b/frontend/hooks/use-ime-composition.ts
@@ -0,0 +1,106 @@
+import { useCallback, useRef } from "react";
+import {
+ blockImeEnter,
+ handleInputKeyDown,
+ type ImeCompositionState,
+ type ImeEnterEvent,
+ type ImeKeyEvent,
+ isImeCompositionEvent,
+ shouldCancelImeEnter,
+} from "@/lib/ime-composition";
+
+/**
+ * Tracks an IME composition session for one text field and submits on Enter.
+ *
+ * ```tsx
+ * const ime = useImeComposition(onSubmit);
+ * <textarea {...ime.inputProps} />
+ * ```
+ *
+ * A field that also handles other keys calls `handleKeyDown` after its own
+ * logic. `isImeCandidateKey` is for keys that cycle a candidate, such as
+ * Space. A space after composition ends is a real space, so that check
+ * ignores Safari's Enter window.
+ */
+export function useImeComposition(onSubmit?: () => void) {
+ const onSubmitRef = useRef(onSubmit);
+ onSubmitRef.current = onSubmit;
+ const isComposingRef = useRef(false);
+ const compositionEndedAtRef = useRef(0);
+
+ const readState = useCallback((): ImeCompositionState => {
+ const compositionEndedAt = compositionEndedAtRef.current;
+ return {
+ composing: isComposingRef.current,
+ compositionEndedAt,
+ now: compositionEndedAt > 0 ? performance.now() : 0,
+ };
+ }, []);
+
+ const onCompositionStart = useCallback(() => {
+ isComposingRef.current = true;
+ }, []);
+
+ const onCompositionEnd = useCallback(() => {
+ isComposingRef.current = false;
+ compositionEndedAtRef.current = performance.now();
+ }, []);
+
+ const onBlur = useCallback(() => {
+ isComposingRef.current = false;
+ compositionEndedAtRef.current = 0;
+ }, []);
+
+ // Safari's confirming Enter is identified by time since compositionend.
+ // Consume that window on the first Enter so a second press can send.
+ const releaseSafariEnter = useCallback(
+ (event: ImeEnterEvent, state: ImeCompositionState) => {
+ if (
+ event.key === "Enter" &&
+ shouldCancelImeEnter(event.nativeEvent, state)
+ ) {
+ compositionEndedAtRef.current = 0;
+ }
+ },
+ [],
+ );
+
+ const blockEnter = useCallback(
+ (event: ImeEnterEvent, state?: ImeCompositionState) => {
+ const snapshot = state ?? readState();
+ const blocked = blockImeEnter(event, snapshot);
+ if (blocked) releaseSafariEnter(event, snapshot);
+ return blocked;
+ },
+ [readState, releaseSafariEnter],
+ );
+
+ const isImeCandidateKey = useCallback((event: ImeKeyEvent) => {
+ return isImeCompositionEvent(event, {
+ composing: isComposingRef.current,
+ compositionEndedAt: 0,
+ });
+ }, []);
+
+ const handleKeyDown = useCallback(
+ (event: ImeEnterEvent) => {
+ const state = readState();
+ handleInputKeyDown(event, state, () => onSubmitRef.current?.());
+ releaseSafariEnter(event, state);
+ },
+ [readState, releaseSafariEnter],
+ );
+
+ return {
+ inputProps: {
+ onCompositionStart,
+ onCompositionEnd,
+ onBlur,
+ onKeyDown: handleKeyDown,
+ },
+ readState,
+ blockEnter,
+ isImeCandidateKey,
+ handleKeyDown,
+ };
+}
diff --git a/frontend/lib/ime-composition.test.ts b/frontend/lib/ime-composition.test.ts
new file mode 100644
index 000000000..eb384e3b8
--- /dev/null
+++ b/frontend/lib/ime-composition.test.ts
@@ -0,0 +1,182 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+ blockImeEnter,
+ handleInputKeyDown,
+ IME_PROCESS_KEY_CODE,
+ isImeCompositionEvent,
+ SAFARI_IME_ENTER_WINDOW_MS,
+ shouldCancelImeEnter,
+} from "./ime-composition";
+
+const plainEnter = { isComposing: false, keyCode: 13 };
+const idle = { composing: false, compositionEndedAt: 0, now: 1_000 };
+
+function enterEvent(
+ nativeEvent: { isComposing: boolean; keyCode: number },
+ shiftKey = false,
+) {
+ return {
+ key: "Enter",
+ shiftKey,
+ preventDefault: vi.fn(),
+ nativeEvent,
+ };
+}
+
+describe("isImeCompositionEvent", () => {
+ it("treats a normal Enter as a send", () => {
+ expect(isImeCompositionEvent(plainEnter, idle)).toBe(false);
+ });
+
+ it("treats Enter during an open composition as IME confirmation", () => {
+ expect(
+ isImeCompositionEvent({ isComposing: true, keyCode: 13 }, idle),
+ ).toBe(true);
+ expect(
+ isImeCompositionEvent(plainEnter, { ...idle, composing: true }),
+ ).toBe(true);
+ });
+
+ it("treats the IME processing key as confirmation", () => {
+ expect(
+ isImeCompositionEvent(
+ { isComposing: false, keyCode: IME_PROCESS_KEY_CODE },
+ idle,
+ ),
+ ).toBe(true);
+ });
+
+ it("treats the Enter Safari fires just after compositionend as confirmation", () => {
+ const endedAt = 1_000;
+ expect(
+ isImeCompositionEvent(plainEnter, {
+ composing: false,
+ compositionEndedAt: endedAt,
+ now: endedAt + SAFARI_IME_ENTER_WINDOW_MS - 1,
+ }),
+ ).toBe(true);
+ });
+
+ it("lets a later Enter send", () => {
+ const endedAt = 1_000;
+ expect(
+ isImeCompositionEvent(plainEnter, {
+ composing: false,
+ compositionEndedAt: endedAt,
+ now: endedAt + SAFARI_IME_ENTER_WINDOW_MS,
+ }),
+ ).toBe(false);
+ });
+});
+
+describe("shouldCancelImeEnter", () => {
+ it("does not cancel Enter while the IME session is still open", () => {
+ expect(
+ shouldCancelImeEnter(
+ { isComposing: true, keyCode: 13 },
+ { composing: false, compositionEndedAt: 1_000, now: 1_010 },
+ ),
+ ).toBe(false);
+ expect(
+ shouldCancelImeEnter(plainEnter, {
+ composing: true,
+ compositionEndedAt: 1_000,
+ now: 1_010,
+ }),
+ ).toBe(false);
+ });
+
+ it("cancels the leftover Enter after compositionend so it does not insert a newline", () => {
+ expect(
+ shouldCancelImeEnter(plainEnter, {
+ composing: false,
+ compositionEndedAt: 1_000,
+ now: 1_010,
+ }),
+ ).toBe(true);
+ });
+});
+
+describe("blockImeEnter", () => {
+ it("leaves a normal Enter for the caller to submit", () => {
+ const event = enterEvent(plainEnter);
+ expect(blockImeEnter(event, idle)).toBe(false);
+ expect(event.preventDefault).not.toHaveBeenCalled();
+ });
+
+ it("blocks Enter during an open composition without dropping the candidate", () => {
+ const event = enterEvent({ isComposing: true, keyCode: 13 });
+ expect(blockImeEnter(event, idle)).toBe(true);
+ expect(event.preventDefault).not.toHaveBeenCalled();
+ });
+
+ it("blocks and cancels the leftover Enter Safari fires after compositionend", () => {
+ const event = enterEvent(plainEnter);
+ expect(
+ blockImeEnter(event, {
+ composing: false,
+ compositionEndedAt: 1_000,
+ now: 1_010,
+ }),
+ ).toBe(true);
+ expect(event.preventDefault).toHaveBeenCalledOnce();
+ });
+
+ it("blocks Shift+Enter during that window without cancelling the newline", () => {
+ const event = enterEvent(plainEnter, true);
+ expect(
+ blockImeEnter(event, {
+ composing: false,
+ compositionEndedAt: 1_000,
+ now: 1_010,
+ }),
+ ).toBe(true);
+ expect(event.preventDefault).not.toHaveBeenCalled();
+ });
+});
+
+describe("handleInputKeyDown", () => {
+ it("submits a normal Enter and blocks the newline", () => {
+ const event = enterEvent(plainEnter);
+ const onSubmit = vi.fn();
+
+ handleInputKeyDown(event, idle, onSubmit);
+
+ expect(event.preventDefault).toHaveBeenCalledOnce();
+ expect(onSubmit).toHaveBeenCalledOnce();
+ });
+
+ it("does not submit Enter that confirms an IME candidate", () => {
+ const event = enterEvent({ isComposing: true, keyCode: 13 });
+ const onSubmit = vi.fn();
+
+ handleInputKeyDown(event, idle, onSubmit);
+
+ expect(onSubmit).not.toHaveBeenCalled();
+ expect(event.preventDefault).not.toHaveBeenCalled();
+ });
+
+ it("does not submit the leftover Safari Enter", () => {
+ const event = enterEvent(plainEnter);
+ const onSubmit = vi.fn();
+
+ handleInputKeyDown(
+ event,
+ { composing: false, compositionEndedAt: 1_000, now: 1_010 },
+ onSubmit,
+ );
+
+ expect(onSubmit).not.toHaveBeenCalled();
+ expect(event.preventDefault).toHaveBeenCalledOnce();
+ });
+
+ it("leaves Shift+Enter as a newline", () => {
+ const event = enterEvent(plainEnter, true);
+ const onSubmit = vi.fn();
+
+ handleInputKeyDown(event, idle, onSubmit);
+
+ expect(onSubmit).not.toHaveBeenCalled();
+ expect(event.preventDefault).not.toHaveBeenCalled();
+ });
+});
diff --git a/frontend/lib/ime-composition.ts b/frontend/lib/ime-composition.ts
new file mode 100644
index 000000000..5be44a422
--- /dev/null
+++ b/frontend/lib/ime-composition.ts
@@ -0,0 +1,112 @@
+/**
+ * Detect Enter keystrokes that belong to an IME composition session
+ * (Japanese, Chinese, Korean) so they confirm a candidate instead of
+ * submitting chat or picking a knowledge filter.
+ *
+ * Chrome and Edge on macOS fire keydown with isComposing still true.
+ * Firefox does not fire that keydown at all. Safari fires compositionend
+ * first, so the confirming Enter arrives with isComposing already false
+ * (https://bugs.webkit.org/show_bug.cgi?id=165004). That leftover keydown
+ * is a few milliseconds after compositionend; a deliberate send is not.
+ *
+ * A text field tracks the session with `useImeComposition` and calls
+ * `blockImeEnter` before treating Enter as submit.
+ */
+
+/** IME processing key. Never produced by a physical key. */
+export const IME_PROCESS_KEY_CODE = 229;
+
+/** Window that covers Safari's post-compositionend Enter, not a human keypress. */
+export const SAFARI_IME_ENTER_WINDOW_MS = 50;
+
+export type ImeKeyEvent = {
+ isComposing: boolean;
+ keyCode: number;
+};
+
+export type ImeCompositionState = {
+ composing: boolean;
+ compositionEndedAt: number;
+ now?: number;
+};
+
+export type ImeEnterEvent = {
+ key: string;
+ shiftKey: boolean;
+ preventDefault: () => void;
+ nativeEvent: ImeKeyEvent;
+};
+
+export const EMPTY_IME_STATE: ImeCompositionState = {
+ composing: false,
+ compositionEndedAt: 0,
+};
+
+function isWithinSafariImeWindow(state: ImeCompositionState): boolean {
+ if (state.compositionEndedAt <= 0) return false;
+ const now = state.now ?? performance.now();
+ const elapsed = now - state.compositionEndedAt;
+ return elapsed >= 0 && elapsed < SAFARI_IME_ENTER_WINDOW_MS;
+}
+
+export function isImeCompositionEvent(
+ event: ImeKeyEvent,
+ state: ImeCompositionState = EMPTY_IME_STATE,
+): boolean {
+ if (
+ event.isComposing ||
+ state.composing ||
+ event.keyCode === IME_PROCESS_KEY_CODE
+ ) {
+ return true;
+ }
+ return isWithinSafariImeWindow(state);
+}
+
+/**
+ * The Enter that follows compositionend is an ordinary key to the textarea
+ * and would insert a newline. Cancelling it while the IME is still open
+ * drops the candidate, so only the leftover post-composition key is cancelled.
+ */
+export function shouldCancelImeEnter(
+ event: ImeKeyEvent,
+ state: ImeCompositionState,
+): boolean {
+ if (event.isComposing || state.composing) return false;
+ return isWithinSafariImeWindow(state);
+}
+
+/**
+ * Returns true when this Enter confirms an IME candidate and must not submit.
+ * Cancels the leftover Safari Enter so it does not insert a newline.
+ */
+export function blockImeEnter(
+ event: ImeEnterEvent,
+ state: ImeCompositionState = EMPTY_IME_STATE,
+): boolean {
+ if (
+ event.key !== "Enter" ||
+ !isImeCompositionEvent(event.nativeEvent, state)
+ ) {
+ return false;
+ }
+ if (!event.shiftKey && shouldCancelImeEnter(event.nativeEvent, state)) {
+ event.preventDefault();
+ }
+ return true;
+}
+
+/**
+ * Enter submits. Shift+Enter inserts a newline. An IME confirmation Enter
+ * does neither. Call this from any text field that sends on Enter.
+ */
+export function handleInputKeyDown(
+ event: ImeEnterEvent,
+ state: ImeCompositionState = EMPTY_IME_STATE,
+ onSubmit?: () => void,
+): void {
+ if (event.key !== "Enter" || event.shiftKey) return;
+ if (blockImeEnter(event, state)) return;
+ event.preventDefault();
+ onSubmit?.();
+}