chore: Capture intended values with scrollIndex and scrollPercent (#13084) 9ebf0f88df
Setting scrollIndex/scrollPercent converts immediately to scrollOffset using live layout bounds, so a set while the layout couldn't answer (display hidden, pre-layout, no items yet) converted against zeroed bounds and destroyed the value — and two-way binds then pushed the recomputed garbage back into the view model.

Sets are now recorded as a per-axis intent tagged with their space and resolved eagerly; when layout can't answer, the intent is held and retried in constrain(), reading back verbatim until it resolves, then discarded (one-shot, RecyclerView-style pending scroll). User interaction drops held intents. Implemented in both rive_core and the C++ runtime; no serialization changes.

Behavior changes (web scrollTo semantics):

Out-of-range indices clamp to the ends instead of snapping to the start.
Resolved offsets clamp to the scrollable range — also removes per-frame relayout churn from overshooting sets (hence the component_list_child_origin silver rebaseline; rendering is identical).
C++ 2-D index sets write both axes, matching the editor.

Co-authored-by: Philip Chung <philterdesign@gmail.com>
diff --git a/.rive_head b/.rive_head
index 2b4e3f6..a484a67 100644
--- a/.rive_head
+++ b/.rive_head
@@ -1 +1 @@
-d24376c1d692b4687141dbcff2bc4b84f3de8c66
+9ebf0f88df7a292be01f95fcf6e3ccf0abe07954
diff --git a/include/rive/constraints/scrolling/scroll_constraint.hpp b/include/rive/constraints/scrolling/scroll_constraint.hpp
index b76c7e8..9d2b788 100644
--- a/include/rive/constraints/scrolling/scroll_constraint.hpp
+++ b/include/rive/constraints/scrolling/scroll_constraint.hpp
@@ -19,6 +19,20 @@
                          public LayoutConstraint
 {
 private:
+    // Coordinate space a scroll write was expressed in.
+    enum class ScrollSpace : uint8_t
+    {
+        none,
+        percent,
+        index,
+    };
+    // A percent/index write awaiting conversion to an offset.
+    struct ScrollAxisIntent
+    {
+        ScrollSpace space = ScrollSpace::none;
+        float value = 0;
+    };
+
     ScrollPhysics* m_physics;
     ScrollVirtualizer* m_virtualizer = nullptr;
     std::vector<LayoutNodeProvider*> m_layoutChildren;
@@ -37,13 +51,32 @@
     bool m_isScrollBarDragging = false;
     bool m_hasListChildren = false;
 
+    // Unresolved writes per axis; held until layout can convert.
+    ScrollAxisIntent m_intentX;
+    ScrollAxisIntent m_intentY;
+
     AABB boundsForFlatIndex(size_t index);
-    Vec2D positionAtIndex(float index);
+    /// Returns false when layout can't resolve the index yet; out-of-range
+    /// indices clamp to the ends.
+    bool positionAtIndex(float index, Vec2D& outPosition);
     float indexAtPosition(Vec2D pos);
     float maxOffsetXForPercent();
     float maxOffsetYForPercent();
     bool isBoundsCollapsed(AABB bounds);
     std::vector<Vec2D> collectSnapPoints();
+    bool scrollLayoutResolvable(bool isX);
+    float clampResolvedOffset(float value, bool isX);
+    bool resolveIntent(const ScrollAxisIntent& intent,
+                       bool isX,
+                       float& outOffset);
+    void setIntentX(ScrollAxisIntent intent);
+    void setIntentY(ScrollAxisIntent intent);
+    void resolveScrollIntents();
+    void clearScrollIntents()
+    {
+        m_intentX.space = ScrollSpace::none;
+        m_intentY.space = ScrollSpace::none;
+    }
 
 public:
     ~ScrollConstraint();
@@ -121,6 +154,8 @@
     {
         if (!m_isScrollBarDragging && value)
         {
+            // User interaction supersedes held intents.
+            clearScrollIntents();
             // Prime the snapshot so the first advance comparison is
             // meaningful (otherwise a stale value falsely flags motion).
             m_lastFrameOffsetX = scrollOffsetX();
diff --git a/src/constraints/scrolling/scroll_constraint.cpp b/src/constraints/scrolling/scroll_constraint.cpp
index 0662643..038e97b 100644
--- a/src/constraints/scrolling/scroll_constraint.cpp
+++ b/src/constraints/scrolling/scroll_constraint.cpp
@@ -193,6 +193,7 @@
 
 void ScrollConstraint::constrain(TransformComponent* component)
 {
+    resolveScrollIntents();
     m_scrollTransform =
         Mat2D::fromTranslate(constrainsHorizontal() ? clampedOffsetX() : 0,
                              constrainsVertical() ? clampedOffsetY() : 0);
@@ -411,6 +412,8 @@
 void ScrollConstraint::initPhysics()
 {
     m_isDragging = true;
+    // User interaction supersedes held intents.
+    clearScrollIntents();
     m_lastFrameOffsetX = scrollOffsetX();
     m_lastFrameOffsetY = scrollOffsetY();
     if (m_physics != nullptr)
@@ -463,16 +466,30 @@
 
 float ScrollConstraint::scrollPercentX()
 {
+    if (m_intentX.space == ScrollSpace::percent)
+    {
+        return m_intentX.value;
+    }
     return maxOffsetX() != 0 ? scrollOffsetX() / maxOffsetXForPercent() : 0;
 }
 
 float ScrollConstraint::scrollPercentY()
 {
+    if (m_intentY.space == ScrollSpace::percent)
+    {
+        return m_intentY.value;
+    }
     return maxOffsetY() != 0 ? scrollOffsetY() / maxOffsetYForPercent() : 0;
 }
 
 float ScrollConstraint::scrollIndex()
 {
+    const ScrollAxisIntent& intent =
+        constrainsHorizontal() ? m_intentX : m_intentY;
+    if (intent.space == ScrollSpace::index)
+    {
+        return intent.value;
+    }
     return indexAtPosition(Vec2D(scrollOffsetX(), scrollOffsetY()));
 }
 
@@ -483,8 +500,7 @@
         return;
     }
     stopPhysics();
-    float to = value * maxOffsetXForPercent();
-    scrollOffsetX(to);
+    setIntentX({ScrollSpace::percent, value});
 }
 
 void ScrollConstraint::setScrollPercentY(float value)
@@ -494,8 +510,7 @@
         return;
     }
     stopPhysics();
-    float to = value * maxOffsetYForPercent();
-    scrollOffsetY(to);
+    setIntentY({ScrollSpace::percent, value});
 }
 
 void ScrollConstraint::setScrollIndex(float value)
@@ -505,37 +520,165 @@
         return;
     }
     stopPhysics();
-    Vec2D to = positionAtIndex(value);
     if (constrainsHorizontal())
     {
-        scrollOffsetX(to.x);
+        setIntentX({ScrollSpace::index, value});
     }
-    else if (constrainsVertical())
+    if (constrainsVertical())
     {
-        scrollOffsetY(to.y);
+        setIntentY({ScrollSpace::index, value});
     }
 }
 
