try(widget): 尝试保留便签手动滚动（编译通过，待验证） / Try preserving sticky-note manual scrolling (build passed, validation pending)

中文：
- 仅在光标、选区或输入内容变化后执行一次光标可见性调整。
- 多行输入框发生手动滚轮滚动后保留用户偏移，后续编辑时恢复光标跟随。
- 增加光标跟随请求状态的规则测试。

English:
- Adjust caret visibility once after caret, selection, or input content changes.
- Preserve the user's wheel offset in multiline inputs and resume caret following after later edits.
- Add rule coverage for caret-follow request state.

验证 / Validation:
- cmake --build .build --config Release --target SnowDesktopWidgetTextInputRulesTests（通过 / passed）
- .build\\Release\\SnowDesktopWidgetTextInputRulesTests.exe（通过 / passed）
- scripts\\build.bat（未运行：待执行完整 Release 构建 / not run: full Release build pending）
- 便签末尾光标滚动场景（未运行：待宿主交互验证 / not run: host interaction validation pending）

限制 / Limitations:
- 尚未完成完整宿主构建与便签实际交互验证 / Full host build and live sticky-note interaction are not yet verified

Author: FreeFallingSnow

src/widget_engine.cpp

@@ -7920,7 +7920,9 @@ static int lua_UiTextArea(lua_State* L)
                 focusedLayout->HitTestTextPosition(
                     hitPosition, trailing, &caretX, &caretY,
                     &caretMetrics));
-            if (hasCaret && s && s->engine)
+            if (hasCaret && s && s->engine &&
+                s->engine->RuntimeConsumeHostInputCaretVisibilityRequest(
+                    BoundWidgetId(L), id))
             {
                 const float caretTop = padding + caretY;
                 const float caretBottom = caretTop +
@@ -26483,6 +26485,7 @@ void WidgetEngine::RuntimeRegisterHostControl(const std::wstring& widgetId,
                 focusedHostInput_.cursor = *cursor;
                 focusedHostInput_.compositionText.clear();
                 focusedHostInput_.compositionCursor = 0;
+                focusedHostInput_.caretVisibility.Request();
             }
         }
     }
@@ -26613,6 +26616,7 @@ bool WidgetEngine::RuntimeFocusHostInput(const std::wstring& widgetId,
                     found->selectAll ? 0 : storedText.size();
                 focusedHostInput_.compositionText.clear();
                 focusedHostInput_.compositionCursor = 0;
+                focusedHostInput_.caretVisibility.Request();
             }
         }
         focusedHostInput_.multiline = found->multiline;
@@ -26645,8 +26649,10 @@ bool WidgetEngine::RuntimeFocusHostInput(const std::wstring& widgetId,
             {
                 focusedHostInput_.selectionAnchor = *anchor;
                 focusedHostInput_.cursor = *cursor;
+                focusedHostInput_.caretVisibility.Request();
             }
         }
+        focusedHostInput_.caretVisibility.Request();
         if (hostInputFocusCallback_)
             hostInputFocusCallback_();
         return true;
