You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit a0ab735
Browse filesBrowse the repository at this point in the historyBrowse files
* fix(interaction): direction-named, selector-first off-screen recovery hints (#1366)
An agent that hits a scrollable form section gets correctly rejected for
targeting an off-screen element, but the recovery hint didn't name a
concrete next move. Its "obvious" retry — re-issue the same @ref after
scrolling — is exactly what both live guards reject: the off-screen guard
still sees it off-screen, and the scroll expired the ref frame (ADR 0014),
so the @ref is refused as stale. Two bootstrap-bench runs burned all 60
turns on a single checkout-form screen this way (arm-independent).
Make the rejection self-sufficient for recovery instead of relaxing either
guard:
- Off-screen selector/ref rejection now names the exact scroll direction
(computed from the target rect vs its effective viewport) and steers the
retry to a *selector*, which re-resolves against a fresh snapshot and
bypasses the ref-frame admission guard entirely. The direction is also
surfaced as a machine-readable `scrollDirection` detail.
- `scroll`'s unknown-direction error now carries a grammar hint, since the
transcripts show agents mis-shaping it as `scroll @ref down` — scroll
takes a direction and no target.
New geometry helper `classifyOffscreenScrollDirection` maps a rect +
viewport to the reveal direction (largest-overshoot axis), following the
same convention the CLI off-screen summary already uses.
Both guards keep their exact rejection semantics and messages; only the
hints and one added detail field change.
* fix(interaction): derive scroll direction from the boundary that rejected (#1366 review)
Address P1: the direction classifier used a rect-vs-single-viewport test, so it
only fired when the whole rect was fully past an effective-viewport edge. But
`isNodeVisibleOnScreen` rejects on two boundaries — and the second one (tap-point
CENTER outside the ROOT viewport while the rect still overlaps its container) is
exactly the off-screen-drawer / edge-straddling case #1366 is about. Those got
the generic hint and no scrollDirection, leaving the loop unresolved.
`classifyOffscreenScrollDirection` now takes (node, nodes) and mirrors both
rejection boundaries: full separation from the effective viewport, then a
center pushed outside the root viewport. Direction is taken from whichever
boundary failed, using the same unrounded center as the tap-point rule, so a
rejected target always yields a direction.
Regressions: partial clip whose center is past the viewport edge (both the pure
classifier and the live selector-press rejection path), and a child inside an
off-screen scrollable ancestor (closed drawer).
* style: oxfmt the windowRoot test helper (#1366 CI)
* fix(interaction): bounded off-screen recovery hint — a large scroll overshoots (#1366 review)
Live evidence exposed that the hint over-promised: it advertised `scroll
<direction>` -> retry-selector as the terminating recovery, but on the
motivating checkout form a plain `scroll` (iOS fling momentum) repeatedly
overshoots the narrow pressable band and the loop never terminates — even
bounded `scroll --pixels 200` oscillates up/down. A momentum-free `gesture pan`
in small steps lands the target (verified: 3–4 attempts -> Tapped "Cash").
Revise the hint to prescribe BOUNDED movement in the named direction, retrying
the same selector after each step, and to name the overshoot failure mode and
the reliable `gesture pan` fallback. Direction + selector-first steering are
unchanged. `scrollRevealClause` drops the "to bring it on-screen" over-promise.
Tests assert the bounded-recovery guidance (small steps / gesture pan) on both a
selector and a ref off-screen path so it can't silently regress.
hint: 'scroll takes a direction first, then an optional amount: scroll <up|down|left|right|top|bottom> [amount]. It takes no @ref or selector — scroll the whole viewport, then retry the target with a selector.',
hint: `The element is outside the visible viewport — likely inside a closed drawer, another tab, or scrolled content. Scroll toward it or open its container, take a fresh snapshot, then retry ${action}.`,
702
+
// A selector re-resolves against a fresh snapshot on every attempt, so the
703
+
// recovery is: move the named direction, then retry THIS selector — no
704
+
// separate snapshot step, and no @ref (a scroll expires the ref frame,
705
+
// #1366). Naming the direction stops the wrong-way / retry-the-same-ref loop;
706
+
// bounded steps stop the overshoot loop — a single large scroll (fling
707
+
// momentum on iOS) can sail past the target, so a short gesture pan lands it.
708
+
hint: (direction)=>
709
+
`${scrollRevealClause(direction)} in small steps, retrying ${action} with the same selector after each (it re-resolves against a fresh snapshot). A single large scroll can overshoot the target; a short bounded gesture pan lands it more reliably. If it is inside a closed drawer or another tab, open that container first.`,
701
710
});
702
711
}
703
712
@@ -710,10 +719,23 @@ function assertVisibleRefTarget(
710
719
throwIfOffscreenInteractionTarget(node,nodes,{
711
720
message: `Ref ${refInput} is off-screen and not safe to ${action}`,
hint: `Use scroll with the direction from the off-screen summary, take a fresh snapshot, then retry ${action} with the new ref or a selector.`,
722
+
// The scroll that reveals the target expires the ref frame (#1366, ADR
723
+
// 0014), so retrying this @ref would be rejected next. Steer to a selector,
724
+
// which re-resolves against a fresh snapshot and bypasses the ref-frame guard.
725
+
hint: (direction)=>
726
+
`${scrollRevealClause(direction)} in small steps (a single large scroll can overshoot; a short bounded gesture pan lands it more reliably), then retry ${action} with a selector (e.g. text=/id=) rather than this @ref — the scroll expires the ref frame, so re-run snapshot -i before reusing any @ref.`,
714
727
});
715
728
}
716
729
730
+
// Shared lead-in for both off-screen hints. Names the concrete `scroll <dir>`
731
+
// when the geometry gives one, and falls back to the generic phrasing when the
732
+
// target is off more than one edge in a way that has no single reveal. Callers
733
+
// append the bounded-steps guidance: a single large scroll (fling momentum on
734
+
// iOS) can sail past the target, so small bounded moves are what actually land.
0 commit comments