You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 6141e35
Browse filesBrowse the repository at this point in the historyBrowse files
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.
Copy file name to clipboardExpand all lines: docs/adr/0026-scroll-clip-authority.md
+28-13Lines changed: 28 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,8 +16,8 @@ walking up past the indicator's parent, and that guess decided which nodes exist
16
16
17
17
| Situation | Behavior |
18
18
| --- | --- |
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)|
21
21
| The visible band | Derived by presentation from the owner's frame and the indicator's track. Never reported by a producer |
22
22
| 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 |
23
23
| 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 `
34
34
in `SnapshotPresentationProjection.swift` both carry `Cell`, `CollectionView`, `ScrollView`, `Table`,
35
35
`TextView`, and `WebView`. Those two lists are one fact in two languages and must stay in step.
36
36
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
+
37
45
That eligibility claim is scoped to iOS, and `scrollarea` is why. `isScrollableSnapshotType` accepts it,
38
46
neither eligible set contains it, and the iOS runner never emits it — it originates in the macOS helper's
39
47
`AXScrollArea` mapping. That helper's trees do reach these rules, through `snapshot-desktop-surface.ts`
@@ -92,17 +100,24 @@ source of truth.
92
100
93
101
## Consequences and open evidence
94
102
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.
106
121
-**macOS is already a second consumer of these rules.** Desktop capture runs the engine through
107
122
`snapshot-desktop-surface.ts` → `ios-snapshot-runtime.ts` → `publishIosSnapshot`, and its trees carry
108
123
`ScrollArea`, which neither eligible set admits. The parent-edge rule needs its own decision there
0 commit comments