sh-ui-cli 0.116.0 → 0.117.0

package/data/registry/react/components/rich-text-editor/index.tailwind.tsx

@@ -1,16 +1,19 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import * as React from "react";
+import { useEffect, useRef, useState } from "react";
 import {
   useEditor,
   useEditorState,
   EditorContent,
   type Editor,
 } from "@tiptap/react";
+import type { AnyExtension } from "@tiptap/core";
 import StarterKit from "@tiptap/starter-kit";
 import Placeholder from "@tiptap/extension-placeholder";
 import Link from "@tiptap/extension-link";
 import { TextStyle, Color } from "@tiptap/extension-text-style";
+import { Markdown } from "tiptap-markdown";
 import { cn } from "@SH_UI_UTILS@";
 import {
   BoldIcon,
@@ -95,9 +98,26 @@ const DEFAULT_LABELS: RichTextEditorLabels = {
 };
 
 export interface RichTextEditorProps {
+  /**
+   * 입출력 포맷. 기본 'html'(하위호환). 'markdown' 이면 value/defaultValue/onChange 가 markdown 문자열.
+   * 주의: 마운트 시점에만 읽힘 — 런타임 변경은 에디터 리마운트 필요(extensions 도 동일).
+   */
+  format?: "html" | "markdown";
   value?: string;
   defaultValue?: string;
-  onChange?: (html: string) => void;
+  /** format='html' 이면 HTML, format='markdown' 이면 markdown 문자열을 넘긴다. */
+  onChange?: (value: string) => void;
+  /** Enter 로 제출. true 면 Enter=onSubmit, Shift+Enter=줄바꿈. 기본 false. */
+  submitOnEnter?: boolean;
+  /** 제출 콜백(submitOnEnter 또는 외부 버튼). */
+  onSubmit?: () => void;
+  /**
+   * StarterKit·기본 확장 뒤에 append 할 추가 TipTap 확장(멘션 등).
+   * 주의: format 과 마찬가지로 마운트 시점에만 읽힘 — 런타임 변경은 리마운트 필요.
+   */
+  extensions?: AnyExtension[];
+  /** 에디터 생성 시 콜백(외부에서 인스턴스 제어). */
+  onCreate?: (editor: Editor) => void;
   placeholder?: string;
   readOnly?: boolean;
   hideToolbar?: boolean;
@@ -127,6 +147,16 @@ const COLOR_SWATCHES = [
 
 const colorValue = (cssVar: string) => `var(${cssVar})`;
 
+/** tiptap-markdown storage 로 현재 doc 을 markdown 문자열로 직렬화. */
+function readMarkdown(editor: Editor): string {
+  const storage = editor.storage as {
+    markdown?: { getMarkdown(): string };
+  };
+  // markdown storage 가 없으면(직렬화 확장 미등록) HTML 을 흘려보내면 포맷이 어긋난다 —
+  // markdown 을 기대한 호출자에게 HTML 을 주지 않도록 빈 문자열로 폴백.
+  return storage.markdown?.getMarkdown() ?? "";
+}
+
 /** 선택 영역(없으면 URL 텍스트 삽입)에 링크를 적용. */
 function applyLink(editor: Editor, rawUrl: string) {
   const url = rawUrl.trim();
@@ -154,9 +184,14 @@ function applyLink(editor: Editor, rawUrl: string) {
 type ToolbarPanel = "none" | "link" | "color";
 
 export function RichTextEditor({
+  format = "html",
   value: valueProp,
   defaultValue,
   onChange,
+  submitOnEnter = false,
+  onSubmit,
+  extensions,
+  onCreate,
   placeholder,
   readOnly = false,
   hideToolbar = false,
@@ -173,6 +208,23 @@ export function RichTextEditor({
   const [panel, setPanel] = useState<ToolbarPanel>("none");
   const L = labels ? { ...DEFAULT_LABELS, ...labels } : DEFAULT_LABELS;
 
+  // onSubmit/submitOnEnter 를 ref 로 잡아 handleKeyDown 이 stale closure 가 되지 않게
+  // 한다(에디터를 매 렌더마다 재생성하지 않으려고 콜백은 useEditor deps 에서 제외).
+  const onSubmitRef = useRef(onSubmit);
+  onSubmitRef.current = onSubmit;
+  const submitOnEnterRef = useRef(submitOnEnter);
+  submitOnEnterRef.current = submitOnEnter;
+
+  // 마지막으로 onChange 로 흘려보냈거나(우리 echo) controlled-sync 로 주입한 value.
+  // controlled-sync 가 자기 자신의 emit 을 다시 setContent 하는 루프(커서 점프)를 막는다.
+  // 비교는 정규화된 직렬화 형태가 아니라 "우리가 마지막으로 본 문자열" 기준이라
+  // markdown 정규화(`**hi**` vs `**hi**\n`)로도 깨지지 않는다.
+  const lastSyncedRef = useRef<string | undefined>(undefined);
+
+  /** format 에 맞춰 에디터의 현재 본문을 직렬화(html/markdown). */
+  const readValue = (ed: Editor): string =>
+    format === "markdown" ? readMarkdown(ed) : ed.getHTML();
+
   const editor = useEditor({
     extensions: [
       // Link/Underline 은 v3 StarterKit 에 포함 — Link 는 따로 설정하려 끄고 별도 등록(중복 경고 회피).
@@ -189,22 +241,53 @@ export function RichTextEditor({
       }),
       TextStyle,
       Color.configure({ types: ["textStyle"] }),
+      // markdown 모드에서만 직렬화 확장 등록 — html 모드(기본)는 기존과 동일.
+      ...(format === "markdown" ? [Markdown.configure({ html: false })] : []),
+      ...(extensions ?? []),
     ],
+    // markdown 모드에서 tiptap-markdown 은 문자열을 markdown 으로 파싱한다.
     content: valueProp ?? defaultValue ?? "",
     editable: !readOnly,
     immediatelyRender: false,
+    onCreate: ({ editor }) => {
+      onCreate?.(editor);
+    },
     onUpdate: ({ editor }) => {
-      onChange?.(editor.getHTML());
+      const output = readValue(editor);
+      // 우리가 방금 emit 한 값을 controlled-sync 가 다시 주입하지 않도록 기록.
+      lastSyncedRef.current = output;
+      onChange?.(output);
     },
     editorProps: {
       attributes: { class: "sh-ui-rte__content", "aria-label": ariaLabel },
+      handleKeyDown: (_view, event) => {
+        if (
+          submitOnEnterRef.current &&
+          event.key === "Enter" &&
+          !event.shiftKey &&
+          // IME 조합 확정 Enter 는 제출이 아님(한글 등 — 조합 확정을 잘못 제출하면
+          // 입력이 날아간다). isComposing + 레거시 keyCode 229 둘 다 가드.
+          !event.isComposing &&
+          event.keyCode !== 229
+        ) {
+          event.preventDefault();
+          onSubmitRef.current?.();
+          return true;
+        }
+        return false;
+      },
     },
   });
 
+  // controlled 모드에서만 외부 value 를 에디터 doc 에 동기화.
+  // 직렬화 결과(readValue) 와 비교하면 markdown 정규화로 영원히 불일치 → 매 렌더 setContent
+  // → 커서 점프가 난다. 대신 "마지막으로 우리가 주고받은 문자열"(lastSyncedRef) 과 비교해
+  // 자기 echo 만 건너뛰고, 진짜 외부 변경(예: 채널 전환)은 항상 로드한다.
   useEffect(() => {
     if (!isControlled) return;
     if (!editor) return;
-    if (editor.getHTML() === valueProp) return;
+    if (valueProp === lastSyncedRef.current) return;
+    lastSyncedRef.current = valueProp;
     editor.commands.setContent(valueProp ?? "", { emitUpdate: false });
   }, [isControlled, valueProp, editor]);
 

package/data/registry/react/components/rich-text-editor/index.tsx

@@ -1,16 +1,19 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import * as React from "react";
+import { useEffect, useRef, useState } from "react";
 import {
   useEditor,
   useEditorState,
   EditorContent,
   type Editor,
 } from "@tiptap/react";
+import type { AnyExtension } from "@tiptap/core";
 import StarterKit from "@tiptap/starter-kit";
 import Placeholder from "@tiptap/extension-placeholder";
 import Link from "@tiptap/extension-link";
 import { TextStyle, Color } from "@tiptap/extension-text-style";
+import { Markdown } from "tiptap-markdown";
 import { cn } from "@SH_UI_UTILS@";
 import {
   BoldIcon,
@@ -97,17 +100,42 @@ const DEFAULT_LABELS: RichTextEditorLabels = {
 
 export interface RichTextEditorProps {
   /**
-   * Controlled — 현재 HTML. 명시 시 외부 상태가 진실원천이 되고 onChange 로 갱신한다.
+   * 입출력 포맷. 기본 'html'(하위호환). 'markdown' 이면 value/defaultValue/onChange 가
+   * markdown 문자열로 동작한다(tiptap-markdown 직렬화).
+   *
+   * 주의: 이 값은 **마운트 시점에만** 읽힌다 — 내부 `useEditor` 는 한 번만 생성되므로
+   * 런타임에 format 을 바꾸려면 에디터를 리마운트해야 한다(예: key prop 교체).
+   * 동일 제약이 `extensions` 에도 적용된다.
+   * @default "html"
+   */
+  format?: "html" | "markdown";
+  /**
+   * Controlled — 현재 본문(format 에 따라 HTML 또는 markdown 문자열).
+   * 명시 시 외부 상태가 진실원천이 되고 onChange 로 갱신한다.
    * 미지정이면 uncontrolled — Tiptap editor 가 자체 doc 으로 동작.
    */
   value?: string;
   /**
-   * Uncontrolled 초기 HTML. value 미지정 시에만 사용.
+   * Uncontrolled 초기 본문(format 에 따라 HTML 또는 markdown 문자열). value 미지정 시에만 사용.
    * @default ""
    */
   defaultValue?: string;
-  /** 본문이 바뀔 때마다 호출 (controlled · uncontrolled 모두). HTML 문자열을 그대로 넘긴다. */
-  onChange?: (html: string) => void;
+  /**
+   * 본문이 바뀔 때마다 호출 (controlled · uncontrolled 모두).
+   * format='html' 이면 HTML, format='markdown' 이면 markdown 문자열을 넘긴다.
+   */
+  onChange?: (value: string) => void;
+  /** Enter 로 제출. true 면 Enter=onSubmit, Shift+Enter=줄바꿈. 기본 false. */
+  submitOnEnter?: boolean;
+  /** 제출 콜백(submitOnEnter 또는 외부 버튼). */
+  onSubmit?: () => void;
+  /**
+   * StarterKit·기본 확장 뒤에 append 할 추가 TipTap 확장(멘션 등).
+   * 주의: `format` 과 마찬가지로 마운트 시점에만 읽힌다 — 런타임 변경은 리마운트 필요.
+   */
+  extensions?: AnyExtension[];
+  /** 에디터 생성 시 콜백(외부에서 인스턴스 제어). */
+  onCreate?: (editor: Editor) => void;
   /** 비어 있을 때 표시할 placeholder. */
   placeholder?: string;
   /** 읽기 전용. 키 입력·툴바 차단. */
@@ -141,6 +169,16 @@ const COLOR_SWATCHES = [
 
 const colorValue = (cssVar: string) => `var(${cssVar})`;
 
+/** tiptap-markdown storage 로 현재 doc 을 markdown 문자열로 직렬화. */
+function readMarkdown(editor: Editor): string {
+  const storage = editor.storage as {
+    markdown?: { getMarkdown(): string };
+  };
+  // markdown storage 가 없으면(직렬화 확장 미등록) HTML 을 흘려보내면 포맷이 어긋난다 —
+  // markdown 을 기대한 호출자에게 HTML 을 주지 않도록 빈 문자열로 폴백.
+  return storage.markdown?.getMarkdown() ?? "";
+}
+
 /** 선택 영역(없으면 URL 텍스트 삽입)에 링크를 적용. */
 function applyLink(editor: Editor, rawUrl: string) {
   const url = rawUrl.trim();
@@ -178,9 +216,14 @@ type ToolbarPanel = "none" | "link" | "color";
  * 구분선 · 실행취소/다시실행. compact 로 핵심만, toolbarMode="focus" 로 인라인 느낌.
  */
 export function RichTextEditor({
+  format = "html",
   value: valueProp,
   defaultValue,
   onChange,
+  submitOnEnter = false,
+  onSubmit,
+  extensions,
+  onCreate,
   placeholder,
   readOnly = false,
   hideToolbar = false,
@@ -197,6 +240,23 @@ export function RichTextEditor({
   const [panel, setPanel] = useState<ToolbarPanel>("none");
   const L = labels ? { ...DEFAULT_LABELS, ...labels } : DEFAULT_LABELS;
 
+  // onSubmit/submitOnEnter 를 ref 로 잡아 handleKeyDown 이 stale closure 가 되지 않게
+  // 한다(에디터를 매 렌더마다 재생성하지 않으려고 콜백은 useEditor deps 에서 제외).
+  const onSubmitRef = useRef(onSubmit);
+  onSubmitRef.current = onSubmit;
+  const submitOnEnterRef = useRef(submitOnEnter);
+  submitOnEnterRef.current = submitOnEnter;
+
+  // 마지막으로 onChange 로 흘려보냈거나(우리 echo) controlled-sync 로 주입한 value.
+  // controlled-sync 가 자기 자신의 emit 을 다시 setContent 하는 루프(커서 점프)를 막는다.
+  // 비교는 정규화된 직렬화 형태가 아니라 "우리가 마지막으로 본 문자열" 기준이라
+  // markdown 정규화(`**hi**` vs `**hi**\n`)로도 깨지지 않는다.
+  const lastSyncedRef = useRef<string | undefined>(undefined);
+
+  /** format 에 맞춰 에디터의 현재 본문을 직렬화(html/markdown). */
+  const readValue = (ed: Editor): string =>
+    format === "markdown" ? readMarkdown(ed) : ed.getHTML();
+
   const editor = useEditor({
     extensions: [
       // Link/Underline 은 v3 StarterKit 에 포함 — Link 는 따로 설정하려 끄고 별도 등록(중복 경고 회피).
@@ -213,26 +273,56 @@ export function RichTextEditor({
       }),
       TextStyle,
       Color.configure({ types: ["textStyle"] }),
+      // markdown 모드에서만 직렬화 확장 등록 — html 모드(기본)는 기존과 동일.
+      ...(format === "markdown" ? [Markdown.configure({ html: false })] : []),
+      ...(extensions ?? []),
     ],
+    // markdown 모드에서 tiptap-markdown 은 문자열을 markdown 으로 파싱한다.
     content: valueProp ?? defaultValue ?? "",
     editable: !readOnly,
     immediatelyRender: false,
+    onCreate: ({ editor }) => {
+      onCreate?.(editor);
+    },
     onUpdate: ({ editor }) => {
-      onChange?.(editor.getHTML());
+      const output = readValue(editor);
+      // 우리가 방금 emit 한 값을 controlled-sync 가 다시 주입하지 않도록 기록.
+      lastSyncedRef.current = output;
+      onChange?.(output);
     },
     editorProps: {
       attributes: {
         class: "sh-ui-rte__content",
         "aria-label": ariaLabel,
       },
+      handleKeyDown: (_view, event) => {
+        if (
+          submitOnEnterRef.current &&
+          event.key === "Enter" &&
+          !event.shiftKey &&
+          // IME 조합 확정 Enter 는 제출이 아님(한글 등 — 조합 확정을 잘못 제출하면
+          // 입력이 날아간다). isComposing + 레거시 keyCode 229 둘 다 가드.
+          !event.isComposing &&
+          event.keyCode !== 229
+        ) {
+          event.preventDefault();
+          onSubmitRef.current?.();
+          return true;
+        }
+        return false;
+      },
     },
   });
 
-  // controlled 모드에서만 외부 value 를 에디터 doc 에 동기화
+  // controlled 모드에서만 외부 value 를 에디터 doc 에 동기화.
+  // 직렬화 결과(readValue) 와 비교하면 markdown 정규화로 영원히 불일치 → 매 렌더 setContent
+  // → 커서 점프가 난다. 대신 "마지막으로 우리가 주고받은 문자열"(lastSyncedRef) 과 비교해
+  // 자기 echo 만 건너뛰고, 진짜 외부 변경(예: 채널 전환)은 항상 로드한다.
   useEffect(() => {
     if (!isControlled) return;
     if (!editor) return;
-    if (editor.getHTML() === valueProp) return;
+    if (valueProp === lastSyncedRef.current) return;
+    lastSyncedRef.current = valueProp;
     editor.commands.setContent(valueProp ?? "", { emitUpdate: false });
   }, [isControlled, valueProp, editor]);
 

package/data/registry/react/components/rich-text-editor/rich-text-editor.test.tsx

@@ -0,0 +1,283 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import * as React from "react";
+import { Extension } from "@tiptap/core";
+import { RichTextEditor } from "./index";
+
+void React;
+
+describe('RichTextEditor format="markdown"', () => {
+  it("markdown defaultValue 를 받아 굵게 마크로 렌더한다", async () => {
+    render(<RichTextEditor format="markdown" defaultValue={"**굵게**"} />);
+    // 에디터가 굵게 마크로 렌더(strong 존재)
+    await screen.findByText("굵게");
+    expect(screen.getByText("굵게").closest("strong")).not.toBeNull();
+  });
+
+  it("편집 시 onChange 가 markdown 문자열을 돌려준다", async () => {
+    const onChange = vi.fn();
+    let editor: import("@tiptap/react").Editor | undefined;
+    render(
+      <RichTextEditor
+        format="markdown"
+        defaultValue={"*기울임*"}
+        onChange={onChange}
+        onCreate={(e) => {
+          editor = e;
+        }}
+      />,
+    );
+    await screen.findByText("기울임");
+    await vi.waitFor(() => expect(editor).toBeDefined());
+    // 본문 끝에 굵은 텍스트를 추가하는 편집을 트랜잭션으로 일으켜 onUpdate 를 트리거.
+    editor!.chain().focus("end").insertContent(" **굵게**").run();
+    await vi.waitFor(() => expect(onChange).toHaveBeenCalled());
+    const out = onChange.mock.calls.at(-1)![0] as string;
+    // markdown(HTML 아님) 으로 직렬화됐는지 검증: 굵게 마크 + 태그 부재.
+    expect(out).toContain("**굵게**");
+    expect(out).not.toContain("<strong>");
+    // _italic_ 은 CommonMark 정규화로 *italic* 형태(별표 기반)로 나온다.
+    expect(out).toContain("*기울임*");
+  });
+
+  it("html 모드(기본)에서는 markdown storage 가 없다(직렬화 미등록)", async () => {
+    let editor: import("@tiptap/react").Editor | undefined;
+    render(
+      <RichTextEditor
+        defaultValue={"<p><em>기울임</em></p>"}
+        onCreate={(e) => {
+          editor = e;
+        }}
+      />,
+    );
+    await screen.findByText("기울임");
+    await vi.waitFor(() => expect(editor).toBeDefined());
+    const storage = editor!.storage as { markdown?: unknown };
+    expect(storage.markdown).toBeUndefined();
+  });
+});
+
+describe("RichTextEditor submitOnEnter", () => {
+  it("Enter 는 onSubmit, Shift+Enter 는 줄바꿈 (ProseMirror handleKeyDown 경유)", async () => {
+    const user = userEvent.setup();
+    const onSubmit = vi.fn();
+    let editor: import("@tiptap/react").Editor | undefined;
+    render(
+      <RichTextEditor
+        format="markdown"
+        submitOnEnter
+        onSubmit={onSubmit}
+        onCreate={(e) => {
+          editor = e;
+        }}
+        aria-label="c"
+      />,
+    );
+    const el = await screen.findByLabelText("c");
+    await vi.waitFor(() => expect(editor).toBeDefined());
+    // user-event 로 실제 키 이벤트를 발생시켜 ProseMirror 의 handleKeyDown 플러그인
+    // 체인을 진짜로 통과시킨다(raw dispatchEvent 는 PM view 를 거치지 않을 수 있음).
+    editor!.commands.focus();
+    el.focus();
+    await user.keyboard("{Enter}");
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+
+    await user.keyboard("{Shift>}{Enter}{/Shift}");
+    expect(onSubmit).toHaveBeenCalledTimes(1); // 늘지 않음(줄바꿈)
+  });
+
+  it("IME 조합 중(isComposing) Enter 는 제출하지 않고, 일반 Enter 는 제출한다", async () => {
+    const onSubmit = vi.fn();
+    let editor: import("@tiptap/react").Editor | undefined;
+    render(
+      <RichTextEditor
+        format="markdown"
+        submitOnEnter
+        onSubmit={onSubmit}
+        onCreate={(e) => {
+          editor = e;
+        }}
+        aria-label="ime"
+      />,
+    );
+    const el = await screen.findByLabelText("ime");
+    await vi.waitFor(() => expect(editor).toBeDefined());
+    editor!.commands.focus();
+    el.focus();
+
+    // 한글 조합 확정 Enter 는 isComposing: true 로 들어온다 — 제출되면 안 됨.
+    el.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        key: "Enter",
+        bubbles: true,
+        cancelable: true,
+        // @ts-expect-error jsdom KeyboardEvent 는 isComposing 을 옵션으로 받음
+        isComposing: true,
+      }),
+    );
+    expect(onSubmit).not.toHaveBeenCalled();
+
+    // 레거시 브라우저가 보내는 keyCode 229(조합 중) Enter 도 제출 금지.
+    el.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        key: "Enter",
+        bubbles: true,
+        cancelable: true,
+        keyCode: 229,
+      }),
+    );
+    expect(onSubmit).not.toHaveBeenCalled();
+
+    // 조합이 끝난 일반 Enter 는 제출된다.
+    el.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        key: "Enter",
+        bubbles: true,
+        cancelable: true,
+      }),
+    );
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("RichTextEditor controlled-sync (C-2 루프/커서 점프 방지)", () => {
+  it("동일 value 로 부모가 리렌더해도 setContent·셀렉션을 건드리지 않는다(커서 점프 방지)", async () => {
+    let editor: import("@tiptap/react").Editor | undefined;
+    let forceRerender: (() => void) | undefined;
+
+    // controlled value 가 그대로인데 부모가 리렌더하는 흔한 상황. lastSyncedRef 비교 덕에
+    // sync effect 가 우리 doc 을 다시 setContent 하지 않아 커서/셀렉션이 보존된다.
+    // (직렬화 비교만 했다면 markdown 정규화 차이로 매 렌더 setContent → 점프 위험.)
+    function Harness() {
+      const [, tick] = React.useState(0);
+      forceRerender = () => tick((n) => n + 1);
+      return (
+        <RichTextEditor
+          format="markdown"
+          value={"**hi**"}
+          onChange={() => {}}
+          onCreate={(e) => {
+            editor = e;
+          }}
+          aria-label="sync"
+        />
+      );
+    }
+
+    render(<Harness />);
+    await vi.waitFor(() => expect(editor).toBeDefined());
+    await screen.findByText("hi");
+
+    // 커서를 문서 끝으로 두고 위치 기록.
+    editor!.commands.focus("end");
+    const before = editor!.state.selection.from;
+    expect(before).toBeGreaterThan(1);
+
+    // 같은 value 로 부모 리렌더 — sync effect 가 echo 를 다시 주입하면 안 된다.
+    const setContentSpy = vi.spyOn(editor!.commands, "setContent");
+    await React.act(async () => {
+      forceRerender!();
+      // effect flush 까지 대기(setContent 가 일어난다면 여기서 일어난다).
+      await Promise.resolve();
+    });
+
+    // setContent 미호출 + 셀렉션 그대로(점프 없음).
+    expect(setContentSpy).not.toHaveBeenCalled();
+    expect(editor!.state.selection.from).toBe(before);
+    setContentSpy.mockRestore();
+  });
+
+  it("진짜 다른 외부 value 는 에디터에 로드된다 (채널 전환)", async () => {
+    function Harness({ value }: { value: string }) {
+      return <RichTextEditor format="markdown" value={value} aria-label="ext" />;
+    }
+    const { rerender } = render(<Harness value={"**first**"} />);
+    await screen.findByText("first");
+
+    // 외부에서 완전히 다른 value 주입 → 에디터에 반영돼야 한다.
+    rerender(<Harness value={"**second**"} />);
+    await screen.findByText("second");
+    expect(screen.queryByText("first")).toBeNull();
+  });
+
+  it("html 모드에서도 controlled echo 루프가 발생하지 않는다", async () => {
+    let editor: import("@tiptap/react").Editor | undefined;
+    let lastEmitted = "";
+    function Harness() {
+      const [value, setValue] = React.useState("<p>hi</p>");
+      return (
+        <RichTextEditor
+          value={value}
+          onChange={(v) => {
+            lastEmitted = v;
+            setValue(v);
+          }}
+          onCreate={(e) => {
+            editor = e;
+          }}
+          aria-label="html-sync"
+        />
+      );
+    }
+    render(<Harness />);
+    await vi.waitFor(() => expect(editor).toBeDefined());
+    await screen.findByText("hi");
+
+    editor!.chain().focus("end").insertContent(" x").run();
+    await vi.waitFor(() => expect(lastEmitted).toContain("x"));
+
+    const setContentSpy = vi.spyOn(editor!.commands, "setContent");
+    editor!.chain().focus("end").insertContent("y").run();
+    await vi.waitFor(() => expect(lastEmitted).toContain("y"));
+    expect(setContentSpy).not.toHaveBeenCalled();
+    setContentSpy.mockRestore();
+  });
+});
+
+describe("RichTextEditor extensions/onCreate", () => {
+  it("추가 확장이 등록되고 onCreate 로 editor 에 접근한다", async () => {
+    const onCreate = vi.fn();
+    const marker = Extension.create({ name: "spikeMarker" });
+    render(
+      <RichTextEditor
+        format="markdown"
+        extensions={[marker]}
+        onCreate={onCreate}
+      />,
+    );
+    await vi.waitFor(() => expect(onCreate).toHaveBeenCalled());
+    const editor = onCreate.mock.calls[0][0];
+    expect(
+      editor.extensionManager.extensions.some(
+        (e: { name: string }) => e.name === "spikeMarker",
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("RichTextEditor 하위호환 (default html)", () => {
+  it("기본 format(html)에서 편집 시 onChange 가 HTML 을 돌려준다", async () => {
+    const onChange = vi.fn();
+    let editor: import("@tiptap/react").Editor | undefined;
+    render(
+      <RichTextEditor
+        defaultValue={"<p><strong>굵게</strong></p>"}
+        onChange={onChange}
+        onCreate={(e) => {
+          editor = e;
+        }}
+      />,
+    );
+    await screen.findByText("굵게");
+    expect(screen.getByText("굵게").closest("strong")).not.toBeNull();
+    await vi.waitFor(() => expect(editor).toBeDefined());
+    editor!.chain().focus("end").insertContent(" 추가").run();
+    await vi.waitFor(() => expect(onChange).toHaveBeenCalled());
+    const out = onChange.mock.calls.at(-1)![0] as string;
+    // html 모드(기본)이므로 태그 문자열이 그대로 나와야 한다(markdown 별표 아님).
+    expect(out).toContain("<strong>");
+    expect(out).toContain("<p>");
+    expect(out).not.toContain("**");
+  });
+});