sh-ui-cli 0.116.0 → 0.117.0

package/data/changelog/versions.json

@@ -2,6 +2,18 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.117.0",
+      "date": "2026-06-18",
+      "title": "Tree 컴포넌트 — 계층 데이터 확장·선택·키보드 네비",
+      "type": "minor",
+      "highlights": [
+        "신규 Tree — 데이터 주도(nodes 배열) 계층 트리. 확장/축소 + 단일 선택(제어·비제어)",
+        "WAI-ARIA Tree 패턴 — role=tree/treeitem/group, 화살표·Home/End·Enter·typeahead 키보드 네비",
+        "React(plain·tailwind·css-modules) + Flutter(ShUiTree) 동시 제공. 풀 기능(다중선택·DnD·lazy·인라인편집)은 후속"
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.117.0"
+    },
     {
       "version": "0.116.0",
       "date": "2026-06-17",

package/data/registry/flutter/registry.json

@@ -331,6 +331,15 @@
       ],
       "dependencies": [],
       "registryDependencies": ["tokens"]
+    },
+    "tree": {
+      "name": "tree",
+      "type": "widget",
+      "files": [
+        { "src": "widgets/sh_ui_tree.dart", "dest": "{widgets}/sh_ui_tree.dart" }
+      ],
+      "dependencies": [],
+      "registryDependencies": ["tokens"]
     }
   }
 }

package/data/registry/flutter/widgets/sh_ui_tree.dart