@@ -26702,6 +26708,7 @@ bool WidgetEngine::RuntimeFocusHostInput(const std::wstring& widgetId,
     focusedHostInput_.step = found->step;
     focusedHostInput_.maximumUtf8Bytes =
         found->maximumUtf8Bytes;
+    focusedHostInput_.caretVisibility.Request();
     DispatchHostInputAction(widgetId, id,
         focusedHostInput_.focusAction, "focus",
         focusedHostInput_.text, false,
@@ -26913,6 +26920,17 @@ bool WidgetEngine::RuntimeFocusViewTarget(const std::wstring& widgetId,
     return true;
 }
 
+bool WidgetEngine::RuntimeConsumeHostInputCaretVisibilityRequest(
+    const std::wstring& widgetId, const std::string& id)
+{
+    if (!focusedHostInput_.active ||
+        focusedHostInput_.widgetId != widgetId ||
+        focusedHostInput_.id != id ||
+        focusedHostInput_.surface != CurrentWidgetSurface(d2dState_))
+        return false;
+    return focusedHostInput_.caretVisibility.Consume();
+}
+
 void WidgetEngine::BeginHostLogicalSlotPointer(
     LuaWidget& widget, int x, int y)
 {
@@ -27950,6 +27968,7 @@ bool WidgetEngine::HandleHostInputPointerMove(
     }
     focusedHostInput_.cursor = HitTestHostInputPosition(
         *control, widgetId, x, y);
+    focusedHostInput_.caretVisibility.Request();
     RuntimeInvalidateHost(widgetId);
     return true;
 }
@@ -27977,9 +27996,12 @@ bool WidgetEngine::HandleHostInputPointerUp(
                     HostControlBelongsToSurface(item, surface);
             });
         if (control != controls.rend())
+        {
             focusedHostInput_.cursor =
                 HitTestHostInputPosition(
                     *control, widgetId, x, y);
+            focusedHostInput_.caretVisibility.Request();
+        }
     }
     DispatchHostInputSelectionChange(widgetId,
         focusedHostInput_.id,
@@ -28175,6 +28197,7 @@ bool WidgetEngine::RuntimePerformAccessibilityAction(
             focusedHostInput_.selectionAnchor = value.size();
             focusedHostInput_.compositionText.clear();
             focusedHostInput_.compositionCursor = 0;
+            focusedHostInput_.caretVisibility.Request();
         }
 
         if (control->controlled)
@@ -28591,6 +28614,7 @@ bool WidgetEngine::SetHostInputComposition(
     focusedHostInput_.compositionText = text;
     focusedHostInput_.compositionCursor =
         std::min(cursor, text.size());
+    focusedHostInput_.caretVisibility.Request();
     RuntimeInvalidateHost(focusedHostInput_.widgetId);
     return true;
 }
@@ -28628,6 +28652,7 @@ bool WidgetEngine::CommitHostInputComposition(
     {
         focusedHostInput_.compositionText.clear();
         focusedHostInput_.compositionCursor = 0;
+        focusedHostInput_.caretVisibility.Request();
         RuntimeInvalidateHost(focusedHostInput_.widgetId);
         return true;
     }
@@ -28636,6 +28661,7 @@ bool WidgetEngine::CommitHostInputComposition(
         focusedHostInput_.cursor;
     focusedHostInput_.compositionText.clear();
     focusedHostInput_.compositionCursor = 0;
+    focusedHostInput_.caretVisibility.Request();
     if (focusedHostInput_.liveUpdate)
     {
         if (focusedHostInput_.controlled)
@@ -28660,6 +28686,7 @@ void WidgetEngine::ClearHostInputComposition()
         return;
     focusedHostInput_.compositionText.clear();
     focusedHostInput_.compositionCursor = 0;
+    focusedHostInput_.caretVisibility.Request();
     RuntimeInvalidateHost(focusedHostInput_.widgetId);
 }
 
@@ -28714,6 +28741,7 @@ bool WidgetEngine::HandleHostInputChar(wchar_t ch)
     focusedHostInput_.cursor = nextCursor;
     focusedHostInput_.selectionAnchor =
         focusedHostInput_.cursor;
+    focusedHostInput_.caretVisibility.Request();
     if (focusedHostInput_.liveUpdate)
     {
         if (focusedHostInput_.controlled)
@@ -28794,6 +28822,7 @@ bool WidgetEngine::HandleHostInputKey(WPARAM key)
         if (!shift)
             focusedHostInput_.selectionAnchor =
                 focusedHostInput_.cursor;
+        focusedHostInput_.caretVisibility.Request();
         dispatchSelectionChange();
         RuntimeInvalidateHost(focusedHostInput_.widgetId);
         return true;
@@ -28836,6 +28865,7 @@ bool WidgetEngine::HandleHostInputKey(WPARAM key)
     {
         focusedHostInput_.selectionAnchor = 0;
         focusedHostInput_.cursor = focusedHostInput_.text.size();
+        focusedHostInput_.caretVisibility.Request();
         dispatchSelectionChange();
         RuntimeInvalidateHost(focusedHostInput_.widgetId);
         return true;
@@ -29099,6 +29129,7 @@ bool WidgetEngine::HandleHostInputKey(WPARAM key)
 
     if (changed)
     {
+        focusedHostInput_.caretVisibility.Request();
         if (focusedHostInput_.liveUpdate)
         {
             if (focusedHostInput_.controlled)
@@ -29373,6 +29404,13 @@ bool WidgetEngine::HandleHostUiPointer(const std::wstring& widgetId, int x, int
             if (!result.moved)
                 continue;
             offset = result.offset;
+            if (focusedHostInput_.active &&
+                focusedHostInput_.widgetId == widgetId &&
+                focusedHostInput_.id == it->id &&
+                focusedHostInput_.surface == normalizedSurface)
+            {
+                focusedHostInput_.caretVisibility.PreserveManualScroll();
+            }
             const std::string targetKey = it->id;
             {
                 snowdesktop::widget_runtime::WidgetTrustedGestureScope
@@ -29406,6 +29444,7 @@ bool WidgetEngine::HandleHostUiPointer(const std::wstring& widgetId, int x, int
                 focusedHostInput_.selectionAnchor =
                     focusedHostInput_.cursor;
                 focusedHostInput_.pointerSelecting = true;
+                focusedHostInput_.caretVisibility.Request();
                 RuntimeInvalidateHost(widgetId);
             }
             return true;

src/widget_engine.h

@@ -1538,6 +1538,8 @@ class WidgetEngine
     bool RuntimeGetFocusedHostInput(const std::wstring& widgetId, const std::string& id,
         std::wstring& text, size_t& cursor, size_t& selectionAnchor,
         std::wstring& compositionText, size_t& compositionCursor) const;
+    bool RuntimeConsumeHostInputCaretVisibilityRequest(
+        const std::wstring& widgetId, const std::string& id);
     bool RuntimeIsWidgetSelected(const std::wstring& widgetId) const;
     std::vector<LuaWidgetAccessibilitySnapshot>
         RuntimeAccessibilitySnapshots() const;
@@ -1910,6 +1912,8 @@ class WidgetEngine
         bool numeric = false;
         bool liveUpdate = true;
         bool multiline = false;
+        snowdesktop::widget_runtime::HostInputCaretVisibilityRequest
+            caretVisibility;
         float minimum = 0.0f;
         float maximum = 1.0f;
         float step = 0.01f;

src/widget_text_input_rules.cpp

@@ -82,6 +82,23 @@ const std::string& DeferredHostInputFocus::ControlId() const noexcept
     return controlId_;
 }
 
+void HostInputCaretVisibilityRequest::Request() noexcept
+{
+    pending_ = true;
+}
+
+void HostInputCaretVisibilityRequest::PreserveManualScroll() noexcept
+{
+    pending_ = false;
+}
+
+bool HostInputCaretVisibilityRequest::Consume() noexcept
+{
+    const bool pending = pending_;
+    pending_ = false;
+    return pending;
+}
+
 std::size_t Utf8BytesForHostText(std::wstring_view text) noexcept
 {
     std::size_t bytes = 0;

src/widget_text_input_rules.h

@@ -22,6 +22,17 @@ class DeferredHostInputFocus
     std::string surface_;
 };
 
+class HostInputCaretVisibilityRequest
+{
+public:
+    void Request() noexcept;
+    void PreserveManualScroll() noexcept;
+    bool Consume() noexcept;
+
+private:
+    bool pending_ = false;
+};
+
 std::size_t Utf8BytesForHostText(std::wstring_view text) noexcept;
 std::size_t Utf8ByteOffsetForHostTextOffset(
     std::wstring_view text, std::size_t hostOffset) noexcept;

tests/widget_text_input_rules_tests.cpp

@@ -96,6 +96,25 @@ void TestDeferredFocusRequest()
     Check(!request.Active() && request.ControlId().empty(),
         "consuming deferred focus clears the request");
 }
+
+void TestCaretVisibilityRequest()
+{
+    using snowdesktop::widget_runtime::HostInputCaretVisibilityRequest;
+
+    HostInputCaretVisibilityRequest request;
+    Check(!request.Consume(),
+        "caret visibility starts without a pending adjustment");
+    request.Request();
+    Check(request.Consume() && !request.Consume(),
+        "caret visibility is consumed once after focus or editing");
+    request.Request();
+    request.PreserveManualScroll();
+    Check(!request.Consume(),
+        "manual multiline scrolling cancels the pending caret adjustment");
+    request.Request();
+    Check(request.Consume(),
+        "later caret movement restores caret-follow scrolling");
+}
 }
 
 int main()
@@ -104,6 +123,7 @@ int main()
     TestBoundedReplacement();
     TestReadOnlyMutationGate();
     TestDeferredFocusRequest();
+    TestCaretVisibilityRequest();
     if (failures != 0)
     {
         std::cerr << failures << " widget text-input rule checks failed\n";