one-design-next 0.0.113 → 0.0.115

package/dist/composer/editor.js

@@ -23,12 +23,13 @@ import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
 import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import ScrollArea from "../scroll-area";
-import { findChipHostBeforeCaret, mergeLineIntoPreviousAtCaretStart, normalizeCollapsedCaretAtChipBoundary, resolveCaretMove, splitLineAt } from "./caret";
+import { caretBeforeHintIn, caretRangeFromPoint, findChipHostBeforeCaret, getCaretBeforeHint, getCurrentLine, isCaretBeforeHint, isCaretOnHintLine, isPointOnHint, isPositionAfterHint, mergeLineIntoPreviousAtCaretStart, normalizeCollapsedCaretAtChipBoundary, normalizeCollapsedCaretBeforeHint, resolveCaretMove, splitLineAt, wouldArrowCrossHint } from "./caret";
 import { buildClipboardPayload, COMPOSER_CLIPBOARD_MIME, parseClipboardPayload, plainTextFromClipboardPayload, remapClipboardPayload } from "./clipboard";
 import { useChipManager } from "./hooks/useChipManager";
 import { useChipSelectionMarker } from "./hooks/useChipSelectionMarker";
 import { chipHasEditableParams, ComposerInlineRef } from "./inline-ref";
-import { createLineRoot, createLineRootWithText, ensureLineRoots, getPlainText, isEditorEmpty, LINE_ATTR_NAME, normalizeEditorDom, probeTrigger } from "./utils";
+import { resolveHintTarget } from "./segments";
+import { COMPOSER_HINT_ATTR, createLineRoot, createLineRootWithText, ensureCaretAnchorAfter, ensureLineRoots, getPlainText, isEditorEmpty, isLineRoot, LINE_ATTR_NAME, normalizeEditorDom, probeTrigger, stripInvisibleChars, ZWSP } from "./utils";
 
 /** Composer editor 触发态对外信号——告诉父组件该弹浮层选 skill 了。 */
 
@@ -39,6 +40,11 @@ var sameProbe = function sameProbe(a, b) {
   return a.textNode === b.textNode && a.triggerOffset === b.triggerOffset && a.caretOffset === b.caretOffset && a.trigger === b.trigger;
 };
 
