📝 add mode-switching via Clay_GetScrollContainerData to scroll spec

Author: cowboyd

specs/scroll-spec.md

@@ -156,14 +156,24 @@ When decoding a clip configuration, the C side:
 1. Reads axis modes from the packed word.
 2. Sets `decl.clip.horizontal` / `decl.clip.vertical` to true for any non-zero
    mode.
-3. For manual axes, reads the offset from the buffer.
+3. For manual axes, reads the offset from the buffer and writes it into Clay's
+   internal scroll state via `Clay_GetScrollContainerData`. This keeps Clay's
+   scroll position in sync so that switching to pointer mode on a subsequent
+   frame continues from the manual position.
 4. For pointer axes, reads the offset from `Clay_GetScrollOffset()`.
 5. Combines both into `decl.clip.childOffset`.
 
 This happens while the element is open (between `Clay__OpenElementWithId` and
 `Clay__ConfigureOpenElement`), so `Clay_GetScrollOffset()` resolves to the
 correct element.
 
+### 7.1 Mode switching
+
+Because manual mode writes to Clay's scroll state every frame, and pointer mode
+reads from it, the two modes are always in sync. The caller can freely alternate
+between numeric and `"pointer"` values on any axis between frames without
+jumps or discontinuities. No explicit mode-switching logic is needed.
+
 ---
 
 ## 8. Invariants
@@ -216,13 +226,19 @@ bounding box contains the event's coordinates.
 12. Manual axis is unaffected by wheel events.
 13. Pointer axis ignores manual values (uses engine state).
 
+### Mode switching
+
+14. Switch from manual to pointer — pointer continues from manual position.
+15. Switch from pointer to manual — manual overrides pointer position.
+16. Rapid alternation between modes — no jumps or discontinuities.
+
 ### Edge cases
 
-14. Clip with no children — no crash, empty output.
-15. Nested scroll containers — inner container gets priority for wheel.
-16. Scroll container removed between frames — no stale state.
-17. Wheel event with no scroll containers under pointer — no effect.
-18. Wheel event with only manual-mode containers under pointer — no effect.
+17. Clip with no children — no crash, empty output.
+18. Nested scroll containers — inner container gets priority for wheel.
+19. Scroll container removed between frames — no stale state.
+20. Wheel event with no scroll containers under pointer — no effect.
+21. Wheel event with only manual-mode containers under pointer — no effect.
 
 ---