-Vec2D ScrollConstraint::positionAtIndex(float index)
+// False while hidden or before the first layout pass on the given axis.
+bool ScrollConstraint::scrollLayoutResolvable(bool isX)
 {
-    if (!std::isfinite(index))
+    auto vp = viewport();
+    if (vp == nullptr)
     {
-        return Vec2D();
+        return false;
+    }
+    return isX ? vp->layoutWidth() > 0 : vp->layoutHeight() > 0;
+}
+
+// Resolved offsets clamp to the scrollable range.
+float ScrollConstraint::clampResolvedOffset(float value, bool isX)
+{
+    if (infinite())
+    {
+        return value;
+    }
+    return math::clamp(value, isX ? maxOffsetX() : maxOffsetY(), 0.0f);
+}
+
+// Convert an intent to an offset; false if layout can't resolve yet.
+bool ScrollConstraint::resolveIntent(const ScrollAxisIntent& intent,
+                                     bool isX,
+                                     float& outOffset)
+{
+    // Non-finite indices resolve to the origin without needing layout.
+    if (intent.space == ScrollSpace::index &&
+        (std::isnan(intent.value) ||
+         (infinite() && !std::isfinite(intent.value))))
+    {
+        outOffset = 0;
+        return true;
+    }
+    // Gate both spaces: virtualized lists compute item bounds from authored
+    // sizes, which resolve even while the viewport layout is collapsed.
+    if (!scrollLayoutResolvable(isX))
+    {
+        return false;
+    }
+    switch (intent.space)
+    {
+        case ScrollSpace::percent:
+        {
+            float contentSize = isX ? contentWidth() : contentHeight();
+            if (contentSize <= 0)
+            {
+                // No measured content — can't resolve.
+                return false;
+            }
+            float maxForPercent =
+                isX ? maxOffsetXForPercent() : maxOffsetYForPercent();
+            outOffset = clampResolvedOffset(intent.value * maxForPercent, isX);
+            return true;
+        }
+        case ScrollSpace::index:
+        {
+            Vec2D to;
+            if (!positionAtIndex(intent.value, to))
+            {
+                return false;
+            }
+            outOffset = clampResolvedOffset(isX ? to.x : to.y, isX);
+            return true;
+        }
+        case ScrollSpace::none:
+            break;
+    }
+    return false;
+}
+
+// Resolve eagerly; unresolved intents are held and retried in constrain().
+void ScrollConstraint::setIntentX(ScrollAxisIntent intent)
+{
+    float resolved;
+    if (!resolveIntent(intent, true, resolved))
+    {
+        m_intentX = intent;
+        return;
+    }
+    m_intentX.space = ScrollSpace::none;
+    scrollOffsetX(resolved);
+}
+
+void ScrollConstraint::setIntentY(ScrollAxisIntent intent)
+{
+    float resolved;
+    if (!resolveIntent(intent, false, resolved))
+    {
+        m_intentY = intent;
+        return;
+    }
+    m_intentY.space = ScrollSpace::none;
+    scrollOffsetY(resolved);
+}
+
+// Retry held intents; called from constrain() where layout is fresh.
+void ScrollConstraint::resolveScrollIntents()
+{
+    if (m_intentX.space != ScrollSpace::none)
+    {
+        setIntentX(m_intentX);
+    }
+    if (m_intentY.space != ScrollSpace::none)
+    {
+        setIntentY(m_intentY);
+    }
+}
+
+bool ScrollConstraint::positionAtIndex(float index, Vec2D& outPosition)
+{
+    if (std::isnan(index) || (infinite() && !std::isfinite(index)))
+    {
+        outPosition = Vec2D();
+        return true;
     }
     auto count = scrollItemCount();
     if (content() == nullptr || count == 0)
     {
-        return Vec2D();
+        return false;
     }
     Vec2D contentGap = gap();
-    float normalizedIndex = infinite() ? std::fmod(index, (float)count) : index;
+    float normalizedIndex;
+    if (infinite())
+    {
+        normalizedIndex = std::fmod(index, (float)count);
+        if (normalizedIndex < 0)
+        {
+            normalizedIndex += (float)count;
+        }
+    }
+    else
+    {
+        normalizedIndex = std::max(index, 0.0f);
+        // Past the last item: target the far end (clamps to max scroll).
+        if (normalizedIndex >= (float)count)
+        {
+            if (contentWidth() <= 0 && contentHeight() <= 0)
+            {
+                // No measured content — can't resolve.
+                return false;
+            }
+            outPosition = Vec2D(-contentWidth(), -contentHeight());
+            return true;
+        }
+    }
     float floorIndex = std::floor(normalizedIndex);
     float mod = normalizedIndex - floorIndex;
     uint32_t targetIndex = (uint32_t)floorIndex;
-    if (targetIndex >= (uint32_t)count)
-    {
-        return Vec2D();
-    }
 
     // No list children: O(1) direct index into scrollChildren.
     if (!m_hasListChildren)
@@ -544,9 +687,10 @@
         auto bounds = boundsForFlatIndex(targetIndex);
         if (!isBoundsCollapsed(bounds))
         {
-            return Vec2D(-bounds.left() - (bounds.width() + contentGap.x) * mod,
-                         -bounds.top() -
-                             (bounds.height() + contentGap.y) * mod);
+            outPosition =
+                Vec2D(-bounds.left() - (bounds.width() + contentGap.x) * mod,
+                      -bounds.top() - (bounds.height() + contentGap.y) * mod);
+            return true;
         }
         // Target is collapsed — walk forward to next visible item.
         for (uint32_t k = targetIndex + 1; k < (uint32_t)count; k++)
@@ -554,7 +698,8 @@
             auto b = boundsForFlatIndex(k);
             if (!isBoundsCollapsed(b))
             {
-                return Vec2D(-b.left(), -b.top());
+                outPosition = Vec2D(-b.left(), -b.top());
+                return true;
             }
         }
         if (infinite())