+/** 归一化结果是否与当前 caret 完全一致（同节点同偏移）。 */
+var isSameCaretPosition = function isSameCaretPosition(range, position) {
+  return range.startContainer === position.node && range.startOffset === position.offset;
+};
+
 /**
  * 让 caret 始终保持在 viewport（ScrollArea 的可视区）内。
  *
@@ -76,6 +82,109 @@ var scrollCaretIntoView = function scrollCaretIntoView(viewport) {
     viewport.scrollTop -= viewportRect.top - rect.top + 4;
   }
 };
+
+/** insertContent 的目标行：最后一个行容器；没有行模型时退回 editor 本身。 */
+var resolveEndLine = function resolveEndLine(editor) {
+  var last = editor.lastElementChild;
+  return isLineRoot(last) ? last : editor;
+};
+
+/** 行内直接子节点的派生 hint（不是正文，插入必须落在它之前）。 */
+var findDirectHint = function findDirectHint(line) {
+  for (var _i = 0, _Array$from = Array.from(line.children); _i < _Array$from.length; _i++) {
+    var child = _Array$from[_i];
+    if (child.hasAttribute(COMPOSER_HINT_ATTR)) return child;
+  }
+  return null;
+};
+
+/**
+ * insertContent 的插入点：最后一个行容器的内容末尾。
+ *
+ * 不能直接 `selectNodeContents(editor).collapse(false)`：
+ * - 行尾的派生 hint 不是内容：落在 hint 之前，避免内容插到灰字后面
+ * - 行尾的占位 `<br>` 不是换行：插到它前面。插到后面会让它从「占位」变成
+ *   真实换行，`getPlainText` 就会凭空多输出一个 '\n'
+ */
+var resolveEndRange = function resolveEndRange(editor) {
+  var line = resolveEndLine(editor);
+  var range = document.createRange();
+  var hint = findDirectHint(line);
+  if (hint) {
+    var before = getCaretBeforeHint(hint);
+    if (before) {
+      range.setStart(before.node, before.offset);
+      range.collapse(true);
+      return range;
+    }
+  }
+  var offset = line.childNodes.length;
+  while (offset > 0) {
+    var node = line.childNodes[offset - 1];
+    if (node.nodeType === Node.ELEMENT_NODE && node.tagName === 'BR') {
+      offset -= 1;
+      continue;
+    }
+    break;
+  }
+  range.setStart(line, offset);
+  range.collapse(true);
+  return range;
+};
+
+/**
+ * insertContent 之后把 caret 落到新内容末尾。
+ *
+ * 行尾是 chip 时补一颗不进 value 的 ZWSP 锚点（与 insertChip 一致）：
+ * 只靠元素偏移落位时，部分浏览器会把 caret 带到结构块之后。
+ * 行尾有派生 hint 时仍落在 hint 之前（hint 之后不是合法插入点）。
+ */
+var placeCaretAtEnd = function placeCaretAtEnd(editor) {
+  var sel = window.getSelection();
+  if (!sel) return;
+  var line = resolveEndLine(editor);
+  var target;
+  var hint = findDirectHint(line);
+  var beforeHint = hint ? getCaretBeforeHint(hint) : null;
+  if (beforeHint) {
+    target = beforeHint;
+  } else {
+    var offset = line.childNodes.length;
+    while (offset > 0) {
+      var node = line.childNodes[offset - 1];
+      if (node.nodeType === Node.ELEMENT_NODE && node.tagName === 'BR') {
+        offset -= 1;
+        continue;
+      }
+      break;
+    }
+    var tail = offset > 0 ? line.childNodes[offset - 1] : null;
+    if ((tail === null || tail === void 0 ? void 0 : tail.nodeType) === Node.TEXT_NODE) {
+      var _tail$textContent;
+      target = {
+        node: tail,
+        offset: ((_tail$textContent = tail.textContent) !== null && _tail$textContent !== void 0 ? _tail$textContent : '').length
+      };
+    } else if (tail instanceof HTMLElement && tail.hasAttribute('data-odn-composer-chip-host')) {
+      var _anchor$textContent;
+      var _anchor = ensureCaretAnchorAfter(tail);
+      target = {
+        node: _anchor,
+        offset: ((_anchor$textContent = _anchor.textContent) !== null && _anchor$textContent !== void 0 ? _anchor$textContent : '').length
+      };
+    } else {
+      target = {
+        node: line,
+        offset: offset
+      };
+    }
+  }
+  var range = document.createRange();
+  range.setStart(target.node, target.offset);
+  range.collapse(true);
+  sel.removeAllRanges();
+  sel.addRange(range);
+};
 var LINE_HEIGHT = 24;
 /** 与 SCSS `padding: 2px … 0` 对齐。10 行 = 10 * 24 + 2 = 242px。 */
 var EDITOR_PADDING_BLOCK = 2;
@@ -237,11 +346,124 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
       }
     };
   }, []);
