one-design-next 0.0.112 → 0.0.114

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, 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, ensureLineRoots, getPlainText, isEditorEmpty, 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 的可视区）内。
  *
@@ -237,11 +243,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 +368,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 +392,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 +426,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 +488,7 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
         if (!el) return;
         el.innerHTML = '';
         el.appendChild(createLineRoot());
+        removeHintNode();
         resetChips();
         setEmpty(true);
         if (triggerRef.current) {
@@ -418,8 +584,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 +631,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 +706,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 +749,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 +803,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 +843,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 +883,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 +902,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 +1090,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,16 @@ 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() 会把
+     * 页面滚动到编辑器（浏览器「聚焦元素进入视口」），导致进页面就跳位置。
+     */
+    options?: {
+        focus?: boolean;
+    }) => void;
     /** 移除已从 DOM 摘下的 chip 状态（cut / 选区删除后）。 */
     syncChipsAfterDomMutation: (editor: HTMLElement) => void;
     /** 按 chip id 移除。 */

package/dist/composer/hooks/useChipManager.js

@@ -16,7 +16,7 @@ import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
  */
 
 import { useCallback, useRef, useState } from 'react';
-import { createLineRoot, ensureLineRoots, forEachMarkerSegment, getCurrentLineRoot, LINE_ATTR_NAME } from "../utils";
+import { createLineRoot, ensureLineRoots, forEachMarkerSegment, getCurrentLineRoot, LINE_ATTR_NAME, stripInvisibleChars, ZWSP } from "../utils";
 
 /** chip 在 React 状态中的形态：data + 对应的 DOM host。 */
 
@@ -27,6 +27,24 @@ function createChipHost(data) {
   host.setAttribute('data-odn-composer-chip-host', '');
   return host;
 }
+
+/**
+ * 在 host 后面垫一个「不进 value」的 ZWSP 文本锚点并返回它。
+ *
+ * chip 后面没有正文时（行尾 / 后面只剩派生 hint / 后面紧跟着另一个 chip），
+ * caret 若只靠「元素偏移」落位，部分浏览器会把它带到结构块之后；垫一个只含
+ * ZWSP 的文本节点，caret 始终有真实文本落点，而 `getPlainText` 会把整段剔掉，
+ * 因此不会进 value / segments / 剪贴板。已有锚点直接复用，避免越积越多。
+ */
+function ensureCaretAnchorAfter(host) {
+  var _tail$textContent, _tail$textContent2;
+  var parent = host.parentNode;
+  var tail = host.nextSibling;
+  var reusable = (tail === null || tail === void 0 ? void 0 : tail.nodeType) === Node.TEXT_NODE && ((_tail$textContent = tail.textContent) !== null && _tail$textContent !== void 0 ? _tail$textContent : '') !== '' && stripInvisibleChars((_tail$textContent2 = tail.textContent) !== null && _tail$textContent2 !== void 0 ? _tail$textContent2 : '') === '' ? tail : null;
+  var anchor = reusable !== null && reusable !== void 0 ? reusable : document.createTextNode(ZWSP);
+  if (!reusable) parent.insertBefore(anchor, tail);
+  return anchor;
+}
 function createCaretAnchorAtBoundary(parent, offset) {
   var _parent$childNodes, _parent$childNodes$sa;
   var len = parent.childNodes.length;
@@ -120,17 +138,27 @@ onAfterMutate) {
     var newRange = document.createRange();
     var parent = host.parentNode;
     if (parent) {
-      var _nextText$textContent, _nextText$textContent2;
+      var _next$textContent, _nextText$textContent, _stripInvisibleChars$;
+      /* insertNode 在文本末尾切一刀会留下空文本节点，它等同于「后面没内容」，
+       * 不能当成「后面有正文」（否则行尾 chip 的 hint 永远不出现）。
+       * 纯 ZWSP 锚点文本（caret 落点）同理——它不是正文。 */
       var next = host.nextSibling;
-      var nextText = (next === null || next === void 0 ? void 0 : next.nodeType) === Node.TEXT_NODE ? next : null;
-      var leading = (_nextText$textContent = nextText === null || nextText === void 0 || (_nextText$textContent2 = nextText.textContent) === null || _nextText$textContent2 === void 0 ? void 0 : _nextText$textContent2[0]) !== null && _nextText$textContent !== void 0 ? _nextText$textContent : '';
-      if (!nextText || !/\s/.test(leading)) {
-        var spacer = document.createTextNode(' ');
-        parent.insertBefore(spacer, next);
-        newRange.setStart(spacer, 1);
+      var nextText = (next === null || next === void 0 ? void 0 : next.nodeType) === Node.TEXT_NODE && ((_next$textContent = next.textContent) !== null && _next$textContent !== void 0 ? _next$textContent : '') !== '' ? next : null;
+      var nextRaw = (_nextText$textContent = nextText === null || nextText === void 0 ? void 0 : nextText.textContent) !== null && _nextText$textContent !== void 0 ? _nextText$textContent : '';
+      /* 跳过零宽锚点前缀后的第一个字符；空格也算用户已有的内容。 */
+      var firstContentChar = (_stripInvisibleChars$ = stripInvisibleChars(nextRaw)[0]) !== null && _stripInvisibleChars$ !== void 0 ? _stripInvisibleChars$ : '';
+
+      /* 插入 chip 从不往内容里写空格：补出来的空格会进 value / segments，
+       * 变成用户没输入过的字符。间隔由 chip 自身的 padding（0 4px）提供。
+       *   - 后面紧跟正文：caret 直接落到正文起点
+       *   - 后面是另一个 chip / 行尾 / 只剩派生 hint / 只有 ZWSP 锚点：垫一个
+       *     不进 value 的 ZWSP 锚点给 caret 落位 */
+      if (nextText && firstContentChar) {
+        newRange.setStart(nextText, nextRaw.indexOf(firstContentChar));
       } else {
-        var _nextText$textContent3;
-        newRange.setStart(nextText, Math.min(1, ((_nextText$textContent3 = nextText.textContent) !== null && _nextText$textContent3 !== void 0 ? _nextText$textContent3 : '').length));
+        var _anchor$textContent;
+        var anchor = ensureCaretAnchorAfter(host);
+        newRange.setStart(anchor, ((_anchor$textContent = anchor.textContent) !== null && _anchor$textContent !== void 0 ? _anchor$textContent : '').length);
       }
     } else {
       newRange.setStartAfter(host);
@@ -143,7 +171,7 @@ onAfterMutate) {
     });
     onAfterMutate === null || onAfterMutate === void 0 || onAfterMutate();
   }, [insertChipAtRange, onAfterMutate]);