@@ -565,7 +710,8 @@
                 auto b = boundsForFlatIndex(k);
                 if (!isBoundsCollapsed(b))
                 {
-                    return Vec2D(-b.left(), -b.top());
+                    outPosition = Vec2D(-b.left(), -b.top());
+                    return true;
                 }
             }
         }
@@ -577,11 +723,13 @@
                 auto b = boundsForFlatIndex(k);
                 if (!isBoundsCollapsed(b))
                 {
-                    return Vec2D(-b.left(), -b.top());
+                    outPosition = Vec2D(-b.left(), -b.top());
+                    return true;
                 }
             }
         }
-        return Vec2D();
+        // Nothing visible — can't resolve.
+        return false;
     }
 
     // Has list children: single-pass through nested child→node structure.
@@ -618,23 +766,25 @@
                 reachedTarget = true;
                 if (!isBoundsCollapsed(bounds))
                 {
-                    return Vec2D(
+                    outPosition = Vec2D(
                         -bounds.left() - (bounds.width() + contentGap.x) * mod,
                         -bounds.top() - (bounds.height() + contentGap.y) * mod);
+                    return true;
                 }
                 continue;
             }
             // Past target: return first visible item found.
             if (!isBoundsCollapsed(bounds))
             {
-                return Vec2D(-bounds.left(), -bounds.top());
+                outPosition = Vec2D(-bounds.left(), -bounds.top());
+                return true;
             }
         }
     }
 
     if (!reachedTarget)
     {
-        return Vec2D();
+        return false;
     }
 
     // No visible item after target.