+
+  /* chips 快照读取器：fireChange 声明在 useChipManager 之前（后者又依赖 fireChange
+   * 当 onAfterMutate），用 ref 打破声明顺序，与 recomputeTriggerRef 同一套做法。 */
+  var getChipsRef = useRef(function () {
+    return [];
+  });
+
+  /* ---- 派生 hint：imperative DOM 同步 ----
+   * hint 必须是 chip host 的**兄弟节点**，不能塞在 host 内部：host 是
+   * contentEditable=false 的原子节点，塞进去后「chip 之后、hint 之前」这个位置
+   * 就不存在了，caret 只能落在整个 host 之后（= 提示文本末尾）。
+   *
+   * 它不归 React 管（editor 的 children 由 contenteditable 自治），由 fireChange
+   * 按结构谓词增删/挪位；`getPlainText` 会整棵子树跳过，所以不进 value / 剪贴板。 */
+  var hintNodeRef = useRef(null);
+  var removeHintNode = useCallback(function () {
+    var _hintNodeRef$current;
+    (_hintNodeRef$current = hintNodeRef.current) === null || _hintNodeRef$current === void 0 || _hintNodeRef$current.remove();
+    hintNodeRef.current = null;
+  }, []);
+  var syncHintNode = useCallback(function (target) {
+    var _Array$from$find, _blankTail;
+    var el = editorRef.current;
+    var host = el && target ? (_Array$from$find = Array.from(el.querySelectorAll('[data-mention-id]')).find(function (node) {
+      return node.dataset.mentionId === target.chipId;
+    })) !== null && _Array$from$find !== void 0 ? _Array$from$find : null : null;
+    if (!target || !host || !host.parentNode) {
+      removeHintNode();
+      return;
+    }
+    var node = hintNodeRef.current;
+    if (!node || !node.isConnected) {
+      node = document.createElement('span');
+      node.setAttribute(COMPOSER_HINT_ATTR, '');
+      node.contentEditable = 'false';
+      hintNodeRef.current = node;
+    }
+    if (node.textContent !== target.text) node.textContent = target.text;
+
+    /* 落位：命中 chip 之后、**紧随其后的不可见锚点文本（ZWSP）之后**。
+     *
+     * 谓词要求 chip 之后没有任何内容，所以这里能走过去的只有不进 value 的
+     * 锚点文本（caret.ts / insertChip 在 chip 与 hint 之间塞的 ZWSP）。hint
+     * 若插在锚点前面，caret 就只剩「元素偏移」一个落点，每次输入后还会被
+     * 拽回去重排；排在锚点之后，caret 落在真实的文本节点里，位置稳定。
+     * 注意只跳过「纯不可见字符」的文本：空格 / 换行是内容（谓词会让 hint
+     * 直接消失），不能把 hint 推到它们后面。 */
+    var parent = host.parentNode;
+    var blankTail = null;
+    var cur = host.nextSibling;
+    while (cur) {
+      var _cur$textContent;
+      // 跳过 hint 自身：上一轮若把它排到了锚点前面，这里顺手挪回末尾
+      if (cur === node) {
+        cur = cur.nextSibling;
+        continue;
+      }
+      if (cur.nodeType === Node.TEXT_NODE && stripInvisibleChars((_cur$textContent = cur.textContent) !== null && _cur$textContent !== void 0 ? _cur$textContent : '') === '') {
+        blankTail = cur;
+        cur = cur.nextSibling;
+        continue;
+      }
+      break;
+    }
+    /* 没有现成锚点时必须补一个：草稿还原（defaultValue + defaultChips）走的
+     * 是 insertSerializedAtRange，不会像 insertChip 那样在 chip 后塞 ZWSP，
+     * 于是 chip 与 hint 之间没有任何可编辑文本节点。此时用户第一次点击 hint，
+     * 原生 caret 无处可落，Chrome 会先把它放进 hint 内部（首帧画在提示文案
+     * 开头），下一拍才被 selectionchange 拉回来 —— 也就是「进页面第一次点
+     * hint，光标先闪一下」。垫上锚点后原生落点直接命中它。
+     * 锚点不进 value（stripInvisibleChars / getPlainText 都会剔除）。 */
+    if (!blankTail) {
+      var caretAnchor = document.createTextNode(ZWSP);
+      parent.insertBefore(caretAnchor, host.nextSibling);
+      blankTail = caretAnchor;
+    }
+    var anchor = (_blankTail = blankTail) !== null && _blankTail !== void 0 ? _blankTail : host;
+    if (node.parentNode !== parent || node.previousSibling !== anchor) {
+      parent.insertBefore(node, anchor.nextSibling);
+    }
+  }, [removeHintNode]);
+
+  /** 把 caret 直接落到 hint 之前（= chip 右侧）；没有 hint 时不动。 */
+  var placeCaretBeforeHint = useCallback(function () {
+    var el = editorRef.current;
+    var target = el ? caretBeforeHintIn(el) : null;
+    var sel = window.getSelection();
+    if (!target || !sel) return false;
+    var range = document.createRange();
+    range.setStart(target.node, target.offset);
+    range.collapse(true);
+    sel.removeAllRanges();
+    sel.addRange(range);
+    lastEditorRangeRef.current = range.cloneRange();
+    return true;
+  }, []);
+
+  /** hint 之后不是合法插入点：把跑过去的 caret 拉回 hint 之前（chip 右侧）。 */
+  var pullCaretBeforeHint = useCallback(function () {
+    var el = editorRef.current;
+    var sel = window.getSelection();
+    if (!el || !sel || sel.rangeCount !== 1 || !sel.isCollapsed) return;
+    if (!el.contains(sel.anchorNode)) return;
+    if (!normalizeCollapsedCaretBeforeHint(sel.getRangeAt(0), el)) return;
+    placeCaretBeforeHint();
+  }, [placeCaretBeforeHint]);
   var fireChange = useCallback(function () {
     var el = editorRef.current;
     if (!el) return;
     // normalizeEditorDom 内部已 ensureLineRoots（commit-2），此处不必重复兜底
     normalizeEditorDom(el);
+    var chips = getChipsRef.current();
+    var raw = getPlainText(el);
+    /* 派生 hint 与 value 同源同刻重算：结构谓词只依赖 raw + chips（换行也算
+     * 内容，所以按 Enter 后 hint 自动消失）。必须先落 DOM 再算 empty / 高度——
+     * 否则「chip 被删」时残留的 hint 文本会让 placeholder 判定与 lite 升格
+     * 判定晚一拍。 */
+    syncHintNode(resolveHintTarget(raw, chips));
     var showPlaceholder = shouldShowPlaceholder(el);
     if (forceNonEmptyOnceRef.current && showPlaceholder) {
       setEmpty(false);
@@ -249,11 +471,12 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
       setEmpty(showPlaceholder);
     }
     forceNonEmptyOnceRef.current = false;
-    onChange === null || onChange === void 0 || onChange(getPlainText(el));
+    onChange === null || onChange === void 0 || onChange(raw);
+    pullCaretBeforeHint();
     scheduleControlledSync();
     // editor.height 锁定时 RO 不触发，主动同步一次，确保升格判定能拿到 scrollHeight
     syncHeight();
-  }, [onChange, scheduleControlledSync, shouldShowPlaceholder, syncHeight]);
+  }, [onChange, pullCaretBeforeHint, scheduleControlledSync, shouldShowPlaceholder, syncHeight, syncHintNode]);
 
   /* ─────────────────────────────────────
    * chip 管理
@@ -272,6 +495,7 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     getChipHost = _useChipManager.getChipHost,
     getChips = _useChipManager.getChips,
     resetChips = _useChipManager.resetChips;
+  getChipsRef.current = getChips;
   useChipSelectionMarker(editorRef, chips);
   var insertSerializedAtRangeRef = useRef(insertSerializedAtRange);
   insertSerializedAtRangeRef.current = insertSerializedAtRange;
@@ -305,6 +529,50 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
   }, [triggers, onTriggerChange, probeToInfo]);
   recomputeTriggerRef.current = recomputeTrigger;
 
+  /* ─────────────────────────────────────
+   * Tab 采纳 hint
+   *
+   * hint 只是结构投影（不进 value）；caret 恰好停在 chip 与 hint 之间
+   * （= 内容末尾）时按 Tab，表示用户接受这段模板，于是把提示文案落成正文：
+   * chip 之后出现内容 → 结构谓词不再命中 → 灰字自动移除，onChange 抛出的
+   * value 里带上这段文案，与用户自己敲进去的效果一致。
+   * ───────────────────────────────────── */
+  var acceptHintAsText = useCallback(function () {
+    var _hint$textContent;
+    var el = editorRef.current;
+    var hint = hintNodeRef.current;
+    var sel = window.getSelection();
+    if (!el || !hint || !hint.isConnected || !sel || sel.rangeCount === 0) {
+      return false;
+    }
+    var range = sel.getRangeAt(0);
+    if (!range.collapsed || !el.contains(range.startContainer)) return false;
+    /* 只认「chip 之后、hint 之前」这一个落点；caret 在别处时 Tab 仍归浏览器，
+     * 避免在任意位置误吞焦点切换。 */
+    if (!isCaretBeforeHint(range, el)) return false;
+    var text = (_hint$textContent = hint.textContent) !== null && _hint$textContent !== void 0 ? _hint$textContent : '';
+    if (!text) return false;
+
+    /* 多行模板按行模型展开（与粘贴纯文本同一路径）；单行直接插文本节点。 */
+    if (text.includes('\n')) {
+      insertSerializedAtRange(text, [], range, el);
+    } else {
+      var node = document.createTextNode(text);
+      range.insertNode(node);
+      var caret = document.createRange();
+      /* 落点写进文本节点内部（而不是 setStartAfter 的元素偏移），后续输入
+       * 直接在同一节点里续写，caret 也更稳定。 */
+      caret.setStart(node, text.length);
+      caret.collapse(true);
+      sel.removeAllRanges();
+      sel.addRange(caret);
+    }
+    fireChange();
+    recomputeTrigger();
+    requestScrollCaretIntoView();
+    return true;
+  }, [fireChange, insertSerializedAtRange, recomputeTrigger, requestScrollCaretIntoView]);
+
   /* ─────────────────────────────────────
    * ref 命令式 API
    * ───────────────────────────────────── */
