@@ -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