fix(data-integrity): keep controlled value sync atomic

src/components/CwlEditor.controlledValueComposition.test.tsx

@@ -0,0 +1,90 @@
+import type { Editor } from '@tiptap/react';
+import { act, cleanup, fireEvent, render, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { CwlEditor } from './CwlEditor.js';
+
+afterEach(cleanup);
+
+describe('CwlEditor controlled value during composition', () => {
+  it('defers host replacement until composition ends and applies the latest value', async () => {
+    let editor: Editor | undefined;
+    const captureEditor = (instance: Editor) => {
+      editor = instance;
+    };
+
+    const { rerender } = render(
+      <CwlEditor mode="markdown" value="Original" onReady={captureEditor} />,
+    );
+    await waitFor(() => expect(editor).toBeTruthy());
+
+    const editable = document.querySelector('.ProseMirror') as HTMLElement;
+    fireEvent.compositionStart(editable, { data: '' });
+    expect(editor!.view.composing).toBe(true);
+
+    await act(async () => {
+      rerender(
+        <CwlEditor mode="markdown" value="First host value" onReady={captureEditor} />,
+      );
+    });
+    expect(editor!.view.composing).toBe(true);
+    expect(editor!.getText()).toBe('Original');
+
+    await act(async () => {
+      rerender(
+        <CwlEditor mode="markdown" value="Latest host value" onReady={captureEditor} />,
+      );
+    });
+    expect(editor!.view.composing).toBe(true);
+    expect(editor!.getText()).toBe('Original');
+
+    fireEvent.compositionEnd(editable, { data: '' });
+
+    await waitFor(() => {
+      expect(editor!.view.composing).toBe(false);
+      expect(editor!.getText()).toBe('Latest host value');
+    });
+  });
+
+  it('keeps intermediate composition text out of document snapshot callbacks', async () => {
+    let editor: Editor | undefined;
+    const onChange = vi.fn();
+    const onDocumentChange = vi.fn();
+
+    render(
+      <CwlEditor
+        mode="markdown"
+        defaultValue="Original"
+        onChange={onChange}
+        onDocumentChange={onDocumentChange}
+        onReady={(instance) => {
+          editor = instance;
+        }}
+      />,
+    );
+    await waitFor(() => expect(editor).toBeTruthy());
+
+    const editable = document.querySelector('.ProseMirror') as HTMLElement;
+    fireEvent.compositionStart(editable, { data: '' });
+    expect(editor!.view.composing).toBe(true);
+
+    act(() => {
+      editor!.chain().focus('end').insertContent(' composing').run();
+    });
+
+    expect(editor!.getText()).toBe('Original composing');
+    expect(onChange).toHaveBeenLastCalledWith('Original composing');
+    expect(onDocumentChange).not.toHaveBeenCalled();
+
+    fireEvent.compositionEnd(editable, { data: '' });
+    await waitFor(() => expect(editor!.view.composing).toBe(false));
+
+    act(() => {
+      editor!.chain().focus('end').insertContent(' committed').run();
+    });
+
+    expect(onDocumentChange).toHaveBeenCalledTimes(1);
+    expect(onDocumentChange.mock.calls[0]![0].snapshot.value).toBe(
+      'Original composing committed',
+    );
+  });
+});

src/components/CwlEditor.editabilityComposition.test.tsx

@@ -0,0 +1,32 @@
+import { cleanup, fireEvent, render, waitFor } from '@testing-library/react';
+import type { Editor } from '@tiptap/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { CwlEditor } from './CwlEditor.js';
+
+afterEach(cleanup);
+
+describe('CwlEditor editability transition during composition', () => {
+  it('clears local composition state before revoking edit authority', async () => {
+    let editor: Editor | undefined;
+    const captureEditor = (instance: Editor) => {
+      editor = instance;
+    };
+
+    const { rerender } = render(
+      <CwlEditor defaultValue="기준" editable onReady={captureEditor} />,
+    );
+    await waitFor(() => expect(editor).toBeTruthy());
+
+    const editable = document.querySelector('.ProseMirror') as HTMLElement;
+    fireEvent.compositionStart(editable, { data: '' });
+    expect(editor!.view.composing).toBe(true);
+
+    rerender(
+      <CwlEditor defaultValue="기준" editable={false} onReady={captureEditor} />,
+    );
+
+    await waitFor(() => expect(editor!.isEditable).toBe(false));
+    expect(editor!.view.composing).toBe(false);
+    expect(editor!.getText()).toBe('기준');
+  });
+});

src/components/CwlEditor.runtimeEditable.test.tsx

@@ -0,0 +1,23 @@
+// @vitest-environment node
+
+import { renderToString } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import { CwlEditor } from './CwlEditor.js';
+
+describe('standalone editor editable runtime contract', () => {
+  it('rejects a non-boolean editable state instead of coercing it into edit authority', () => {
+    expect(() =>
+      renderToString(
+        <CwlEditor editable={'false' as unknown as boolean} />,
+      ),
+    ).toThrowError(
+      new RangeError('editor editable state must be a boolean when provided'),
+    );
+  });
+
+  it('preserves omitted, explicitly editable, and explicitly read-only states', () => {
+    expect(() => renderToString(<CwlEditor />)).not.toThrow();
+    expect(() => renderToString(<CwlEditor editable />)).not.toThrow();
+    expect(() => renderToString(<CwlEditor editable={false} />)).not.toThrow();
+  });
+});

src/components/CwlEditor.runtimeToolbarVisibility.test.tsx

@@ -0,0 +1,25 @@
+// @vitest-environment node
+
+import { renderToString } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import { CwlEditor } from './CwlEditor.js';
+
+describe('standalone editor toolbar visibility runtime contract', () => {
+  it('rejects a non-boolean toolbar visibility state instead of coercing it', () => {
+    expect(() =>
+      renderToString(
+        <CwlEditor hideToolbar={'false' as unknown as boolean} />,
+      ),
+    ).toThrowError(
+      new RangeError(
+        'editor toolbar visibility state must be a boolean when provided',
+      ),
+    );
+  });
+
+  it('preserves omitted, visible, and hidden toolbar states', () => {
+    expect(() => renderToString(<CwlEditor />)).not.toThrow();
+    expect(() => renderToString(<CwlEditor hideToolbar={false} />)).not.toThrow();
+    expect(() => renderToString(<CwlEditor hideToolbar />)).not.toThrow();
+  });
+});

src/components/CwlEditor.tsx

@@ -14,6 +14,7 @@ import {
   buildEditorAccessibilityAttributes,
   normalizeEditorPlaceholder,
 } from './editorAccessibility.js';
+import { synchronizeControlledEditorValue } from './editorControlledValueSync.js';
 import { createEditorDocumentSnapshot } from './editorDocumentSnapshot.js';
 import { applyEditorFormReset } from './editorFormReset.js';
 import { editorHtmlToValue, editorValueToHtml } from './editorSerialization.js';
@@ -65,9 +66,32 @@ export const CwlEditor = forwardRef<CwlEditorHandle, CwlEditorProps>(
     },
     ref,
   ) {
+    if (value !== undefined && typeof value !== 'string') {
+      throw new RangeError('editor value must be a string when provided');
+    }
+    if (defaultValue !== undefined && typeof defaultValue !== 'string') {
+      throw new RangeError(
+        'editor default value must be a string when provided',
+      );
+    }
+    if (formResetValue !== undefined && typeof formResetValue !== 'string') {
+      throw new RangeError(
+        'editor form reset value must be a string when provided',
+      );
+    }
+    if (typeof editable !== 'boolean') {
+      throw new RangeError('editor editable state must be a boolean when provided');
+    }
+    if (typeof hideToolbar !== 'boolean') {
+      throw new RangeError(
+        'editor toolbar visibility state must be a boolean when provided',
+      );
+    }
+
     const isControlled = value !== undefined;
     const selectedDocumentValue = value ?? defaultValue ?? '';
     const emittingRef = useRef(false);
+    const compositionActiveRef = useRef(false);
     const editorInstanceRef = useRef<Editor | null>(null);
     const modeRef = useLatestRef(mode);
     const onChangeRef = useLatestRef(onChange);
@@ -144,6 +168,7 @@ export const CwlEditor = forwardRef<CwlEditorHandle, CwlEditorProps>(
       },
       onDestroy: () => {
         const instance = editorInstanceRef.current!;
+        compositionActiveRef.current = false;
         onDestroyRef.current?.(instance);
         editorInstanceRef.current = null;
       },
@@ -153,7 +178,11 @@ export const CwlEditor = forwardRef<CwlEditorHandle, CwlEditorProps>(
         if (!valueListener && !snapshotListener) return;
         emittingRef.current = true;
         try {
-          if (snapshotListener) {
+          if (
+            snapshotListener &&
+            !compositionActiveRef.current &&
+            !instance.view.composing
+          ) {
             const snapshot = createEditorDocumentSnapshot(
               instance,
               modeRef.current,
@@ -193,7 +222,38 @@ export const CwlEditor = forwardRef<CwlEditorHandle, CwlEditorProps>(
     useEditorHandle(ref, editor, modeRef);
 
     useEffect(() => {
-      editor?.setEditable(editable);
+      if (!editor) return;
+      const editableElement = editor.view.dom;
+      const beginComposition = () => {
+        compositionActiveRef.current = true;
+      };
+      const finishComposition = () => {
+        queueMicrotask(() => {
+          compositionActiveRef.current = false;
+        });
+      };
+
+      editableElement.addEventListener('compositionstart', beginComposition);
+      editableElement.addEventListener('compositionend', finishComposition);
+      return () => {
+        editableElement.removeEventListener('compositionstart', beginComposition);
+        editableElement.removeEventListener('compositionend', finishComposition);
+        compositionActiveRef.current = false;
+      };
+    }, [editor]);
+
+    useEffect(() => {
+      if (!editor) return;
+      if (!editable && editor.view.composing) {
+        // ProseMirror treats compositionend as an edit event, so it will stop
+        // processing that event after editability has already been revoked.
+        // Drain the active local composition first to avoid stranding its
+        // internal composing state across the read-only transition.
+        const EventConstructor =
+          editor.view.dom.ownerDocument.defaultView!.Event;
+        editor.view.dom.dispatchEvent(new EventConstructor('compositionend'));
+      }
+      editor.setEditable(editable);
     }, [editor, editable]);
 
     useEffect(() => {
@@ -209,12 +269,26 @@ export const CwlEditor = forwardRef<CwlEditorHandle, CwlEditorProps>(
 
     useEffect(() => {
       if (!editor || !isControlled || emittingRef.current) return;
-      const current = editorHtmlToValue(editor.getHTML(), mode);
-      if (current !== value) {
-        /* v8 ignore next -- isControlled guarantees value is defined. */
-        const next = editorValueToHtml(value ?? '', mode);
-        editor.commands.setContent(next, false);
+
+      const synchronizeValue = () => {
+        const current = editorHtmlToValue(editor.getHTML(), mode);
+        if (current !== value) {
+          /* v8 ignore next -- isControlled guarantees value is defined. */
+          synchronizeControlledEditorValue(editor, value ?? '', mode);
+        }
+      };
+
+      if (!editor.view.composing) {
+        synchronizeValue();
+        return;
       }
+
+      editor.view.dom.addEventListener('compositionend', synchronizeValue, {
+        once: true,
+      });
+      return () => {
+        editor.view.dom.removeEventListener('compositionend', synchronizeValue);
+      };
     }, [editor, isControlled, value, mode]);
 
     const handleFormReset = useCallback(