Skip to content

Commit 6141e35

Browse files
committed
fix(ios): read scroll indicator ownership from the parent edge (#2754 step 1)
Ownership of a scroll indicator is now read from the producer's parent edge, passing up only through ancestors that share the scroller's exact frame, instead of walking for the nearest scrollable or text node. A scroll-typed node labelled as an indicator describes itself and owns nothing. This stops an indicator from a scroll-shaped host that publishes as a non-scroll type (a WebView row, a map, a paged cell) from clipping the enclosing list to the host's band (#2214), while a WKWebView page whose wrappers fill the ScrollView keeps its visible band (#1784/#1797). The walk stops at the first frame change, so a host smaller than its list still owns nothing. ADR 0026.
1 parent a374bd9 commit 6141e35

5 files changed

Lines changed: 469 additions & 32 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,16 @@
22

33
## Unreleased
44

5+
- Fixed (ios): an interactive snapshot no longer drops the rows of a list whose row hosts a scroll
6+
view of its own. Ownership of a scroll indicator is now read from its parent edge — a visible band
7+
derives only when the indicator's parent is itself a scroll type — instead of walking ancestors for
8+
the nearest scrollable or text node. #2740 closed the class for `TextView` alone; the walk still
9+
misattributed the indicator of any other scroll-shaped host that publishes as a non-scroll type (a
10+
`WebView`, a map view, a paged cell) to the enclosing list and clipped that list to the host's
11+
one-line band. Ownership still passes up through ancestors that share the scroller's exact frame, so a
12+
`WKWebView` page — whose indicator sits under `WebView` wrappers that fill the scroll view — keeps its
13+
visible band; the walk stops at the first frame change, so a host smaller than its list still owns
14+
nothing. ADR 0026.
515
- Fixed (ios): `fold half-open` no longer reports a pose the hinge never held. The command accepted
616
the requested category as the answer whenever its four-read budget happened to end on a
717
`half-open` angle, so a hinge still sweeping from 180° toward 0° — which passes through every

‎contracts/fixtures/ios-snapshot-engine-conformance.json‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1165,6 +1165,173 @@
11651165
}
11661166
]
11671167
}
1168+
},
1169+
{
1170+
"name": "scroll indicator owned by a parent web view keeps list rows",
1171+
"swift": false,
1172+
"projection": "regular",
1173+
"interactiveOnly": true,
1174+
"depth": null,
1175+
"scope": null,
1176+
"foldPolicy": "cursor-projected",
1177+
"truncated": false,
1178+
"residue": [],
1179+
"nodes": [
1180+
{
1181+
"index": 0,
1182+
"type": "Application",
1183+
"label": "App",
1184+
"rect": { "x": 0, "y": 0, "width": 320, "height": 240 },
1185+
"enabled": true,
1186+
"hittable": false,
1187+
"depth": 0
1188+
},
1189+
{
1190+
"index": 1,
1191+
"type": "Table",
1192+
"label": "Feed",
1193+
"rect": { "x": 0, "y": 40, "width": 320, "height": 200 },
1194+
"enabled": true,
1195+
"hittable": false,
1196+
"depth": 1,
1197+
"parentIndex": 0
1198+
},
1199+
{
1200+
"index": 2,
1201+
"type": "Other",
1202+
"label": "Story",
1203+
"rect": { "x": 16, "y": 60, "width": 288, "height": 22 },
1204+
"enabled": true,
1205+
"hittable": false,
1206+
"depth": 2,
1207+
"parentIndex": 1
1208+
},
1209+
{
1210+
"index": 3,
1211+
"type": "WebView",
1212+
"label": "Story",
1213+
"rect": { "x": 16, "y": 60, "width": 288, "height": 22 },
1214+
"enabled": true,
1215+
"hittable": false,
1216+
"depth": 3,
1217+
"parentIndex": 2
1218+
},
1219+
{
1220+
"index": 4,
1221+
"type": "Other",
1222+
"label": "Vertical scroll bar, 1 page",
1223+
"value": "0%",
1224+
"rect": { "x": 300, "y": 60, "width": 10, "height": 22 },
1225+
"enabled": true,
1226+
"hittable": false,
1227+
"depth": 4,
1228+
"parentIndex": 3
1229+
},
1230+
{
1231+
"index": 5,
1232+
"type": "Button",
1233+
"label": "Reply",
1234+
"rect": { "x": 16, "y": 100, "width": 60, "height": 28 },
1235+
"enabled": true,
1236+
"hittable": true,
1237+
"depth": 2,
1238+
"parentIndex": 1
1239+
},
1240+
{
1241+
"index": 6,
1242+
"type": "Button",
1243+
"label": "Like",
1244+
"rect": { "x": 16, "y": 140, "width": 60, "height": 28 },
1245+
"enabled": true,
1246+
"hittable": true,
1247+
"depth": 2,
1248+
"parentIndex": 1
1249+
},
1250+
{
1251+
"index": 7,
1252+
"type": "Other",
1253+
"label": "Vertical scroll bar, 3 pages",
1254+
"value": "0%",
1255+
"rect": { "x": 306, "y": 40, "width": 10, "height": 150 },
1256+
"enabled": true,
1257+
"hittable": false,
1258+
"depth": 2,
1259+
"parentIndex": 1
1260+
}
1261+
],
1262+
"expected": {
1263+
"outcome": "success",
1264+
"truncated": false,
1265+
"residue": [],
1266+
"nodes": [
1267+
{
1268+
"index": 0,
1269+
"type": "Application",
1270+
"label": "App",
1271+
"rect": { "x": 0, "y": 0, "width": 320, "height": 240 },
1272+
"depth": 0,
1273+
"parentIndex": null,
1274+
"hittable": false,
1275+
"hiddenContentAbove": false,
1276+
"hiddenContentBelow": false
1277+
},
1278+
{
1279+
"index": 1,
1280+
"type": "Table",
1281+
"label": "Feed",
1282+
"rect": { "x": 0, "y": 40, "width": 320, "height": 150 },
1283+
"depth": 1,
1284+
"parentIndex": 0,
1285+
"hittable": false,
1286+
"hiddenContentAbove": false,
1287+
"hiddenContentBelow": true
1288+
},
1289+
{
1290+
"index": 2,
1291+
"type": "Other",
1292+
"label": "Story",
1293+
"rect": { "x": 16, "y": 60, "width": 288, "height": 22 },
1294+
"depth": 2,
1295+
"parentIndex": 1,
1296+
"hittable": false,
1297+
"hiddenContentAbove": false,
1298+
"hiddenContentBelow": false
1299+
},
1300+
{
1301+
"index": 3,
1302+
"type": "WebView",
1303+
"label": "Story",
1304+
"rect": { "x": 16, "y": 60, "width": 288, "height": 22 },
1305+
"depth": 3,
1306+
"parentIndex": 2,
1307+
"hittable": false,
1308+
"hiddenContentAbove": false,
1309+
"hiddenContentBelow": false
1310+
},
1311+
{
1312+
"index": 4,
1313+
"type": "Button",
1314+
"label": "Reply",
1315+
"rect": { "x": 16, "y": 100, "width": 60, "height": 28 },
1316+
"depth": 2,
1317+
"parentIndex": 1,
1318+
"hittable": true,
1319+
"hiddenContentAbove": false,
1320+
"hiddenContentBelow": false
1321+
},
1322+
{
1323+
"index": 5,
1324+
"type": "Button",
1325+
"label": "Like",
1326+
"rect": { "x": 16, "y": 140, "width": 60, "height": 28 },
1327+
"depth": 2,
1328+
"parentIndex": 1,
1329+
"hittable": true,
1330+
"hiddenContentAbove": false,
1331+
"hiddenContentBelow": false
1332+
}
1333+
]
1334+
}
11681335
}
11691336
]
11701337
}