-  var insertSerializedAtRange = useCallback(function (value, chipList, range, editor) {
+  var insertSerializedAtRange = useCallback(function (value, chipList, range, editor, options) {
     var chipById = new Map(chipList.map(function (c) {
       return [c.id, c];
     }));
@@ -260,9 +288,14 @@ onAfterMutate) {
       chipsRef.current = next;
       setChips(next);
     }
-    requestAnimationFrame(function () {
-      return editor.focus();
-    });
+
+    /* 默认保持原行为（粘贴 / Tab 采纳都发生在已聚焦的编辑器里，focus 是幂等的）。
+     * 首屏还原内容必须显式关掉：mount 期间 focus() 会连带触发页面滚动。 */
+    if ((options === null || options === void 0 ? void 0 : options.focus) !== false) {
+      requestAnimationFrame(function () {
+        return editor.focus();
+      });
+    }
     onAfterMutate === null || onAfterMutate === void 0 || onAfterMutate();
   }, [onAfterMutate]);
   var syncChipsAfterDomMutation = useCallback(function (editor) {

package/dist/composer/index.d.ts

@@ -76,6 +76,12 @@ export interface ComposerProps {
      * `segments`：有序内容 IR，业务按数组顺序自定义拼后端。
      * `meta`：附件 / 联网搜索等非正文数据；为空时不传。
      *
+     * **派生 `hint` 段**：当最后一个 chip 是带 `SkillItem.hint` 的 skill、且其后
+     * 一个字符都没有（空格 / 换行都算内容）时，该提示文案会作为
+     * `{ type: 'hint', data: { text } }` 出现在 segments 末尾——与输入框里那段
+     * 灰字同源同谓词，不会漂移。不需要它的业务直接 filter / `isHintSegment`
+     * 判一下即可。
+     *
      * 兼容旧链路（需要单串文本）：业务可调 `segmentsToReadableText(segments)`。
      *
      * **返回值语义**：