[v4]: update `/scroll` route stub

Merged
SE
8mo ago
+185-40

why

  • the existing /page/scroll endpoint had an awkward union of PageScrollElementParams (element selector + percentage) and PageScrollCoordinateParams (coordinate selector + deltaX/deltaY).
  • these two modes were hard to distinguish and didn't cover common scrolling patterns like "scroll N pages" or "scroll until this element is visible"

what changed

  • replaced the two old scroll param schemas with a cleaner 3-way discriminated union:
    • PageScrollByOffsetParams: scroll by pixel delta ({ cursorPosition?, offset: {x, y} })
    • PageScrollByPagesParams: scroll by viewport heights ({ cursorPosition?, pages: number, delayBetweenMs? })
    • PageScrollToTargetParams: scroll until a target is visible ({ target: Selector })
  • cursorPosition is an optional Selector that determines where the mouse cursor is placed before scrolling. this controls which scrollable container receives the event.

test plan

  • updated the route stub and integration test to match the new schema

Summary by cubic

Refactors the v4 /page/scroll route into a simple 3‑mode API and updates OpenAPI to return a typed PageScrollActionOutput. The stub now returns {x: 0, y: 0}; adds position for target scrolls and delayBetweenMs for page scrolling, aligning with Linear STG-1644.

  • Refactors

    • Replaced old params with 3 modes: by offset {offset:{x,y}}, by pages {pages, delayBetweenMs?}, or to target {target, position?}; optional {cursorPosition} selects the scroll container.
    • OpenAPI now uses PageScrollActionOutput and PageScroll*ParamsOutput (defaults resolved, stricter requireds) and wires it into the PageAction union.
    • Route stub execution simplified to always return {x: 0, y: 0}.
  • Migration

    • Stop using selector + percentage and selector + deltaX/deltaY.
    • Send one of: {offset:{x,y}}, {pages, delayBetweenMs?, cursorPosition?}, or {target, position?}.
    • Expect {x,y} in the result; the action shape is now PageScrollActionOutput.