@@ -323,6 +591,7 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
         if (!el) return;
         el.innerHTML = '';
         el.appendChild(createLineRoot());
+        removeHintNode();
         resetChips();
         setEmpty(true);
         if (triggerRef.current) {
@@ -370,6 +639,33 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
         onTriggerChange === null || onTriggerChange === void 0 || onTriggerChange(null);
         _insertChip(data, el);
       },
+      insertSerializedAtEnd: function insertSerializedAtEnd(value, nextChips, options) {
+        var el = editorRef.current;
+        if (!el || !value) return;
+        ensureLineRoots(el);
+        var range = resolveEndRange(el);
+        var shouldFocus = (options === null || options === void 0 ? void 0 : options.focus) !== false;
+        /* 拿不到 Selection 时仍要把内容插进去，只是不主动落 caret。 */
+        var sel = shouldFocus ? window.getSelection() : null;
+        if (sel) {
+          sel.removeAllRanges();
+          sel.addRange(range);
+        }
+        insertSerializedAtRange(value, nextChips, range, el, {
+          focus: shouldFocus,
+          caret: !!sel
+        });
+        if (!shouldFocus) return;
+        placeCaretAtEnd(el);
+        if (sel && sel.rangeCount > 0) {
+          lastEditorRangeRef.current = sel.getRangeAt(0).cloneRange();
+        }
+        requestScrollCaretIntoView();
+      },
+      getValue: function getValue() {
+        var el = editorRef.current;
+        return el ? getPlainText(el) : '';
+      },
       cancelTrigger: function cancelTrigger() {
         if (!triggerRef.current) return;
         triggerRef.current = null;
@@ -392,7 +688,7 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
         return editorRef.current;
       }
     };
