|
1 | | -# ADR 0026: Scroll Clip Authority — Inference May Reshape, Never Eject |
| 1 | +# ADR 0026: Scroll Clip Authority — Ownership Is the Parent Edge |
2 | 2 |
|
3 | 3 | ## Status |
4 | 4 |
|
5 | | -Proposed (2026-09-22). Refines ADR 0004's acquisition/presentation boundary for scroll geometry; it |
6 | | -does not supersede it. Implementation contract: #2754. |
| 5 | +Proposed (2026-09-22), revised after review. Refines ADR 0004's fact/interpretation boundary for scroll |
| 6 | +geometry; does not supersede it. Implementation contract: #2754. |
7 | 7 |
|
8 | | -An interactive iOS snapshot dropped every list row after a row holding selectable text. A `UITextView` |
9 | | -is a UIScrollView and XCTest publishes its scroll indicator inside the text, so the indicator was |
10 | | -attributed to the surrounding list and the list's visible band became one 22 px line; everything below |
11 | | -it was clipped out of `snapshot -i`. The root cause is not the wrong type: it is that a **tree-walking |
12 | | -guess about which scroll view an indicator describes was given the power to decide which nodes exist |
13 | | -in the output.** This ADR separates those two powers. |
| 8 | +An interactive iOS snapshot of a list dropped every row after a row holding selectable text. A |
| 9 | +`UITextView` is a UIScrollView and XCTest publishes its scroll indicator inside the text, so the |
| 10 | +indicator was attributed to the surrounding list, the list's visible band became one 22 px line, and |
| 11 | +everything below it was clipped out of `snapshot -i` (#2214 in 0.21.0, patched for that one type by |
| 12 | +#2740). The root cause is not the unrecognised type — it is that presentation **inferred** an owner by |
| 13 | +walking up past the indicator's parent, and that guess decided which nodes existed in the output. |
14 | 14 |
|
15 | 15 | ## Rules at a glance |
16 | 16 |
|
17 | 17 | | Situation | Behavior | |
18 | 18 | | --- | --- | |
19 | | -| Which scroll view an indicator reports on | A **reported** fact from the producer: the owner element, named capture-locally | |
20 | | -| Producer cannot report ownership (private-AX, tree backends) | An **inferred** attribution, explicitly typed as inferred | |
21 | | -| An inferred attribution | May add directional hints (`hiddenContentAbove` / `hiddenContentBelow`). May not rewrite a container's rect or remove a node | |
22 | | -| A reported attribution | May additionally establish that container's visible band | |
23 | | -| Indicator inside a `TextView`, `WebView`, or other host that scrolls but publishes as a non-scroll type | Ownership terminates at that host. The enclosing list keeps its own band and loses no rows | |
24 | | -| Visible clip for an acquired input | The clip fold's viewport-intersected container frame, unchanged | |
25 | | -| Visible clip for a runner-presented input | The same fold rule, refined only by reported ownership | |
26 | | -| Any rule that removes a node from output | Must go through the eject surface with a typed reason | |
27 | | -| "Is this a scroll container?" | A capability matrix (`mayOwnIndicator`, `mayEstablishViewportClip`, `terminatesAncestorOwnership`), never one boolean | |
28 | | -| Interactive output shrinks | Every removed source has a recorded disposition, and a gate says so | |
29 | | -| Producer proposes a visible band | Refused. The band is interpretation, not evidence | |
| 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 | |
| 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 | |
| 21 | +| The visible band | Derived by presentation from the owner's frame and the indicator's track. Never reported by a producer | |
| 22 | +| Removing a node from output | Requires evidence: a clip fold result, or a parent-edge owner. A guess about ownership may not do it | |
| 23 | +| Weaker evidence than a parent edge | Directional hints (`hiddenContentAbove` / `hiddenContentBelow`) and nothing that changes membership | |
| 24 | +| Every removed source | Ends with a typed disposition. Internal evidence, never wire vocabulary | |
30 | 25 |
|
31 | 26 | ## Contracts |
32 | 27 |
|
33 | | -**1. Ownership is a fact; the band is interpretation.** ADR 0004 kept interpretation on the host so no |
34 | | -backend carried its own copy of it. Indicator→owner attribution is a fact about what the producer |
35 | | -traversed — XCTest knows which UIScrollView it took the indicator from — so the runner publishes it and |
36 | | -the host still decides the clip. The producer reports **no** band: a producer-computed band moves the |
37 | | -interpretation back across the process boundary it was removed from. |
38 | | - |
39 | | -The fact belongs with the payload, not with the validation claims: `IosRunnerPresentation`, beside |
40 | | -`payload` (`packages/contracts/src/ios-snapshot.ts:165-189`), not `IosSnapshotValidationFacts`, whose |
41 | | -members are viewport, hittability, lineage, and residue. |
42 | | - |
43 | | -**2. The owner reference is capture-local.** Swift reindexes presented nodes after eligibility, scope, |
44 | | -and depth (`apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotPresentationProjection.swift:59-87`). |
45 | | -An owner index must therefore be consumed or remapped before host compaction, never carried across a |
46 | | -reindex. A producer-side ancestor walk that merely relocates today's heuristic is not a reported fact |
47 | | -and does not earn band authority. |
48 | | - |
49 | | -**3. Reshape and eject are different authorities.** The presentation rule seam |
50 | | -(`packages/capture-kit/src/ios-snapshot-engine/semantic-index.ts:9-18`) currently hands all five passes |
51 | | -one context whose `suppressNode` is unrestricted |
52 | | -(`packages/capture-kit/src/ios-snapshot-engine/tree.ts:5-13`). Split it: |
53 | | - |
54 | | -```ts |
55 | | -type ReshapeApi = { |
56 | | - current(index: number): RawSnapshotNode; |
57 | | - replaceFacts(index: number, patch: Partial<RawSnapshotNode>): void; |
58 | | - addScrollHint(index: number, hint: { above?: true; below?: true }): void; |
59 | | -}; |
60 | | - |
61 | | -type MembershipApi = ReshapeApi & { |
62 | | - eject(index: number, reason: EjectionReason): void; |
63 | | -}; |
64 | | - |
65 | | -type EjectionReason = |
66 | | - | { kind: 'semantic-representative'; representativeIndexes: readonly number[] } |
67 | | - | { kind: 'noise' } |
68 | | - | { kind: 'viewport-clip'; authority: 'fold' | 'reported-ownership' }; |
69 | | -``` |
70 | | - |
71 | | -Scroll-indicator interpretation receives `ReshapeApi`. Only the single clip-application rule receives |
72 | | -`MembershipApi`. "Low-confidence geometry cannot change membership" is then a compile-time property of |
73 | | -which argument a rule is handed, not a convention inside the rule body. |
74 | | - |
75 | | -**4. Scroll capability is a matrix.** `mayOwnIndicator`, `mayEstablishViewportClip`, and |
76 | | -`terminatesAncestorOwnership` are three different questions and today get one boolean answered five |
77 | | -different ways: `ios-snapshot-engine/tree.ts:171-179`, `geometry-policy.ts:6`, `invariants.ts:12`, |
78 | | -`SnapshotVisibilityFold.swift:18`, `RunnerTests+Snapshot.swift:128-132`. A text or web host answers |
79 | | -`mayOwnIndicator: true, terminatesAncestorOwnership: true, mayEstablishViewportClip: false`. Adding |
80 | | -`TextView`/`WebView` to a universal scroll-container set is refused for the same reason the fix in #2740 |
81 | | -was insufficient: it would let those hosts establish clips as well. |
82 | | - |
83 | | -**5. One clip resolver, evidence-gated.** The acquired path folds |
84 | | -(`ios-snapshot-engine/engine.ts:108-132`, anchor rule `geometry-policy.ts:179`); the runner path skips |
85 | | -the fold and clips to an indicator band instead (`runner-presentation.ts:104-115`). One resolver, with |
86 | | -the viewport-intersected container frame as the safe default and reported ownership as the only |
87 | | -refinement. The band remains necessary — XCTest reports a UIScrollView's frame as its content extent, so |
88 | | -the container's own frame cannot express visibility alone — but it may only be applied to a container |
89 | | -whose ownership is reported. |
90 | | - |
91 | | -**6. Ancestors are read from one tree.** Indicator detection reads presented nodes while ownership walks |
92 | | -source nodes (`ios-snapshot-engine/scroll.ts:22` vs `:74`), so a rule that rewrites a type — `web.ts:26-29` |
93 | | -turns `element(58)` into `WebView` — is invisible to the ownership walk that runs after it. Predicates see |
94 | | -the effective view. |
95 | | - |
96 | | -**7. Ejections are accounted for.** Every source index ends with a disposition: presented (with its |
97 | | -representatives) or ejected (with at least one reason). The ledger is internal evidence; reasons stay off |
98 | | -the public snapshot wire. |
99 | | - |
100 | | -**8. Differential coverage covers both stages.** `assertProjectionSubsets` |
101 | | -(`ios-snapshot-engine/properties.test.ts:107-133`) builds acquired inputs only, and the Swift differential |
102 | | -drops interactive cases (`scripts/ios-snapshot-differential.test.ts:24`). The subset property must run |
103 | | -`stage: 'presented'` inputs too. Assert source-level membership plus dispositions — not literally |
104 | | -`interactive ⊆ full`, which is false because the full projection skips semantic compaction |
105 | | -(`engine.ts:121-126`). |
| 28 | +**Ownership is read, not inferred.** A scroll view's indicators arrive as its children, so the parent |
| 29 | +edge is the producer's own claim and no new contract field, cross-language ownership table, or |
| 30 | +capture-local index remapping is needed. That edge survives to presentation on both input stages |
| 31 | +because every scroll host is regular-eligible, so projection re-parents an indicator only to that host: |
| 32 | +`REGULAR_ELIGIBLE_TYPES` in `ios-snapshot-engine/projection.ts` and `eligibleInteractiveTypes` in |
| 33 | +`SnapshotPresentationProjection.swift` both carry `Cell`, `CollectionView`, `ScrollView`, `Table`, |
| 34 | +`TextView`, and `WebView`. Those two lists are one fact in two languages and must stay in step. |
| 35 | + |
| 36 | +**Why the band exists at all.** XCTest reports a scroll view's frame spanning the bars and the safe |
| 37 | +area, not the visible track. In the pinned Settings tree the `CollectionView` frame is the whole screen, |
| 38 | +0–874, while its indicator track is 116–812 (`runner-presentation.test.ts`). The frame alone therefore |
| 39 | +cannot express visibility, and deleting indicator clipping would return content that is scrolled under |
| 40 | +the chrome. The band is necessary; only *who owns it* was ever in question. |
| 41 | + |
| 42 | +**Ejection needs evidence, and is recorded.** Removing a node from the regular output is the one |
| 43 | +decision a weak signal must not make. Directional hints are the safe outlet for anything short of a |
| 44 | +parent-edge owner. Every source index ends either presented, with its representatives, or removed with a |
| 45 | +typed reason — which makes the ledger complete by construction rather than gated. The existing |
| 46 | +`presentedIndexesBySourceIndex` in `ios-snapshot-engine/semantic-index.ts` is the shape to extend; a |
| 47 | +second parallel ledger would be a second source of truth. |
106 | 48 |
|
107 | 49 | ## Refuted alternatives |
108 | 50 |
|
109 | | -- **Producer-computed visible band.** Reopens the per-backend interpretation ADR 0004 closed. |
110 | | -- **The indicator band as the single global clip authority.** Recreates this incident for every host |
111 | | - whose indicator is not its own; deleting indicator clipping instead breaks the contract pinned by |
112 | | - `runner-presentation.test.ts:17-34`. |
113 | | -- **A universal "is scroll container" set.** Five sites already diverge, and some divergence is real: |
114 | | - `ScrollArea` comes from the macOS helper's `AXScrollArea` mapping |
115 | | - (`apple/macos-helper/Sources/AgentDeviceMacOSHelper/SnapshotTraversal.swift:597`) and may reach shared |
116 | | - rules deliberately. Unifying without characterizing each site is a behavior change in disguise. |
117 | | -- **A generic rule graph or effect system.** The two interfaces above are the enforcement; a framework |
118 | | - would be a larger thing to get wrong. |
119 | | -- **Cross-language parity asserted early.** Indicator cases join the Swift golden fixture only when Swift |
120 | | - implements the behavior. |
121 | | - |
122 | | -## Evidence gaps kept open |
123 | | - |
124 | | -- 0.20.8 produced 74 nodes on the reporting screen, this fix 67. No captured artifact explains the |
125 | | - difference; neither number is an acceptance baseline until one exists. |
126 | | -- Whether `ScrollArea` reaches the iOS engine rules on purpose, and what each of the five scroll-type |
127 | | - sites actually needs, must be characterized before any set is unified. |
| 51 | +- **A producer-reported ownership field.** The first draft of this ADR required one on |
| 52 | + `IosRunnerPresentation`, plus capture-local indexing and remapping. The parent edge already carries the |
| 53 | + fact, so the field, its validation, and its hazards are all unnecessary. |
| 54 | +- **Producer-computed visible bands.** Moves interpretation back across the process boundary ADR 0004 |
| 55 | + removed it from. The band stays host-side. |
| 56 | +- **An owner found by walking ancestors.** That walk is the incident. Skipping only the types known to |
| 57 | + scroll — #2740's fix — leaves the next scroll-shaped host (`WebView`, a map view, a paged cell) to |
| 58 | + reopen it. |
| 59 | +- **One universal "is a scroll container" set, or a capability matrix of ownership/clip/termination |
| 60 | + booleans.** Five sites answer variants of this question today (`ios-snapshot-engine/tree.ts`, |
| 61 | + `geometry-policy.ts`, `invariants.ts`, `SnapshotVisibilityFold.swift`, `RunnerTests+Snapshot.swift`) |
| 62 | + and at least one divergence is deliberate. Characterise them before reshaping them; with parent-edge |
| 63 | + ownership the shape this rule needs is the existing `isScrollableSnapshotType`. |
| 64 | +- **A rule-graph or effect system, and a two-API reshape/eject split.** Rejected on the shape of the |
| 65 | + code: `suppressNode` already has ~23 call sites across ten rules, most legitimately ejecting, so |
| 66 | + handing `MembershipApi` to "one clip rule" restores the convention it claims to enforce. A reshape |
| 67 | + surface that still accepts `rect` would permit the exact rewrite that caused this incident. Inventory |
| 68 | + the ejection sites in #2754 first; redesign only what the inventory justifies. |
| 69 | +- **A runtime guard substituting for the differential.** The subset property exists |
| 70 | + (`assertProjectionSubsets`, `ios-snapshot-engine/properties.test.ts`) but builds acquired inputs only, |
| 71 | + and the Swift differential drops interactive cases. Extending it to `stage: 'presented'` is what makes |
| 72 | + any future shrinkage visible. |
| 73 | + |
| 74 | +## Consequences and open evidence |
| 75 | + |
| 76 | +- **Under-clipping is the new risk.** Dropping the walk means a tree that places an indicator under a |
| 77 | + labelled wrapper rather than directly under its scroll view gets no band, so content scrolled under |
| 78 | + the chrome can survive in the output — the leak class #1784/#1797 removed. Measured so far: the full |
| 79 | + unit suite passes with parent-edge ownership, and a synthetic `WebView` row keeps rows that `main` |
| 80 | + drops. Real captured trees must be surveyed for that wrapper shape before landing. |
| 81 | +- **The `WebView` instance is synthetic.** The mechanism is confirmed in a hand-built tree; that XCTest |
| 82 | + publishes a `WKWebView`'s indicator the same way is unverified. |
| 83 | +- **Ejection inventory precedes any API change.** ~23 suppression sites, ten rules, and at least two |
| 84 | + that rewrite rects as well as eject. |
| 85 | +- **The 74 → 67 node delta on the reporting screen is unexplained.** No captured artifact exists, so |
| 86 | + neither number is an acceptance baseline. |
0 commit comments