‎docs/adr/0026-scroll-clip-authority.md‎

Lines changed: 28 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@ walking up past the indicator's parent, and that guess decided which nodes exist
1616

1717
| Situation | Behavior |
1818
| --- | --- |
19-
| Which scroll view an indicator reports on | Its **parent**, when that parent is a scroll type (or the scroll host itself when it carries the label — open, below). UIKit publishes an indicator inside its own scroll view, and the producer's tree already says so |
20-
| An indicator whose parent is not a scroll type — `TextView`, `WebView`, a cell | Owns nothing. No band, no clip, and the host's own scrollability stays with that host |
19+
| Which scroll view an indicator reports on | Its **parent**, when that parent is a scroll type. UIKit publishes an indicator inside its own scroll view, and the producer's tree already says so. Ownership also passes **up through ancestors that share their own parent's exact frame** — the producer's transparent wrappers around one scroll region (Safari nests `Other` → `WebView` → `WebView` above a `WKWebView`'s `ScrollView`, all one frame). A node that is **itself** a scroll type and carries the label describes itself, not its parent, so it owns nothing (resolved: #2754 step 1 — banding its parent would clip a sibling list to the host's band, mirroring #2214 upward) |
20+
| An indicator whose nearest scroll-typed ancestor is reached only across a frame change — a smaller `TextView`/`WebView`/cell host | Owns nothing. No band, no clip, and the host's own scrollability stays with that host. The frame change, not a label or type, is what ends the walk (resolved: #2754 step 3 on a real `WKWebView` capture) |
2121
| The visible band | Derived by presentation from the owner's frame and the indicator's track. Never reported by a producer |
2222
| Removing a node **because a scroll band hides it** | Requires evidence: the clip fold's result, or a band whose owner is the indicator's parent. A guess about ownership may not do it |
2323
| Removing a node by semantic delegation — a collapsed row, a duplicate label, a wrapper's content | Out of scope here. That is compaction, and it keeps its own authority |
@@ -34,6 +34,14 @@ that host: `REGULAR_ELIGIBLE_TYPES` in `ios-snapshot-engine/projection.ts` and `
3434
in `SnapshotPresentationProjection.swift` both carry `Cell`, `CollectionView`, `ScrollView`, `Table`,
3535
`TextView`, and `WebView`. Those two lists are one fact in two languages and must stay in step.
3636

37+
Passing ownership up through **same-frame** ancestors keeps ownership read rather than inferred: the
38+
producer states two nodes are the same rectangle, which is a structural fact, not a label or type guess.
39+
It is needed because a `WKWebView`'s page indicator is published under `WebView` wrappers that fill the
40+
`ScrollView` exactly (#1784/#1797, and real captures in #2754 step 3); strict parent-edge ownership left
41+
that scroller unbanded and returned content scrolled under the toolbar. The walk stops at the first frame
42+
change, so a host that is smaller than its parent — a `WebView` row in a list — is a different scroll
43+
region and still owns nothing, which is the #2214 bug the pass-through must not reintroduce.
44+
3745
That eligibility claim is scoped to iOS, and `scrollarea` is why. `isScrollableSnapshotType` accepts it,
3846
neither eligible set contains it, and the iOS runner never emits it — it originates in the macOS helper's
3947
`AXScrollArea` mapping. That helper's trees do reach these rules, through `snapshot-desktop-surface.ts`
@@ -92,17 +100,24 @@ source of truth.
92100

93101
## Consequences and open evidence
94102

95-
- **Under-clipping is the new risk.** Dropping the walk means a tree that places an indicator under a
96-
labelled wrapper rather than directly under its scroll view gets no band, so content scrolled under the
97-
chrome survives in the output. That is a leak of a different kind from the one the clip fold owns
98-
(#1797, with #1784 adjacent on private-AX projection); it is the band's own job, and nothing else covers
99-
it. Measured so far: the full unit suite passes with parent-edge ownership, and a synthetic `WebView` row
100-
keeps rows that `main` drops. Real captured trees must be surveyed for that wrapper shape before landing.
101-
- **The `WebView` instance is synthetic.** The mechanism is confirmed in a hand-built tree; that XCTest
102-
publishes a `WKWebView`'s indicator the same way is unverified.
103-
- **The self case is unpinned.** The rule also treats a scroll-typed node carrying an indicator label as
104-
its own owner. No test exercises that branch — parent-only ownership without it passes the full suite —
105-
so #2754 step 1 keeps it with a case or deletes it deliberately, rather than inheriting it.
103+
- **Under-clipping was the open risk; same-frame pass-through resolves the real instance.** Strict
104+
parent-edge ownership left a `WKWebView` page scroller unbanded because the page indicator is published
105+
under `WebView` wrappers, leaking content under the toolbar (#1797, with #1784 adjacent). #2754 step 3
106+
surveyed real captures (Settings, Settings › Privacy & Security, a Safari `WKWebView` page — 25 indicators,
107+
18 under a non-scroll parent) and found exactly this shape on the web surface. Resolved by passing
108+
ownership through same-frame ancestors, which reproduces `main`'s clip on all three real captures while
109+
the smaller-host row cases (#2214) still own nothing. A genuinely frame-mismatched non-scroll wrapper
110+
would still under-clip, but no captured iOS tree has that shape.
111+
- **The `WebView` shape is now confirmed on real data.** A Safari `snapshot -i --raw` capture shows the
112+
`WKWebView`'s indicator published under `Other` → `WebView` → `WebView` ancestors that fill the
113+
`ScrollView` exactly; the fixture in `runner-presentation.test.ts` reduces that live tree.
114+
- **The self case is resolved: a scroll-typed indicator owns nothing.** #2754 step 1 deleted the
115+
self-ownership branch. Reading a scroll-typed node labelled as an indicator onto its own band is a
116+
no-op (the indicator and container are the same rect, which `deriveScrollableViewportRect` refuses),
117+
while reading it onto its parent clips a sibling list to that host — the #2214 failure mirrored
118+
upward. So `findScrollIndicatorContainer` returns null when the node is itself a scroll type;
119+
`runner-presentation.test.ts` pins a scroll host labelled as an indicator leaving its parent list's
120+
band intact.
106121
- **macOS is already a second consumer of these rules.** Desktop capture runs the engine through
107122
`snapshot-desktop-surface.ts` → `ios-snapshot-runtime.ts` → `publishIosSnapshot`, and its trees carry
108123
`ScrollArea`, which neither eligible set admits. The parent-edge rule needs its own decision there

0 commit comments

Comments
 (0)