-  }, [onChange, _insertChip, removeChip, resetChips, onTriggerChange, getChips, updateChipData, getChipHost]);
+  }, [onChange, _insertChip, insertSerializedAtRange, requestScrollCaretIntoView, removeChip, resetChips, onTriggerChange, getChips, updateChipData, getChipHost]);
 
   /* ─────────────────────────────────────
    * 监听 selection 变化：方向键 / 鼠标点击移位都要重算 trigger
@@ -418,8 +714,15 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
       }
       var range = sel.getRangeAt(0);
       if (range.collapsed) {
-        var normalized = normalizeCollapsedCaretAtChipBoundary(range, el);
-        if (normalized) {
+        var _normalizeCollapsedCa;
+        /* hint 之后不是合法插入点（点击行尾 / End / 方向键跑到提示文案后面），
+         * 优先拉回 hint 左侧；其余 chip 边界仍走原规范化。 */
+        var normalized = (_normalizeCollapsedCa = normalizeCollapsedCaretBeforeHint(range, el)) !== null && _normalizeCollapsedCa !== void 0 ? _normalizeCollapsedCa : normalizeCollapsedCaretAtChipBoundary(range, el);
+        /* 归一化到「原地」时不能再回写：removeAllRanges + addRange 会再次派发
+         * selectionchange，形成「归一化 → 回写 → 再归一化」的死循环。
+         * chip 后只剩 ZWSP 锚点（hint 场景的常态）时归一化结果必然等于当前
+         * caret，正是这条循环最容易命中的地方。 */
+        if (normalized && !isSameCaretPosition(range, normalized)) {
           var r = document.createRange();
           r.setStart(normalized.node, normalized.offset);
           r.collapse(true);
@@ -458,7 +761,12 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
           var range = document.createRange();
           range.selectNodeContents(firstLine);
           range.collapse(true);
-          insertSerializedAtRangeRef.current(initial, initialChips, range, el);
+          /* 首屏还原不是用户操作：不要在这里 focus。否则挂载时浏览器会把
+           * 页面滚动到该编辑器（多个 demo / 多处草稿还原时，最后聚焦的那个
+           * 会决定滚动落点），用户看到的就是「一进页面就跳位置」。 */
+          insertSerializedAtRangeRef.current(initial, initialChips, range, el, {
+            focus: false
+          });
         }
       } else {
         var lines = (initial !== null && initial !== void 0 ? initial : '').split('\n');
@@ -528,11 +836,13 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
           var line = _step2.value;
           el.appendChild(createLineRootWithText(line));
         }