@@ -0,0 +1,428 @@
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import '../foundation/sh_ui_tokens.dart';
+
+/// Tree 밀도. [sm]은 좁은 사이드바용 컴팩트 변형.
+enum ShUiTreeSize { sm, md }
+
+/// Tree 노드 모델.
+class ShUiTreeNode {
+  /// 고유 식별자. 확장/선택 상태 추적에 사용된다.
+  final String id;
+
+  /// 행에 표시될 라벨.
+  final String label;
+
+  /// 하위 노드 목록 (선택). 비어있지 않으면 확장 가능한 부모로 취급된다.
+  final List<ShUiTreeNode>? children;
+
+  /// 라벨 왼쪽에 붙는 아이콘 (선택).
+  final IconData? icon;
+
+  /// 비활성화 상태. 선택·확장되지 않고 키보드 네비에서도 건너뛴다.
+  final bool disabled;
+
+  const ShUiTreeNode({
+    required this.id,
+    required this.label,
+    this.children,
+    this.icon,
+    this.disabled = false,
+  });
+
+  bool get hasChildren => children != null && children!.isNotEmpty;
+}
+
+/// shUi Tree — 계층형 노드를 들여쓰기로 렌더하는 트리 뷰.
+///
+/// 확장/축소(부모 노드 탭), 단일 선택, disabled 노드 스킵, Semantics(스크린
+/// 리더) 및 데스크탑/웹 키보드 네비(화살표·Enter/Space)를 지원한다.
+///
+/// 확장 상태는 [expandedIds]를 주면 controlled, 없으면 [defaultExpandedIds]로
+/// 시드한 내부 상태로 동작한다. 선택 상태도 [selectedId] / [defaultSelectedId]로
+/// 동일하게 controlled/uncontrolled를 가른다.
+class ShUiTree extends StatefulWidget {
+  /// 렌더할 트리 노드 배열.
+  final List<ShUiTreeNode> nodes;
+
+  /// 확장된 노드 id 집합 (controlled). null이면 내부 상태를 사용한다.
+  final Set<String>? expandedIds;
+
+  /// 초기 확장 노드 id 집합 (uncontrolled).
+  final Set<String>? defaultExpandedIds;
+
+  /// 확장 상태 변경 콜백. 변경 후의 확장 id 집합이 전달된다.
+  final ValueChanged<Set<String>>? onExpandedChange;
+
+  /// 선택된 노드 id (controlled). null이면 내부 상태를 사용한다.
+  final String? selectedId;
+
+  /// 초기 선택 노드 id (uncontrolled).
+  final String? defaultSelectedId;
+
+  /// 선택 변경 콜백. 선택된 노드 id(또는 null)가 전달된다.
+  final ValueChanged<String?>? onSelect;
+
+  /// 밀도. [ShUiTreeSize.sm]은 좁은 사이드바용 컴팩트 변형.
+  final ShUiTreeSize size;
+
+  const ShUiTree({
+    super.key,
+    required this.nodes,
+    this.expandedIds,
+    this.defaultExpandedIds,
+    this.onExpandedChange,
+    this.selectedId,
+    this.defaultSelectedId,
+    this.onSelect,
+    this.size = ShUiTreeSize.md,
+  });
+
+  @override
+  State<ShUiTree> createState() => _ShUiTreeState();
+}
+
+/// 평탄화된 한 행의 메타.
+class _FlatRow {
+  final ShUiTreeNode node;
+  final int level;
+  const _FlatRow(this.node, this.level);
+}
+
+class _ShUiTreeState extends State<ShUiTree> {
+  late Set<String> _expanded;
+  String? _selected;
+  final FocusNode _focusNode = FocusNode();
+  String? _focusedId;
+
+  /// build에서 한 번 계산해 둔, 현재 보이는 행들. 키 이벤트는 build 이후에
+  /// 발생하므로 키 핸들러가 이 값을 그대로 재사용해 _flatten() 중복 호출을 피한다.
+  List<_FlatRow> _visibleRows = const [];
+
+  bool get _expandedControlled => widget.expandedIds != null;
+  bool get _selectedControlled => widget.selectedId != null;
+
+  Set<String> get _effectiveExpanded =>
+      _expandedControlled ? widget.expandedIds! : _expanded;
+  String? get _effectiveSelected =>
+      _selectedControlled ? widget.selectedId : _selected;
+
+  @override
+  void initState() {
+    super.initState();
+    _expanded = {...?widget.defaultExpandedIds};
+    _selected = widget.defaultSelectedId;
+  }
+
+  @override
+  void dispose() {
+    _focusNode.dispose();
+    super.dispose();
+  }
+
+  /// 현재 확장 상태 기준으로 보이는 행만 평탄화한다.
+  List<_FlatRow> _flatten() {
+    final rows = <_FlatRow>[];
+    final expanded = _effectiveExpanded;
+    void walk(List<ShUiTreeNode> nodes, int level) {
+      for (final node in nodes) {
+        rows.add(_FlatRow(node, level));
+        if (node.hasChildren && expanded.contains(node.id)) {
+          walk(node.children!, level + 1);
+        }
+      }
+    }
+
+    walk(widget.nodes, 0);
+    return rows;
+  }
+
+  void _toggleExpand(String id) {
+    final next = {..._effectiveExpanded};
+    if (next.contains(id)) {
+      next.remove(id);
+    } else {
+      next.add(id);
+    }
+    if (!_expandedControlled) {
+      setState(() => _expanded = next);
+    }
+    widget.onExpandedChange?.call(next);
+  }
+
+  void _setExpanded(String id, bool expand) {
+    final current = _effectiveExpanded;
+    if (expand == current.contains(id)) return;
+    _toggleExpand(id);
+  }
+
+  void _select(String? id) {
+    if (!_selectedControlled) {
+      setState(() => _selected = id);
+    }
+    widget.onSelect?.call(id);
+  }
+
+  /// 노드 행 탭: 자식이 있으면 확장 토글 + 선택, 없으면 선택만.
+  void _onRowTap(ShUiTreeNode node) {
+    if (node.disabled) return;
+    setState(() => _focusedId = node.id);
+    if (node.hasChildren) {
+      _toggleExpand(node.id);
+    }
+    _select(node.id);
+  }
+
+  // ── 키보드 네비게이션 ──────────────────────────────────────────────
+
+  List<_FlatRow> _navigableRows(List<_FlatRow> rows) =>
+      rows.where((r) => !r.node.disabled).toList();
+
+  KeyEventResult _handleKey(FocusNode node, KeyEvent event) {
+    if (event is! KeyDownEvent && event is! KeyRepeatEvent) {
+      return KeyEventResult.ignored;
+    }
+    final rows = _visibleRows;
+    final navigable = _navigableRows(rows);
+    if (navigable.isEmpty) return KeyEventResult.ignored;
+
+    // 현재 포커스 인덱스 (없으면 첫 항목 직전으로 가정).
+    int currentIndex =
+        navigable.indexWhere((r) => r.node.id == _focusedId);
+    final key = event.logicalKey;
+
+    if (key == LogicalKeyboardKey.arrowDown) {
+      final nextIndex =
+          currentIndex < 0 ? 0 : (currentIndex + 1).clamp(0, navigable.length - 1);
+      setState(() => _focusedId = navigable[nextIndex].node.id);
+      return KeyEventResult.handled;
+    }
+    if (key == LogicalKeyboardKey.arrowUp) {
+      final prevIndex =
+          currentIndex <= 0 ? 0 : (currentIndex - 1);
+      setState(() => _focusedId = navigable[prevIndex].node.id);
+      return KeyEventResult.handled;
+    }
+    if (key == LogicalKeyboardKey.arrowRight) {
+      if (currentIndex < 0) return KeyEventResult.ignored;
+      final row = navigable[currentIndex];
+      if (row.node.hasChildren) {
+        if (!_effectiveExpanded.contains(row.node.id)) {
+          _setExpanded(row.node.id, true);
+        } else {
+          // 이미 확장됨 → 첫 자식으로 이동. 확장 상태 변경이 없으므로
+          // build에서 계산한 _visibleRows가 그대로 유효하다.
+          final after = _navigableRows(_visibleRows);
+          final idx = after.indexWhere((r) => r.node.id == row.node.id);
+          if (idx >= 0 && idx + 1 < after.length &&
+              after[idx + 1].level > row.level) {
+            setState(() => _focusedId = after[idx + 1].node.id);
+          }
+        }
+      }
+      return KeyEventResult.handled;
+    }
+    if (key == LogicalKeyboardKey.arrowLeft) {
+      if (currentIndex < 0) return KeyEventResult.ignored;
+      final row = navigable[currentIndex];
+      if (row.node.hasChildren && _effectiveExpanded.contains(row.node.id)) {
+        _setExpanded(row.node.id, false);
+      } else if (row.level > 0) {
+        // 부모로 이동.
+        final all = rows;
+        final pos = all.indexWhere((r) => r.node.id == row.node.id);
+        for (var i = pos - 1; i >= 0; i--) {
+          if (all[i].level < row.level && !all[i].node.disabled) {
+            setState(() => _focusedId = all[i].node.id);
+            break;
+          }
+        }
+      }
+      return KeyEventResult.handled;
+    }
+    if (key == LogicalKeyboardKey.home) {
+      setState(() => _focusedId = navigable.first.node.id);
+      return KeyEventResult.handled;
+    }
+    if (key == LogicalKeyboardKey.end) {
+      setState(() => _focusedId = navigable.last.node.id);
+      return KeyEventResult.handled;
+    }
+    if (key == LogicalKeyboardKey.enter ||
+        key == LogicalKeyboardKey.space) {
+      if (currentIndex < 0) return KeyEventResult.ignored;
+      _onRowTap(navigable[currentIndex].node);
+      return KeyEventResult.handled;
+    }
+    return KeyEventResult.ignored;
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final rows = _flatten();
+    _visibleRows = rows;
+
+    return Focus(
+      focusNode: _focusNode,
+      onKeyEvent: _handleKey,
+      child: Semantics(
+        container: true,
+        explicitChildNodes: true,
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.stretch,
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            for (final row in rows)
+              _ShUiTreeRow(
+                key: ValueKey(row.node.id),
+                node: row.node,
+                level: row.level,
+                size: widget.size,
+                isExpanded:
+                    row.node.hasChildren && _effectiveExpanded.contains(row.node.id),
+                isSelected: _effectiveSelected == row.node.id,
+                isFocused: _focusedId == row.node.id,
+                onTap: () {
+                  _focusNode.requestFocus();
+                  _onRowTap(row.node);
+                },
+              ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+class _ShUiTreeRow extends StatefulWidget {
+  final ShUiTreeNode node;
+  final int level;
+  final ShUiTreeSize size;
+  final bool isExpanded;
+  final bool isSelected;
+  final bool isFocused;
+  final VoidCallback onTap;
+
+  const _ShUiTreeRow({
+    super.key,
+    required this.node,
+    required this.level,
+    required this.size,
+    required this.isExpanded,
+    required this.isSelected,
+    required this.isFocused,
+    required this.onTap,
+  });
+
+  @override
+  State<_ShUiTreeRow> createState() => _ShUiTreeRowState();
+}
+
+class _ShUiTreeRowState extends State<_ShUiTreeRow> {
+  bool _hover = false;
+
+  @override
+  Widget build(BuildContext context) {
+    final shUi = Theme.of(context).extension<ShUiTheme>() ?? ShUiTheme.light;
+    final colors = shUi.colors;
+    final node = widget.node;
+    final disabled = node.disabled;
+    final sm = widget.size == ShUiTreeSize.sm;
+
+    final fontSize = sm ? shUi.text.xs : shUi.text.sm;
+    final vPad = sm ? shUi.spacing.s1 : shUi.spacing.s2;
+    final indent = shUi.spacing.s4 * widget.level;
+
+    final highlighted =
+        widget.isSelected || (widget.isFocused && !disabled);
+    final bg = highlighted
+        ? colors.backgroundMuted
+        : (_hover && !disabled ? colors.backgroundMuted : Colors.transparent);
+
+    final row = MouseRegion(
+      cursor: disabled ? SystemMouseCursors.basic : SystemMouseCursors.click,
+      onEnter: (_) => setState(() => _hover = true),
+      onExit: (_) => setState(() => _hover = false),
+      child: GestureDetector(
+        onTap: disabled ? null : widget.onTap,
+        behavior: HitTestBehavior.opaque,
+        child: AnimatedContainer(
+          duration: shUi.duration.fast,
+          curve: shUi.ease.standard,
+          padding: EdgeInsets.fromLTRB(
+            shUi.spacing.s2 + indent,
+            vPad,
+            shUi.spacing.s2,
+            vPad,
+          ),
+          decoration: BoxDecoration(
+            color: bg,
+            borderRadius:
+                BorderRadius.circular(shUi.radius.defaultRadius - 2),
+            border: widget.isFocused && !disabled
+                ? Border.all(
+                    color: colors.ring,
+                    width: shUi.borderWidth.strong,
+                  )
+                : Border.all(color: Colors.transparent, width: shUi.borderWidth.strong),
+          ),
+          child: Row(
+            children: [
+              // chevron — leaf면 자리만 유지(visibility hidden).
+              SizedBox(
+                width: shUi.spacing.s4,
+                child: node.hasChildren
+                    ? AnimatedRotation(
+                        turns: widget.isExpanded ? 0.25 : 0.0,
+                        duration: shUi.duration.fast,
+                        curve: shUi.ease.standard,
+                        child: Icon(
+                          Icons.chevron_right,
+                          size: sm ? 14 : 16,
+                          color: colors.foregroundMuted,
+                        ),
+                      )
+                    : const SizedBox.shrink(),
+              ),
+              SizedBox(width: shUi.spacing.s2),
+              if (node.icon != null) ...[
+                Icon(
+                  node.icon,
+                  size: sm ? 14 : 16,
+                  color: colors.foregroundMuted,
+                ),
+                SizedBox(width: shUi.spacing.s2),
+              ],
+              Expanded(
+                child: Text(
+                  node.label,
+                  overflow: TextOverflow.ellipsis,
+                  style: TextStyle(
+                    color: disabled ? colors.foregroundMuted : colors.foreground,
+                    fontSize: fontSize,
+                    fontWeight: widget.isSelected
+                        ? shUi.weight.medium
+                        : shUi.weight.regular,
+                    height: 1.25,
+                  ),
+                ),
+              ),
+            ],
+          ),
+        ),
+      ),
+    );
+
+    return Semantics(
+      selected: widget.isSelected,
+      enabled: !disabled,
+      expanded: node.hasChildren ? widget.isExpanded : null,
+      label: node.label,
+      button: true,
+      child: Opacity(
+        opacity: disabled ? shUi.opacity.disabled : 1,
+        child: row,
+      ),
+    );
+  }
+}

package/data/registry/react/components/rich-text-editor/index.module.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: styles.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]);