Skip to content

Commit 85127f0

Browse files
committed
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.
1 parent 503ef6f commit 85127f0

3 files changed

Lines changed: 21 additions & 12 deletions

File tree

‎src/commands/interaction/runtime/resolution.test.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,10 @@ test('runtime press names a direction for a partial clip whose center is off-scr
168168
assert.equal(details?.reason, 'offscreen_selector');
169169
assert.equal(details?.scrollDirection, 'down');
170170
assert.match(String(details?.hint), /scroll down/i);
171+
// #1366 recovery must be bounded: a single large (fling) scroll overshoots,
172+
// so the hint steers to small steps / a bounded gesture pan.
173+
assert.match(String(details?.hint), /small steps/i);
174+
assert.match(String(details?.hint), /gesture pan/i);
171175
return true;
172176
},
173177
);

‎src/commands/interaction/runtime/resolution.ts‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -700,11 +700,13 @@ function assertVisibleSelectorTarget(
700700
message: `Selector ${selector} resolved to an off-screen element and is not safe to ${action}`,
701701
details: { reason: 'offscreen_selector', selector },
702702
// A selector re-resolves against a fresh snapshot on every attempt, so the
703-
// recovery is just: scroll the named direction, then retry THIS selector —
704-
// no 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.
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.
706708
hint: (direction) =>
707-
`${scrollRevealClause(direction)}, then retry ${action} with the same selector — a selector re-resolves against a fresh snapshot, so no separate snapshot is needed. If it is inside a closed drawer or another tab, open that container first.`,
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.`,
708710
});
709711
}
710712

@@ -721,17 +723,17 @@ function assertVisibleRefTarget(
721723
// 0014), so retrying this @ref would be rejected next. Steer to a selector,
722724
// which re-resolves against a fresh snapshot and bypasses the ref-frame guard.
723725
hint: (direction) =>
724-
`${scrollRevealClause(direction)}, 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.`,
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.`,
725727
});
726728
}
727729

728730
// Shared lead-in for both off-screen hints. Names the concrete `scroll <dir>`
729-
// when the geometry gives one, and falls back to the container-aware phrasing
730-
// when the target is off more than one edge in a way that has no single reveal.
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.
731735
function scrollRevealClause(direction: OffscreenScrollDirection | null): string {
732-
return direction
733-
? `Scroll ${direction} to bring it on-screen`
734-
: 'Scroll toward it (open its container if it is in a closed drawer or another tab)';
736+
return direction ? `Scroll ${direction} toward it` : 'Scroll toward it';
735737
}
736738

737739
/**

‎src/daemon/handlers/__tests__/interaction.test.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2593,10 +2593,13 @@ test('press @ref fails fast when the target is off-screen', async () => {
25932593
if (response && !response.ok) {
25942594
expect(response.error.code).toBe('COMMAND_FAILED');
25952595
expect(response.error.message).toMatch(/off-screen/i);
2596-
// #1366: the hint names the concrete scroll direction and steers to a
2597-
// selector-based retry (a @ref would be rejected as expired after the scroll).
2596+
// #1366: the hint names the concrete scroll direction, steers to a
2597+
// selector-based retry (a @ref would be rejected as expired after the scroll),
2598+
// and prescribes bounded movement (a large fling scroll overshoots).
25982599
expect(response.error.hint).toMatch(/scroll down/i);
25992600
expect(response.error.hint).toMatch(/selector/i);
2601+
expect(response.error.hint).toMatch(/small steps/i);
2602+
expect(response.error.hint).toMatch(/gesture pan/i);
26002603
expect(response.error.details?.reason).toBe('offscreen_ref');
26012604
expect(response.error.details?.scrollDirection).toBe('down');
26022605
}

0 commit comments

Comments
 (0)