+        // 重建后没有任何 chip，hint 一并清掉（外部 value 只按纯文本还原）
       } catch (err) {
         _iterator2.e(err);
       } finally {
         _iterator2.f();
       }
+      removeHintNode();
       resetChips();
       setEmpty(shouldShowPlaceholder(el));
       if (triggerRef.current) {
@@ -569,7 +879,10 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     isComposingRef.current = true;
     // 合成期一定会有候选字符出现，立刻收 placeholder（输入事件会进一步刷新）
     setEmpty(false);
-  }, []);
+    /* 合成期 hint 先摘掉：候选串会插在 chip/hint 之间，留着灰字会和候选文字挤在
+     * 一起且语义已经失效（用户开始自己写内容了）。compositionEnd 会按谓词重算。 */
+    removeHintNode();
+  }, [removeHintNode]);
   var handleCompositionEnd = useCallback(function () {
     isComposingRef.current = false;
     var el = editorRef.current;
@@ -620,10 +933,19 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     /* 触发态优先：activeTrigger 时把导航键先吐给父组件（驱动浮层选择）。
      * 父返回 true 表示已处理，editor 直接结束本次 keydown，不再走任何
      * 自身逻辑（避免 Enter 又触发 onPressEnter / 插换行）。 */
-    if (triggerRef.current && onTriggerKeyDown && (e.key === 'ArrowDown' || e.key === 'ArrowUp' || e.key === 'Enter' && !e.shiftKey || e.key === 'Escape' || e.key === 'Tab')) {
+    if (triggerRef.current && onTriggerKeyDown && (e.key === 'ArrowDown' || e.key === 'ArrowUp' || e.key === 'Enter' && !e.shiftKey || e.key === 'Escape' || e.key === 'Tab' && !e.shiftKey && !e.altKey && !e.ctrlKey && !e.metaKey)) {
       if (onTriggerKeyDown(e) === true) return;
     }
 
+    /* Tab 采纳 hint：caret 停在 chip 与派生 hint 之间（内容末尾）时，把提示
+     * 文案落成正文。浮层展开时 Tab 已被父组件优先用于选中技能（上面已 return）；
+     * 走到这里说明浮层没开 / 没有命中，才轮到 hint 采纳。带修饰键的
+     * Tab（Shift+Tab 反向焦点、Ctrl/Cmd+Tab 切窗口）不拦，保持浏览器默认。 */
+    if (e.key === 'Tab' && !e.shiftKey && !e.altKey && !e.ctrlKey && !e.metaKey && acceptHintAsText()) {
+      e.preventDefault();
+      return;
+    }
+
     // Backspace：chip 边界——空 text 在 chip 后先退回 chip 前；chip 前无正文再整块删
     if (e.key === 'Backspace') {
       var el = editorRef.current;
@@ -651,14 +973,39 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
       }
     }
 
+    /* hint 之后不是合法插入点，而 ArrowRight / ArrowDown / End 原生的下一跳都会先跨
+     * 过去、再由 selectionchange 拉回——视觉上闪一帧。这里在按键阶段直接拦下，
+     * 把 caret 落到 hint 之前（那时它就是唯一合法的落点）。 */
+    if (!e.shiftKey && (e.key === 'ArrowRight' || e.key === 'ArrowDown' || e.key === 'ArrowUp' || e.key === 'End')) {
+      var _sel = window.getSelection();
+      var _el = editorRef.current;
+      var _range = _sel && _sel.rangeCount > 0 ? _sel.getRangeAt(0) : null;
+      if (_sel && _el && _range && _range.collapsed && _el.contains(_range.startContainer)) {
+        /* Ctrl/Cmd+End 会跳到整篇末尾（= hint 之后），与普通 End 同样拦下 */
+        var isDocEnd = e.key === 'End' && (e.ctrlKey || e.metaKey);
+        var isVertical = e.key === 'ArrowDown' || e.key === 'ArrowUp';
+        var crossesHint = e.key === 'ArrowRight' && isCaretBeforeHint(_range, _el) || isVertical && wouldArrowCrossHint(_range, _el, e.key === 'ArrowDown' ? 'down' : 'up') || e.key === 'End' && (isDocEnd || isCaretOnHintLine(_range, _el));
+        if (crossesHint) {
+          e.preventDefault();
+          /* ↓ 若本来就在 hint 所在行，则「无处可去」→ 原地不动；
+           * 其余情况统一落到 hint 之前（那里才是唯一合法插入点）。 */
+          if (!(e.key === 'ArrowDown' && isCaretOnHintLine(_range, _el))) {
+            placeCaretBeforeHint();
+          }
+          recomputeTrigger();
+          return;
+        }
+      }
+    }
+
     // ArrowLeft / ArrowRight：跨越 chip 边界时一次到位（绕开 ZWSP 锚点造成的"卡一格"）
     if ((e.key === 'ArrowLeft' || e.key === 'ArrowRight') && !e.shiftKey) {
-      var _sel = window.getSelection();
-      if (_sel && _sel.rangeCount > 0) {
+      var _sel2 = window.getSelection();
+      if (_sel2 && _sel2.rangeCount > 0) {
         var _editorRef$current3;
-        var _range = _sel.getRangeAt(0);
-        if (_range.collapsed && (_editorRef$current3 = editorRef.current) !== null && _editorRef$current3 !== void 0 && _editorRef$current3.contains(_range.startContainer)) {
-          var target = resolveCaretMove(_range, e.key === 'ArrowLeft' ? 'left' : 'right', editorRef.current);
+        var _range2 = _sel2.getRangeAt(0);
+        if (_range2.collapsed && (_editorRef$current3 = editorRef.current) !== null && _editorRef$current3 !== void 0 && _editorRef$current3.contains(_range2.startContainer)) {
+          var target = resolveCaretMove(_range2, e.key === 'ArrowLeft' ? 'left' : 'right', editorRef.current);
           if (target) {
             e.preventDefault();
             var r = document.createRange();
@@ -666,8 +1013,8 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
             r.collapse(true);
             // 本次已在 keydown 同步完成 caret 落位：跳过下一次 selectionchange 重算。
             suppressSelectionChangeOnceRef.current = true;
-            _sel.removeAllRanges();
-            _sel.addRange(r);
+            _sel2.removeAllRanges();
+            _sel2.addRange(r);
             lastEditorRangeRef.current = r.cloneRange();
             recomputeTrigger();
             return;
@@ -685,10 +1032,66 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
       e.preventDefault();
       insertLineBreak();
     }
-  }, [inputModality, onPressEnter, insertLineBreak, removeChip, onTriggerKeyDown, fireChange, recomputeTrigger]);
+  }, [inputModality, onPressEnter, insertLineBreak, placeCaretBeforeHint, removeChip, onTriggerKeyDown, acceptHintAsText, fireChange, recomputeTrigger]);
   var handlePointerInput = useCallback(function () {
     if (inputModality !== 'pointer') setInputModality('pointer');
   }, [inputModality]);
+
+  /**
+   * mouseup 兜底：极少数路径（多击 / 浏览器差异）caret 可能在 mousedown 之后才
+   * 落位。这里再校一次，仍然在下一帧绘制之前完成，不会留下闪帧。
+   */
+  var handleEditorMouseUp = useCallback(function () {
+    pullCaretBeforeHint();
+  }, [pullCaretBeforeHint]);
+
+  /**
+   * 点击落在 hint 之后（含点在提示文案自己身上）时，浏览器会先把 caret 放到
+   * 提示文案末尾，下一帧才被 selectionchange 拉回来 —— 视觉上就是「闪一下」。
+   * 这里用点击坐标预判原生落点，命中就 preventDefault 并自己落 caret，
+   * 连那一帧都不给。
+   *
+   * 注意不要按 `e.detail` 放行多击：连点（双击 / 三击）时 `detail` 会变成 2、3，
+   * 一旦放行，第二次点击就又会先落到 hint 之后（高频点击复现的原因）。
+   * 该区域本来就没有可选文本（hint 是 user-select:none 的派生展示），
+   * 双击选词/三击整行在这里没有语义，拦掉是安全的。
+   */
+  var handleEditorMouseDown = useCallback(function (e) {
+    handlePointerInput();
+    if (e.button !== 0 || disabled) return;
+    // shift+click 是扩选，不劫持
+    if (e.shiftKey) return;
+    var el = editorRef.current;
+    var hint = hintNodeRef.current;
+    if (!el || !hint || !hint.isConnected) return;
+
+    /* 两条命中判据：
+     * 1. 坐标直接落在 hint 的视觉行上 —— 原生落点不可控（可能进 hint 内部、
+     *    行首、甚至 hint 之后），只有坐标是确定的；
+     * 2. 原生落点解析在 hint 之后（点在同一行右侧留白等处）。
+     * 命中任一条都接管，别让原生 caret 先画一帧。 */
+    var onHint = isPointOnHint(e.clientX, e.clientY, hint);
+    if (!onHint) {
+      var point = caretRangeFromPoint(e.clientX, e.clientY);
+      if (!point) return;
+      if (!isPositionAfterHint(point.startContainer, point.startOffset, hint)) {
+        return;
+      }
+      /* chip 之后可能有空行（用户按 Enter 留了一行又把内容删光）：点在那
+       * 些行上要正常落 caret，不能被拽回 hint 所在行。pointLine 为空 =
+       * 点在行留白 / 编辑器 padding 上，这种仍按「末尾」处理。 */
+      var pointLine = getCurrentLine(point.startContainer, el);
+      if (pointLine && pointLine !== hint.parentElement) return;
+    }
+    e.preventDefault();
+    /* 先 focus 再写 selection：未聚焦时写进去的 range 会被 focus 的默认行为
+     * 覆盖（首次点击恰好是这种情况）。 */
+    el.focus({
+      preventScroll: true
+    });
+    placeCaretBeforeHint();
+    requestScrollCaretIntoView();
+  }, [disabled, handlePointerInput, placeCaretBeforeHint, requestScrollCaretIntoView]);
   var writeClipboardPayload = useCallback(function (e, payload) {
     if (!payload) return false;
     e.clipboardData.setData(COMPOSER_CLIPBOARD_MIME, JSON.stringify(payload));
@@ -817,7 +1220,8 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     onCompositionEnd: handleCompositionEnd,
     onKeyDown: handleKeyDown,
     onMouseMove: handlePointerInput,
-    onMouseDown: handlePointerInput,
+    onMouseDown: handleEditorMouseDown,
+    onMouseUp: handleEditorMouseUp,
     onPointerMove: handlePointerInput,
     onCopy: handleCopy,
     onCut: handleCut,

package/dist/composer/hooks/useChipManager.d.ts

@@ -29,8 +29,20 @@ export interface UseChipManagerReturn {
     insertChip: (data: ChipData, editor: HTMLElement, preferredRange?: Range | null) => void;
     /** 在指定 range 处插入 chip（调用方负责 deleteContents）。 */
     insertChipAtRange: (data: ChipData, range: Range, editor: HTMLElement) => HTMLSpanElement;
-    /** 将含 marker 的 raw value + chips 插入 range（粘贴用）。 */
-    insertSerializedAtRange: (value: string, chips: ChipData[], range: Range, editor: HTMLElement) => void;
+    /** 将含 marker 的 raw value + chips 插入 range（粘贴 / 初始化还原用）。 */
+    insertSerializedAtRange: (value: string, chips: ChipData[], range: Range, editor: HTMLElement, 
+    /**
+     * `focus: false` 时插入后不把焦点交给编辑器。
+     * 首屏还原 defaultValue / defaultChips 必须传 false：默认 focus() 会把
+     * 页面滚动到编辑器（浏览器「聚焦元素进入视口」），导致进页面就跳位置。
+     *
+     * `caret: false` 时不主动改写 selection（后台预填用，避免抢走用户
+     * 在别处的光标）。单行路径由调用方传自己的 range，不受影响。
+     */
+    options?: {
+        focus?: boolean;
+        caret?: boolean;
+    }) => void;
     /** 移除已从 DOM 摘下的 chip 状态（cut / 选区删除后）。 */
     syncChipsAfterDomMutation: (editor: HTMLElement) => void;
     /** 按 chip id 移除。 */