Skip to content

Commit bce6f52

Browse files
authored
fix(scroll): an overscroll bounce at the edge is not movement (#2984)
* fix(scroll): an overscroll bounce at the edge is not movement At the end of a list iOS rubber-bands past the edge, so the first post-gesture capture lands mid-bounce with every row shifted and read as moved, then the content sprang back to the pre-gesture tree. A change against a baseline that already ended in the scrolled direction is now credited only once the surface holds still and still differs; a bounce that settles back answers at-edge. Closes #2884. * fix(scroll): ask the edge question of the scroller under the swipe The rest requirement resolved the edge state without the swipe point, so a nested screen could answer for a scroller the gesture never ran in. The baseline check now passes the swipe midpoint through readScrollEdgeState, the same selection the edge verdict uses, and the poll loop doc names the edge exception. * docs(scroll): describe the container the edge gate resolves to
1 parent 1ea91d2 commit bce6f52

3 files changed

Lines changed: 171 additions & 12 deletions

File tree

‎packages/capture-kit/src/snapshot/scroll-edge-state.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,9 +81,10 @@ export async function captureScrollEdgeState(params: {
8181
export async function readScrollEdgeState(
8282
nodes: readonly (RawSnapshotNode | SnapshotNode)[],
8383
edge: ScrollEdge,
84+
target: ScrollEdgeTarget = {},
8485
): Promise<ScrollEdgeState> {
8586
const { analyzeScrollEdgeState } = await import('./scroll-edge-state/selection.ts');
86-
return analyzeScrollEdgeState(nodes, edge);
87+
return analyzeScrollEdgeState(nodes, edge, target);
8788
}
8889

8990
/**

‎src/daemon/__tests__/scroll-movement.test.ts‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -177,6 +177,94 @@ test('a surface that no longer holds the pre-gesture content answers moved on th
177177
assert.equal(spy.calls(), 1);
178178
});
179179

180+
/**
181+
* At the end of a list iOS rubber-bands past the edge: the first capture lands mid-bounce with every row
182+
* shifted, then the content springs back to exactly the pre-gesture tree (#2884). A baseline that already
183+
* showed the end of the content turns that first read into a question, not a verdict.
184+
*/
185+
test('a bounce past the edge that springs back is at-edge, not moved', async () => {
186+
const { observation, spy } = observe({
187+
baseline: baselineOf(screen(0, false)),
188+
screens: [screen(-14, false), screen(0, false), screen(0, false)],
189+
});
190+
191+
assert.equal(await observation, 'at-edge');
192+
assert.equal(spy.calls(), 3);
193+
});
194+
195+
/**
196+
* The edge question is asked of the scroller under the swipe, through the same selection the edge
197+
* verdict uses: among the containers holding the point, the one that still hides content in that
198+
* direction. An inner list at its end inside an outer list with more below hands the swipe to the
199+
* outer list (that is what the platform does with the gesture), so the rest requirement does not
200+
* engage and the first differing read is the movement it produced.
201+
*/
202+
test('an inner list at its end inside an outer list with hidden content hands the swipe on', async () => {
203+
const outer = {
204+
type: 'ScrollView',
205+
identifier: 'outer',
206+
rect: { x: 0, y: 100, width: 402, height: 760 },
207+
hiddenContentBelow: true,
208+
} as SnapshotNode;
209+
const inner = (rowOffset: number) => [
210+
outer,
211+
...screen(rowOffset, false).map((node) =>
212+
node.type === 'ScrollView' ? ({ ...node, identifier: 'inner' } as SnapshotNode) : node,
213+
),
214+
];
215+
const { observation, spy } = observe({
216+
baseline: baselineOf(inner(0)),
217+
screens: [inner(-300)],
218+
});
219+
220+
assert.equal(await observation, 'moved');
221+
assert.equal(spy.calls(), 1);
222+
});
223+
224+
/** With no outer list left to take it, the swipe point resolves the inner list and its edge gates the claim. */
225+
test('an inner list at its end with no outer list left to scroll is gated on rest', async () => {
226+
const outerAtEnd = {
227+
type: 'ScrollView',
228+
identifier: 'outer',
229+
rect: { x: 0, y: 100, width: 402, height: 760 },
230+
} as SnapshotNode;
231+
const inner = (rowOffset: number) => [
232+
outerAtEnd,
233+
...screen(rowOffset, false).map((node) =>
234+
node.type === 'ScrollView' ? ({ ...node, identifier: 'inner' } as SnapshotNode) : node,
235+
),
236+
];
237+
const { observation, spy } = observe({
238+
baseline: baselineOf(inner(0)),
239+
screens: [inner(-14), inner(0), inner(0)],
240+
});
241+
242+
assert.equal(await observation, 'at-edge');
243+
assert.equal(spy.calls(), 3);
244+
});
245+
246+
test('content that changes at the edge and holds still is still moved', async () => {
247+
const { observation, spy } = observe({
248+
baseline: baselineOf(screen(0, false)),
249+
screens: [screen(-300, false), screen(-300, false)],
250+
});
251+
252+
assert.equal(await observation, 'moved');
253+
// The rest requirement costs exactly the one extra read, and only at the edge.
254+
assert.equal(spy.calls(), 2);
255+
});
256+
257+
test('a bounce that never settles at the edge spends the budget and answers unobserved', async () => {
258+
const { observation } = observe({
259+
baseline: baselineOf(screen(0, false)),
260+
screens: (attempt) => screen(attempt % 2 === 0 ? -14 : 0, false),
261+
budgetMs: 40,
262+
});
263+
264+
assert.equal(await observation, 'unobserved');
265+
assertWithheld('surface-unsettled');
266+
});
267+
180268
test('a surface that never shifted while the container still hides content refuses with a typed reason', async () => {
181269
const { observation, spy } = observe({
182270
baseline: baselineOf(screen(0)),

‎src/daemon/scroll-movement.ts‎

Lines changed: 81 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,8 @@ import type { SessionState } from './session-state.ts';
5151
* baseline is answered on the first capture, so a scroll that worked pays nothing extra; only a
5252
* surface that looks untouched keeps polling (a mid-flight or stale read is indistinguishable from a
5353
* no-op until it either moves or goes quiet), and only an untouched surface at rest is ever reported.
54+
* The one exception is a baseline that already ended in the scrolled direction: there a differing
55+
* first read is an overscroll bounce until it holds still (`baselineEndsInDirection`).
5456
*
5557
* Nothing is classified before the two trees are established to be two views of one screen, and that
5658
* gate runs on every capture rather than only on the quiet path. The deferred loop can adopt a new
@@ -68,6 +70,8 @@ export type ScrollSurfaceBaseline = Readonly<{
6870
signature: InteractionSurfaceSignature;
6971
presentationKey: string | undefined;
7072
comparisonKey: string | undefined;
73+
/** The tree itself: whether the content already ended in the scrolled direction is asked of nodes. */
74+
nodes: SnapshotState['nodes'];
7175
}>;
7276

7377
/** Why there is nothing honest to compare this scroll's effect against. */
@@ -134,6 +138,7 @@ export function readScrollSurfaceBaseline(
134138
signature,
135139
presentationKey: snapshot.presentationKey,
136140
comparisonKey: snapshotSurfaceComparisonKey(snapshot),
141+
nodes: snapshot.nodes,
137142
};
138143
}
139144

@@ -234,7 +239,9 @@ function surfacePairDrift(
234239

235240
/**
236241
* Polls until an untouched surface proves itself. A surface that differs from the baseline is a
237-
* verdict on the first capture, so a scroll that worked pays for one read. One that looks untouched
242+
* verdict on the first capture, so a scroll that worked pays for one read, unless the baseline
243+
* already ended in the scrolled direction, where the change must hold still first
244+
* (`baselineEndsInDirection`). One that looks untouched
238245
* needs a quiet pair, because a gesture still in flight and a gesture that did nothing answer a
239246
* single read identically. A surface that never holds still expires as `surface-unsettled` rather
240247
* than being called a no-op — and that answer is worth a warning the others are not, since it spent
@@ -254,28 +261,91 @@ async function pollForSurfaceVerdict(
254261
const deadline = startedAt + (params.budgetMs ?? MOVEMENT_VERDICT_BUDGET_MS);
255262
let previous: InteractionSurfaceSignature | undefined;
256263
let attempts = 0;
264+
let changeNeedsRest: boolean | undefined;
257265

258266
while (true) {
259267
const reading = await readOneCapture(baseline, params.capture);
260268
attempts += 1;
261269
if (reading.kind === 'blind') return { kind: 'blind', reason: reading.reason };
262-
if (reading.kind === 'changed')
263-
return { kind: 'moved', observed: reading.observed, attempts, startedAt };
264-
if (surfaceIsAtRest(previous, reading.observed.signature)) {
265-
return {
266-
kind: 'settled',
267-
observed: reading.observed,
268-
evidence: reading.evidence,
269-
attempts,
270-
startedAt,
271-
};
270+
if (reading.kind === 'changed') {
271+
changeNeedsRest ??= await baselineEndsInDirection(baseline, params.direction, params.swipe);
272272
}
273+
const verdict = settledVerdict(reading, {
274+
previous,
275+
changeNeedsRest: changeNeedsRest === true,
276+
attempts,
277+
startedAt,
278+
});
279+
if (verdict) return verdict;
273280
if (Date.now() >= deadline) return budgetExpiredVerdict(params, attempts, startedAt);
274281
previous = reading.observed.signature;
275282
await sleep(params.pollMs ?? MOVEMENT_POLL_MS);
276283
}
277284
}
278285

286+
/**
287+
* The verdict one readable capture supports, or nothing yet. A changed surface is movement on sight
288+
* unless the baseline already ended in that direction, where it must hold still first; an unchanged
289+
* surface is settled only as the second of a quiet pair.
290+
*/
291+
function settledVerdict(
292+
reading: Exclude<CaptureReading, { kind: 'blind' }>,
293+
poll: {
294+
previous: InteractionSurfaceSignature | undefined;
295+
changeNeedsRest: boolean;
296+
attempts: number;
297+
startedAt: number;
298+
},
299+
): SurfaceVerdict | undefined {
300+
const atRest = surfaceIsAtRest(poll.previous, reading.observed.signature);
301+
const { attempts, startedAt } = poll;
302+
if (reading.kind === 'changed') {
303+
if (!poll.changeNeedsRest || atRest) {
304+
return { kind: 'moved', observed: reading.observed, attempts, startedAt };
305+
}
306+
return undefined;
307+
}
308+
if (!atRest) return undefined;
309+
return {
310+
kind: 'settled',
311+
observed: reading.observed,
312+
evidence: reading.evidence,
313+
attempts,
314+
startedAt,
315+
};
316+
}
317+
318+
/**
319+
* Whether the pre-gesture tree already showed the end of the content in the scrolled direction. A
320+
* scroll past that edge on iOS rubber-bands: the first capture lands mid-bounce with every row shifted
321+
* by a few points and reads as `changed`, then the content springs back to exactly the baseline, which
322+
* is what the next command's stabilization later observes as a stale-accept (#2884). So a change against
323+
* a baseline that had nothing left to reveal is credited only once the surface holds still and still
324+
* differs; a scroll whose baseline still hid content keeps paying one read.
325+
*/
326+
async function baselineEndsInDirection(
327+
baseline: ScrollSurfaceBaseline,
328+
direction: ScrollDirection,
329+
swipe: ScrollSwipeEvidence,
330+
): Promise<boolean> {
331+
const edge = verticalEdgeFor(direction);
332+
if (!edge) return false;
333+
// The question is asked of the scroller the swipe ran in, through the selection the edge verdict
334+
// uses: among the containers holding the point, the one that still hides content in that
335+
// direction. An inner list at its end inside an outer list with more below hands the gesture to
336+
// the outer list, so the outer list's edge is what gates the claim.
337+
const state = await readScrollEdgeState(baseline.nodes, edge, { point: swipe.midpoint });
338+
const ends = state.containerRect !== undefined && !state.canScroll;
339+
if (ends) {
340+
emitDiagnostic({
341+
level: 'debug',
342+
phase: 'scroll_movement_edge_rest_required',
343+
data: { direction, containerRect: state.containerRect },
344+
});
345+
}
346+
return ends;
347+
}
348+
279349
/**
280350
* What a single capture says, on its own: nothing at all when the tree could not be read or comes from
281351
* another lineage, movement when the surface differs from the baseline, and otherwise the untouched

0 commit comments

Comments
 (0)