Skip to content

Commit 93de350

Browse files
committed
fix(scroll): pace edge passes to rest and stop a stuck surface
A rubber-band bounce keeps shifting the surface after a fling, so the next edge pass captured a phantom new offset, stacked another fling on top of the bounce, and a single stuck container could fling 40 times without net progress. `runScrollEdgePasses` now waits for the scoped scroll surface to hold between passes before deciding or flinging again, and stops with `scroll_edge_no_progress` when a container still reports hidden content but its descendants never shift. The end pass-limit keeps its own `scroll_edge_pass_limit` reason. `scroll --until` shares the same stuck-signature window and raises `scroll_until_no_progress`. The stuck-window bookkeeping and surface fingerprint are shared from capture-kit so both loops read one definition of "stuck" rather than a copy.
1 parent 38cfa87 commit 93de350

7 files changed

Lines changed: 389 additions & 44 deletions

File tree

‎packages/capture-kit/src/snapshot/__tests__/scroll-edge-state-pass-orchestration.test.ts‎

Lines changed: 52 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -284,6 +284,8 @@ test('runScrollEdgePasses: throws a COMMAND_FAILED AppError once the pass limit
284284
await assert.rejects(
285285
runScrollEdgePasses({
286286
edge: 'bottom',
287+
// No fingerprint on these manual captures, so no-progress detection is inert and only the
288+
// 40-pass backstop can end the loop. The real capture path always sets a fingerprint.
287289
captureState: async () => ({
288290
canScroll: true,
289291
emptySnapshot: false,
@@ -300,15 +302,62 @@ test('runScrollEdgePasses: throws a COMMAND_FAILED AppError once the pass limit
300302
error.message,
301303
'scroll bottom reached the safety limit before the snapshot showed the edge',
302304
);
303-
assert.deepEqual(error.details, {
304-
hint: 'The scoped scroll container still reports hidden content. Run scroll <dir> --until <selector> to stop on the element you are after, or snapshot -i to inspect the current state.',
305-
});
305+
assert.equal(error.details?.reason, 'scroll_edge_pass_limit');
306+
assert.equal(error.details?.passes, 40);
307+
assert.match(String(error.details?.hint), /--until <selector>/);
306308
return true;
307309
},
308310
);
309311
assert.equal(scrollCalls, 40);
310312
});
311313

314+
test('runScrollEdgePasses: stops as no-progress after a couple of passes when the fingerprint never moves', async () => {
315+
let scrollCalls = 0;
316+
await assert.rejects(
317+
runScrollEdgePasses({
318+
edge: 'bottom',
319+
// canScroll stays true but the surface fingerprint is byte-identical every capture — the
320+
// stuck-container signature (the gesture is not reaching this scroll view).
321+
captureState: async () => ({
322+
canScroll: true,
323+
emptySnapshot: false,
324+
fingerprint: 'stuck-surface',
325+
}),
326+
scroll: async () => {
327+
scrollCalls += 1;
328+
return undefined;
329+
},
330+
}),
331+
(error: unknown) => {
332+
assert.ok(error instanceof AppError);
333+
assert.equal(error.code, 'COMMAND_FAILED');
334+
assert.equal(error.details?.reason, 'scroll_edge_no_progress');
335+
assert.equal(error.details?.edge, 'bottom');
336+
assert.match(String(error.details?.hint), /not reaching this container/);
337+
return true;
338+
},
339+
);
340+
// The whole point: a stuck container stops within a few flings, not 40.
341+
assert.equal(scrollCalls, 3);
342+
});
343+
344+
test('runScrollEdgePasses: a moving fingerprint never trips no-progress and scrolls to the edge', async () => {
345+
let scrollCalls = 0;
346+
const result = await runScrollEdgePasses({
347+
edge: 'bottom',
348+
captureState: async () => ({
349+
canScroll: scrollCalls < 5,
350+
emptySnapshot: false,
351+
fingerprint: `surface-${scrollCalls}`,
352+
}),
353+
scroll: async () => {
354+
scrollCalls += 1;
355+
return undefined;
356+
},
357+
});
358+
assert.equal(result.passes, 5);
359+
});
360+
312361
test('unique container scope is retained across edge pass captures', async () => {
313362
const scopes: Array<string | undefined> = [];
314363
const snapshots = [scrollSnapshot(true), scrollSnapshot(true), scrollSnapshot(false)];

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

Lines changed: 94 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,13 @@ export type ScrollEdgeState = {
88
canScroll: boolean;
99
emptySnapshot: boolean;
1010
scope?: string;
11+
/**
12+
* A cheap signature of what is on screen right now. Two consecutive captures with the same
13+
* fingerprint but `canScroll` still true mean the scroll did not move the container — the actuator
14+
* and the detector disagree, which is the stuck-container signature `runScrollEdgePasses` stops on.
15+
* Optional so manual capture fixtures can opt out of no-progress detection.
16+
*/
17+
fingerprint?: string;
1118
};
1219

1320
export type ScrollEdgeTarget = {
@@ -17,6 +24,17 @@ export type ScrollEdgeTarget = {
1724

1825
const SCROLL_EDGE_PASS_LIMIT = 40;
1926

27+
/**
28+
* A stuck or rubber-banding surface revisits the same one or two on-screen signatures, while a real
29+
* scroll keeps producing a new signature every pass. Once a short window has held at most two
30+
* distinct signatures for enough passes, the gesture is not reaching the container and further
31+
* flings only bounce — stop long before the 40-pass backstop. Rounded-pixel signatures make a real
32+
* pass always look new, so this never cuts a scroll that actually moved.
33+
*/
34+
const SCROLL_EDGE_STUCK_WINDOW = 6;
35+
const SCROLL_EDGE_STUCK_MIN_LENGTH = 4;
36+
const SCROLL_EDGE_STUCK_MAX_DISTINCT = 2;
37+
2038
export async function captureScrollEdgeState(params: {
2139
edge: ScrollEdge;
2240
target?: ScrollEdgeTarget;
@@ -49,33 +67,92 @@ export async function canScrollFurtherAtEdge(
4967
return analyzeScrollEdgeState(nodes, edge).canScroll;
5068
}
5169

70+
/**
71+
* The on-screen signature the `--until` loop tracks to notice a stuck container, computed the same
72+
* way `captureScrollEdgeState` derives it, so both loops read one signal. Pure: no capture happens.
73+
*/
74+
export async function scrollSurfaceFingerprint(
75+
nodes: readonly (RawSnapshotNode | SnapshotNode)[],
76+
edge: ScrollEdge,
77+
): Promise<string> {
78+
const { analyzeScrollEdgeState } = await import('./scroll-edge-state/selection.ts');
79+
return analyzeScrollEdgeState(nodes, edge).fingerprint ?? '';
80+
}
81+
82+
/**
83+
* Has a scroll stopped making progress? True once `recentSignatures` holds at least
84+
* `SCROLL_EDGE_STUCK_MIN_LENGTH` captures within the last `SCROLL_EDGE_STUCK_WINDOW` and no more
85+
* than two of them are distinct — the signature of a container that ignores the gesture or is only
86+
* rubber-banding. Callers cap `recentSignatures` to the window. Exported so `scroll --until` reuses
87+
* the one definition of "stuck" rather than a second copy.
88+
*/
89+
export function scrollSurfaceIsStuck(recentSignatures: readonly string[]): boolean {
90+
if (recentSignatures.length < SCROLL_EDGE_STUCK_MIN_LENGTH) return false;
91+
const window = recentSignatures.slice(-SCROLL_EDGE_STUCK_WINDOW);
92+
return new Set(window).size <= SCROLL_EDGE_STUCK_MAX_DISTINCT;
93+
}
94+
95+
/**
96+
* Records one pass's surface signature, capped to the trailing window the stuck detector reads. An
97+
* empty signature is skipped so a container with no positioned descendants stays on its edge/pass
98+
* signals instead of stacking blanks. Both scroll loops push through here so "one window" has one
99+
* definition rather than a copy that can drift.
100+
*/
101+
export function pushScrollSurfaceSignature(
102+
recentSignatures: string[],
103+
fingerprint: string | undefined,
104+
window: number,
105+
): void {
106+
if (!fingerprint) return;
107+
recentSignatures.push(fingerprint);
108+
if (recentSignatures.length > window) recentSignatures.shift();
109+
}
110+
52111
export async function runScrollEdgePasses<TResult>(params: {
53112
edge: ScrollEdge;
54113
captureState: (scope?: string) => Promise<ScrollEdgeState>;
55114
scroll: () => Promise<TResult>;
115+
/**
116+
* Waits for the previous fling to come to rest before the next capture. A rubber-banded scroll
117+
* moves back and forth for a beat after a fling; capturing mid-bounce makes every pass look new and
118+
* the next fling lands on top of the bounce, compounding it. Default no-op keeps this loop
119+
* device-free; the daemon supplies a real rest-wait.
120+
*/
121+
settleAfterPass?: () => Promise<void>;
56122
}): Promise<{ passes: number; result?: TResult }> {
57-
const { edge, captureState, scroll } = params;
123+
const { edge, captureState, scroll, settleAfterPass = async () => {} } = params;
58124
let state = await captureState();
59125
if (state.scope) {
60126
state = await captureState(state.scope);
61127
}
62128

63129
let passes = 0;
64130
let result: TResult | undefined;
131+
const recentSignatures: string[] = [];
132+
pushScrollSurfaceSignature(recentSignatures, state.fingerprint, SCROLL_EDGE_STUCK_WINDOW);
65133
while (state.canScroll) {
66134
if (passes >= SCROLL_EDGE_PASS_LIMIT) {
67135
throw new AppError(
68136
'COMMAND_FAILED',
69137
`scroll ${edge} reached the safety limit before the snapshot showed the edge`,
70138
{
139+
reason: 'scroll_edge_pass_limit',
140+
edge,
141+
passes,
71142
hint: 'The scoped scroll container still reports hidden content. Run scroll <dir> --until <selector> to stop on the element you are after, or snapshot -i to inspect the current state.',
72143
},
73144
);
74145
}
75146

76147
result = await scroll();
77148
passes += 1;
149+
await settleAfterPass();
78150
state = await captureState(state.scope);
151+
152+
pushScrollSurfaceSignature(recentSignatures, state.fingerprint, SCROLL_EDGE_STUCK_WINDOW);
153+
if (state.canScroll && scrollSurfaceIsStuck(recentSignatures)) {
154+
throw buildScrollEdgeNoProgressError(edge, passes);
155+
}
79156
}
80157

81158
return { passes, result };
@@ -109,6 +186,22 @@ export function formatScrollEdgeMessage(params: {
109186
return `Scrolled ${direction}`;
110187
}
111188

189+
function buildScrollEdgeNoProgressError(edge: ScrollEdge, passes: number): AppError {
190+
const spent = `${passes} ${passes === 1 ? 'pass' : 'passes'}`;
191+
return new AppError(
192+
'COMMAND_FAILED',
193+
`scroll ${edge} moved nothing across ${spent}: the container still reports hidden content but its contents never shifted`,
194+
{
195+
reason: 'scroll_edge_no_progress',
196+
edge,
197+
passes,
198+
hint:
199+
`The scroll is not reaching this container. If a field is focused, dismiss the keyboard first; if it is nested inside another scroller, target it directly with scroll <dir> --until <selector>. ` +
200+
`Some lists ignore synthesized scrolls — a raw drag moves them: swipe x1 y1 x2 y2 started inside the list.`,
201+
},
202+
);
203+
}
204+
112205
function buildScrollEdgeVerificationError(
113206
edge: ScrollEdge,
114207
scope: string | undefined,

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

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ export function analyzeScrollEdgeState(
3939
canScroll,
4040
emptySnapshot: false,
4141
scope: buildScrollContainerScope(container, nodes),
42+
fingerprint: buildSurfaceFingerprint(container, nodes),
4243
};
4344
}
4445

@@ -206,3 +207,48 @@ function containsPoint(rect: NonNullable<SnapshotNode['rect']>, point: Point): b
206207
function isUsableRect(rect: SnapshotNode['rect']): rect is NonNullable<SnapshotNode['rect']> {
207208
return Boolean(rect && rect.width > 0 && rect.height > 0);
208209
}
210+
211+
/**
212+
* A stable signature of the content the container currently shows, built from the container's own
213+
* descendants (via the parent chain), each keyed by identity and rounded position. Scrolling shifts
214+
* descendant rects, so a real pass always changes it; a gesture the container ignores leaves it
215+
* byte-identical. Descendant scoping — not geometric overlap — is the point: it excludes the
216+
* keyboard, its typing predictions, and scroll-indicator overlays, which are not under the scroller
217+
* and would otherwise flicker and mask a stuck container. Rounded to whole pixels so layout jitter
218+
* never fakes movement; a false "unchanged" only defers to a later pass or the pass limit. An empty
219+
* string (a container with no positioned descendants) leaves both loops to their edge/pass signals.
220+
*/
221+
function buildSurfaceFingerprint(container: SnapshotNode, nodes: SnapshotNode[]): string {
222+
const byIndex = new Map<number, SnapshotNode>();
223+
for (const node of nodes) byIndex.set(node.index, node);
224+
const descendants: string[] = [];
225+
for (const node of nodes) {
226+
const rect = node.rect;
227+
if (!isUsableRect(rect)) continue;
228+
if (node.index === container.index || !isDescendantOf(node, container.index, byIndex)) continue;
229+
descendants.push(
230+
`${node.type}#${surfaceIdentity(node)}@${Math.round(rect.x)},${Math.round(rect.y)}`,
231+
);
232+
}
233+
if (descendants.length === 0) return '';
234+
descendants.sort();
235+
return descendants.join(';');
236+
}
237+
238+
function surfaceIdentity(node: SnapshotNode): string {
239+
return (node.identifier ?? node.label ?? node.value ?? '').trim();
240+
}
241+
242+
function isDescendantOf(
243+
node: SnapshotNode,
244+
ancestorIndex: number,
245+
byIndex: ReadonlyMap<number, SnapshotNode>,
246+
): boolean {
247+
let parentIndex = node.parentIndex;
248+
let guard = byIndex.size + 1;
249+
while (parentIndex !== undefined && guard-- > 0) {
250+
if (parentIndex === ancestorIndex) return true;
251+
parentIndex = byIndex.get(parentIndex)?.parentIndex;
252+
}
253+
return false;
254+
}

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

Lines changed: 31 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -193,11 +193,6 @@ test('bound scroll bottom does not scroll when no hidden content is below', asyn
193193
test('bound scroll bottom scrolls only while a scoped capture confirms hidden content', async () => {
194194
const calls: ScrollCall[] = [];
195195
const snapshotScopes: unknown[] = [];
196-
const snapshots = [
197-
makeScrollSnapshot({ hiddenBelow: true, message: 'Middle message' }),
198-
makeScrollSnapshot({ hiddenBelow: true, message: 'Middle message' }),
199-
makeScrollSnapshot({ hiddenBelow: false, message: 'Latest message' }),
200-
];
201196
const result = await runScroll(
202197
['bottom'],
203198
{},
@@ -208,7 +203,12 @@ test('bound scroll bottom scrolls only while a scoped capture confirms hidden co
208203
},
209204
captureSnapshot: async (input) => {
210205
snapshotScopes.push(input.options?.scope);
211-
return snapshots[Math.min(snapshotScopes.length - 1, snapshots.length - 1)];
206+
// Driven by scroll count, not capture count, so the rest-wait's own captures cannot move the
207+
// goalposts: content is hidden until the one pass has run, then the edge is reached.
208+
return makeScrollSnapshot({
209+
hiddenBelow: calls.length === 0,
210+
message: calls.length === 0 ? 'Middle message' : 'Latest message',
211+
});
212212
},
213213
},
214214
);
@@ -225,32 +225,35 @@ test('bound scroll bottom scrolls only while a scoped capture confirms hidden co
225225
});
226226
assert.equal(result.passes, 1);
227227
assert.equal(result.lastPass, 1);
228-
assert.deepEqual(snapshotScopes, [undefined, 'Messages', 'Messages']);
228+
// The loop verifies against the scoped container it discovered, not the unscoped tree.
229+
assert.ok(snapshotScopes.includes('Messages'));
229230
});
230231

231-
test('bound scroll bottom tolerates unchanged signatures while hidden content advances', async () => {
232+
test('bound scroll bottom stops when the surface never shifts under hidden content', async () => {
232233
const calls: ScrollCall[] = [];
233-
const snapshots = [
234-
makeScrollSnapshot({ hiddenBelow: true, message: 'Repeated row' }),
235-
makeScrollSnapshot({ hiddenBelow: true, message: 'Repeated row' }),
236-
makeScrollSnapshot({ hiddenBelow: true, message: 'Repeated row' }),
237-
makeScrollSnapshot({ hiddenBelow: false, message: 'Repeated row' }),
238-
];
239-
let snapshotIndex = 0;
240-
const result = await runScroll(
241-
['bottom'],
242-
{},
243-
{
244-
scroll: async (direction, options) => {
245-
calls.push({ direction, options });
246-
return { lastPass: calls.length };
247-
},
248-
captureSnapshot: async () => snapshots[Math.min(snapshotIndex++, snapshots.length - 1)],
249-
},
234+
await assert.rejects(
235+
() =>
236+
runScroll(
237+
['bottom'],
238+
{},
239+
{
240+
scroll: async (direction, options) => {
241+
calls.push({ direction, options });
242+
return { lastPass: calls.length };
243+
},
244+
// Hidden content below forever, row fixed: the surface signature is byte-identical across
245+
// passes. A gesture that reports hidden content but moves nothing is the stuck-container
246+
// signature, and the loop must stop on it rather than fling to the 40-pass backstop.
247+
captureSnapshot: async () =>
248+
makeScrollSnapshot({ hiddenBelow: true, message: 'Repeated row' }),
249+
},
250+
),
251+
(error: unknown) =>
252+
error instanceof AppError &&
253+
error.code === 'COMMAND_FAILED' &&
254+
error.details?.reason === 'scroll_edge_no_progress',
250255
);
251-
252-
assert.equal(calls.length, 2);
253-
assert.equal(result.passes, 2);
256+
assert.equal(calls.length, 3);
254257
});
255258

256259
test('bound scroll bottom keeps scoped capture failures scoped', async () => {

0 commit comments

Comments
 (0)