Skip to content

Commit f4c2c24

Browse files
airoweclaude
andcommitted
fix(scroll): require a same-rect ancestor to report a vertical edge
Geometry carries no scroll axis, so a horizontal pager framing the same pixels as a vertical list on its page could stand in for that list and hide its edge hints. The snapshot emits vertical edge hints only for vertical scrollers, so an ancestor now stands in only when it reports one. subtreeFor matches scopes and reindexes nodes the way an Android scoped snapshot does. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent dc24f9a commit f4c2c24

3 files changed

Lines changed: 38 additions & 14 deletions

File tree

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

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import {
44
type ScrollEdgeTarget,
55
} from '../scroll-edge-state.ts';
66
import { AppError } from '@agent-device/kernel/errors';
7+
import { matchesSnapshotScope, reindexSnapshotNodes } from '@agent-device/contracts/snapshot';
78
import { formatRole } from '@agent-device/kernel/snapshot';
89
import type { RawSnapshotNode, SnapshotNode } from '@agent-device/kernel/snapshot';
910

@@ -117,17 +118,21 @@ export async function captureThrows(scope: string | undefined): Promise<AppError
117118
}
118119
}
119120

120-
/** The scope root's subtree, as an Android scoped snapshot returns it; the whole tree when unscoped. */
121+
/**
122+
* The scope root's subtree, reindexed, as an Android scoped snapshot returns it: the first node in
123+
* document order whose label, value or identifier matches, plus its descendants. Unscoped returns
124+
* the whole tree.
125+
*/
121126
export function subtreeFor(
122127
nodes: readonly SnapshotNode[],
123128
scope: string | undefined,
124129
): SnapshotNode[] {
125130
if (scope === undefined) return [...nodes];
126-
const root = nodes.find((node) => node.identifier === scope);
131+
const root = nodes.find((node) => matchesSnapshotScope(node, scope));
127132
if (!root) return [];
128133
const inScope = new Set([root.index]);
129134
for (const node of nodes) {
130135
if (node.parentIndex !== undefined && inScope.has(node.parentIndex)) inScope.add(node.index);
131136
}
132-
return nodes.filter((node) => inScope.has(node.index));
137+
return reindexSnapshotNodes(nodes.filter((node) => inScope.has(node.index)));
133138
}

‎packages/capture-kit/src/snapshot/__tests__/scroll-edge-state-same-rect-ancestor.test.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,3 +90,16 @@ test('scroll top edge: a targeted node in a cyclic chain with no scrollable ance
9090
assert.equal(state.scope, 'list');
9191
assert.equal(state.canScroll, true);
9292
});
93+
94+
test('scroll bottom edge: a same-rect horizontal pager does not stand in for the vertical list on its page', async () => {
95+
// A horizontal pager reports no vertical edge hints; its page's vertical list carries them.
96+
const rect = { x: 0, y: 100, width: 400, height: 600 };
97+
const nodes = [
98+
windowRoot(),
99+
scrollNode(1, { identifier: 'pager', rect }),
100+
scrollNode(2, { parentIndex: 1, identifier: 'feed', hiddenContentBelow: true, rect }),
101+
];
102+
const state = await capture(nodes, 'bottom');
103+
assert.equal(state.scope, 'feed');
104+
assert.equal(state.canScroll, true);
105+
});

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

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -64,8 +64,11 @@ function selectScrollContainer(
6464
target: ScrollEdgeTarget,
6565
): SnapshotNode | null {
6666
const visibility = createSnapshotVisibility(nodes);
67+
const reportsVerticalEdge = (node: SnapshotNode): boolean =>
68+
hasHiddenContentAtEdge(node, hiddenHints.get(node.index), 'top') ||
69+
hasHiddenContentAtEdge(node, hiddenHints.get(node.index), 'bottom');
6770
const edgeContainer = (node: SnapshotNode): SnapshotNode =>
68-
sameRectScrollableAncestor(node, visibility.nodeByIndex) ?? node;
71+
sameRectScrollableAncestor(node, visibility.nodeByIndex, reportsVerticalEdge) ?? node;
6972
const scrollables = [
7073
...new Set(
7174
nodes
@@ -168,20 +171,23 @@ function hasHiddenContentAtEdge(
168171
}
169172

170173
/**
171-
* The outermost scrollable in an unbroken chain of same-rect scrollable ancestors, or undefined when
172-
* the nearest scrollable ancestor frames different pixels. Scroll edge selection stands that
173-
* ancestor in for the nested scroller: Android's Settings RecyclerView offers scroll-backward even at
174-
* the top, while the ScrollView framing the same pixels reports the real position (#3737). Choosing
175-
* the ancestor also keeps the nested scroller inside the scoped recapture. Visited indexes stop a
176-
* cyclic `parentIndex` chain in a malformed tree.
174+
* The outermost scrollable in an unbroken chain of same-rect, vertically scrolling ancestors, or
175+
* undefined when the nearest scrollable ancestor frames different pixels or reports no vertical edge.
176+
* Scroll edge selection stands that ancestor in for the nested scroller: Android's Settings
177+
* RecyclerView offers scroll-backward even at the top, while the ScrollView framing the same pixels
178+
* reports the real position (#3737). Choosing the ancestor also keeps the nested scroller inside the
179+
* scoped recapture. Visited indexes stop a cyclic `parentIndex` chain in a malformed tree.
177180
*
178-
* This is a geometric heuristic: an identical rect is taken to mean the two scrollers move the same
179-
* content. It ignores scroll axis, so a horizontal scroller framing exactly the same pixels as a
180-
* vertical list nested in it would stand in for that list. No known screen has that shape.
181+
* An identical rect is a geometric heuristic for "these two scrollers move the same content", and
182+
* geometry carries no scroll axis. Requiring the ancestor to report a vertical edge hint keeps a
183+
* horizontal pager whose page holds a vertical list from standing in for that list; the snapshot
184+
* emits vertical edge hints only for vertical scrollers. A vertical ancestor whose content fits in
185+
* both directions reports no edge either, and leaves the nested scroller to answer for itself.
181186
*/
182187
function sameRectScrollableAncestor(
183188
node: SnapshotNode,
184189
byIndex: ReadonlyMap<number, SnapshotNode>,
190+
reportsVerticalEdge: (candidate: SnapshotNode) => boolean,
185191
): SnapshotNode | undefined {
186192
const visited = new Set<number>([node.index]);
187193
let owner: SnapshotNode | undefined;
@@ -190,7 +196,7 @@ function sameRectScrollableAncestor(
190196
while (parent && !visited.has(parent.index)) {
191197
visited.add(parent.index);
192198
if (isScrollableNodeLike(parent) && isUsableRect(parent.rect)) {
193-
if (!sameRect(parent.rect, current.rect)) return owner;
199+
if (!sameRect(parent.rect, current.rect) || !reportsVerticalEdge(parent)) return owner;
194200
owner = parent;
195201
current = parent;
196202
}

0 commit comments

Comments
 (0)