@@ -653,12 +803,14 @@
             {
                 if (flatIndex >= targetIndex)
                 {
-                    return Vec2D();
+                    // Nothing visible — can't resolve.
+                    return false;
                 }
                 auto bounds = child->layoutBoundsForNode(j);
                 if (!isBoundsCollapsed(bounds))
                 {
-                    return Vec2D(-bounds.left(), -bounds.top());
+                    outPosition = Vec2D(-bounds.left(), -bounds.top());
+                    return true;
                 }
             }
         }
@@ -666,10 +818,12 @@
     else if (hasVisibleBeforeTarget)
     {
         // End of list: fall back to last visible item before target.
-        return lastVisibleBeforeTarget;
+        outPosition = lastVisibleBeforeTarget;
+        return true;
     }
 
-    return Vec2D();
+    // Nothing visible — can't resolve.
+    return false;
 }
 
 float ScrollConstraint::indexAtPosition(Vec2D pos)
@@ -830,6 +984,8 @@
 
 void ScrollConstraint::scrollToPosition(float targetX, float targetY)
 {
+    // Direct offset writes supersede held intents.
+    clearScrollIntents();
     if (m_physics == nullptr)
     {
         // No physics, just set offset directly
diff --git a/tests/unit_tests/assets/scroll_intent.riv b/tests/unit_tests/assets/scroll_intent.riv
new file mode 100644
index 0000000..96e12cf
--- /dev/null
+++ b/tests/unit_tests/assets/scroll_intent.riv
Binary files differ
diff --git a/tests/unit_tests/runtime/layout_scroll_test.cpp b/tests/unit_tests/runtime/layout_scroll_test.cpp
index dd680d1..02f1097 100644
--- a/tests/unit_tests/runtime/layout_scroll_test.cpp
+++ b/tests/unit_tests/runtime/layout_scroll_test.cpp
@@ -6,6 +6,7 @@
 #include "rive/shapes/rectangle.hpp"
 #include "rive/text/text.hpp"
 #include "rive/viewmodel/viewmodel_instance_enum.hpp"
+#include "rive/viewmodel/viewmodel_instance_number.hpp"
 #include "utils/no_op_factory.hpp"
 #include "utils/serializing_factory.hpp"
 #include "rive_file_reader.hpp"
@@ -653,6 +654,112 @@
     rive::File::deterministicMode = false;
 }
 
+TEST_CASE("ScrollConstraint index intent across hidden layout", "[silver]")
+{
+    rive::File::deterministicMode = true;
+
+    rive::SerializingFactory silver;
+    auto file = ReadRiveFile("assets/scroll_intent.riv", &silver);
+
+    auto artboard = file->artboard()->instance();
+    REQUIRE(artboard != nullptr);
+    silver.frameSize(artboard->width(), artboard->height());
+
+    auto vmi = file->createDefaultViewModelInstance(artboard.get());
+    REQUIRE(vmi != nullptr);
+    artboard->bindViewModelInstance(vmi);
+
+    auto smi = artboard->defaultStateMachine();
+    REQUIRE(smi != nullptr);
+
+    auto display =
+        vmi->propertyValue("display")->as<rive::ViewModelInstanceEnum>();
+    auto scrollIndex =
+        vmi->propertyValue("scrollIndex")->as<rive::ViewModelInstanceNumber>();
+
+    auto scrolls = artboard->find<rive::ScrollConstraint>();
+    REQUIRE_FALSE(scrolls.empty());
+    auto scroll = scrolls[0];
+    // LayoutComponent re-declares isCollapsed as protected; read it through
+    // the public Component interface.
+    rive::Component* content = scroll->content();
+    auto offset = [&]() {
+        return scroll->constrainsVertical() ? scroll->scrollOffsetY()
+                                            : scroll->scrollOffsetX();
+    };
+
+    auto renderer = silver.makeRenderer();
+    float dt = 1.0f / 60.0f;
+
+    smi->advanceAndApply(0.0f);
+    artboard->draw(renderer.get());
+
+    for (int frame = 0; frame < 35; frame++)
+    {
+        // Visible: an index set applies immediately.
+        if (frame == 5)
+        {
+            scrollIndex->propertyValue(2.0f);
+        }
+        if (frame == 6)
+        {
+            REQUIRE(offset() < 0);
+        }
+        // Hide the scrolling layout.
+        if (frame == 10)
+        {
+            display->value(1);
+        }
+        if (frame == 11)
+        {
+            REQUIRE(content->isCollapsed());
+        }
+        // Hidden: the set is held and reads back verbatim.
+        if (frame == 15)
+        {
+            scrollIndex->propertyValue(4.0f);
+        }
+        if (frame == 16)
+        {
+            REQUIRE(scroll->scrollIndex() == 4.0f);
+        }
+        // Show again: the held index resolves against fresh layout.
+        if (frame == 20)
+        {
+            display->value(0);
+        }
+        if (frame == 21)
+        {
+            REQUIRE_FALSE(content->isCollapsed());
+            REQUIRE(offset() < 0);
+        }
+        // Visible: out-of-range clamps to the end of the scroll range.
+        if (frame == 25)
+        {
+            scrollIndex->propertyValue(100.0f);
+        }
+        if (frame == 26)
+        {
+            REQUIRE(offset() == (scroll->constrainsVertical()
+                                     ? scroll->maxOffsetY()
+                                     : scroll->maxOffsetX()));
+        }
+        // Back to the start.
+        if (frame == 30)
+        {
+            scrollIndex->propertyValue(0.0f);
+        }
+        silver.addFrame();
+        smi->advanceAndApply(dt);
+        artboard->draw(renderer.get());
+    }
+    REQUIRE(offset() == 0);
+
+    CHECK(silver.matches("scroll_intent"));
+
+    rive::File::deterministicMode = false;
+}
+
 // =========================================================================
 // Velocity-tracking tests for ScrollConstraint.
 //
@@ -936,4 +1043,62 @@
     CHECK_FALSE(scroll->physics()->isRunning());
 
     rive::File::deterministicMode = false;
+}
+
+TEST_CASE("ScrollConstraint index set before layout resolves on advance",
+          "[layoutscroll]")
+{
+    auto file = ReadRiveFile("assets/layout/layout_scroll_vertical.riv");
+
+    auto artboard = file->artboard();
+    auto scroll = artboard->find<rive::ScrollConstraint>()[0];
+
+    // Layout hasn't run; the index is held and reads back verbatim.
+    scroll->setScrollIndex(2);
+    REQUIRE(scroll->scrollIndex() == 2);
+    REQUIRE(scroll->offsetY() == 0);
+
+    // First advance runs layout; the intent resolves.
+    artboard->advance(0.0f);
+    REQUIRE(scroll->offsetY() == -220.0f);
+    REQUIRE(scroll->scrollIndex() == 2);
+}
+
+TEST_CASE("ScrollConstraint percent set before layout resolves on advance",
+          "[layoutscroll]")
+{
+    auto file = ReadRiveFile("assets/layout/layout_scroll_vertical.riv");
+
+    auto artboard = file->artboard();
+    auto scroll = artboard->find<rive::ScrollConstraint>()[0];
+
+    // Layout hasn't run; the percent is held and reads back verbatim.
+    scroll->setScrollPercentY(0.5f);
+    REQUIRE(scroll->scrollPercentY() == 0.5f);
+    REQUIRE(scroll->offsetY() == 0);
+
+    // First advance runs layout; the intent resolves.
+    artboard->advance(0.0f);
+    REQUIRE(scroll->offsetY() == -305.0f);
+    REQUIRE(scroll->scrollPercentY() == 0.5f);
+}
+
+TEST_CASE("ScrollConstraint out-of-range index clamps to the ends",
+          "[layoutscroll]")
+{
+    auto file = ReadRiveFile("assets/layout/layout_scroll_vertical.riv");
+
+    auto artboard = file->artboard();
+    auto scroll = artboard->find<rive::ScrollConstraint>()[0];
+    artboard->advance(0.0f);
+
+    // Past the end: clamps to max scroll; readback reports the actual index.
+    scroll->setScrollIndex(99);
+    REQUIRE(scroll->offsetY() == -610.0f);
+    REQUIRE(scroll->scrollIndex() == Approx(5.54545f));
+
+    // Before the start: clamps to zero.
+    scroll->setScrollIndex(-5);
+    REQUIRE(scroll->offsetY() == 0.0f);
+    REQUIRE(scroll->scrollIndex() == 0);
 }
\ No newline at end of file
diff --git a/tests/unit_tests/silvers/component_list_child_origin.sriv b/tests/unit_tests/silvers/component_list_child_origin.sriv
index 0f344ea..1f09995 100644
--- a/tests/unit_tests/silvers/component_list_child_origin.sriv
+++ b/tests/unit_tests/silvers/component_list_child_origin.sriv
Binary files differ
diff --git a/tests/unit_tests/silvers/scroll_intent.sriv b/tests/unit_tests/silvers/scroll_intent.sriv
new file mode 100644
index 0000000..3e8a652
--- /dev/null
+++ b/tests/unit_tests/silvers/scroll_intent.sriv
Binary files differ