Skip to content

Commit 000a220

Browse files
committed
docs(adr): read scroll indicator ownership from the parent edge
Review found the first draft built eight contracts on top of a bug that a parent-edge lookup removes. UIKit publishes an indicator inside its own scroll view and projection preserves that edge, because every scroll host is regular-eligible in both languages; the ancestor walk past the parent is what misattributed the text view's indicator in the first place. Reading the parent instead retires the proposed IosRunnerPresentation field, its capture-local indexing and remapping, the ownership capability matrix, and the two-tree split. Also corrects the band's premise: the pinned Settings tree has the CollectionView frame at 0-874 with an indicator track at 116-812, so the frame spans the bars and safe area rather than reporting a content extent. Drops the two-API reshape/eject split, which does not hold against ~23 suppression sites across ten rules, and against a reshape surface that still accepts rect. Keeps the decision: ownership is read, ejection needs evidence, every removal carries a disposition. Measured while revising: the full unit suite passes with parent-edge ownership, and a synthetic WebView row keeps rows that main drops.
1 parent e22dacd commit 000a220

2 files changed

Lines changed: 72 additions & 113 deletions

File tree

Lines changed: 71 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -1,127 +1,86 @@
1-
# ADR 0026: Scroll Clip Authority — Inference May Reshape, Never Eject
1+
# ADR 0026: Scroll Clip Authority — Ownership Is the Parent Edge
22

33
## Status
44

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.
77

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.
1414

1515
## Rules at a glance
1616

1717
| Situation | Behavior |
1818
| --- | --- |
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 |
3025

3126
## Contracts
3227

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.
10648

10749
## Refuted alternatives
10850

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.

‎docs/adr/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
| [0023 End-State Entry-to-Platform Hop Trace](0023-end-state-hop-trace.md) | the hop counting definition, the ordered `press`/Android and dual-arm `snapshot`/iOS chains, per-hop roles, and the deletion test behind the numbers ADR 0019 and ADR 0022 quote |
2828
| [0024 Screen Recording — One Coordinator, Two Facts (Proposed)](0024-screen-recording-provable-signal.md) | `record start`/`stop` lifecycle, the export-exists / recorder-stopped split, backend stop-and-collect contract, recovery through the coordinator, the ADR 0019 §5 amendment and the failed-finish cleanup fix |
2929
| [0025 Foldable Apple Panels — Capture the Lit Panel](0025-foldable-apple-panels.md) | iPhone Duo outer/inner panels, CoreDevice display info as the only screen authority, why `simctl`'s implicit display default captures a black panel, derived (never asserted) pose, and why no pose-control command exists |
30-
| [0026 Scroll Clip Authority — Inference May Reshape, Never Eject (Proposed)](0026-scroll-clip-authority.md) | iOS scroll indicators and the visible band, who may remove a node from an interactive snapshot, reshape vs eject rule authority, the scroll-capability matrix, and ejection dispositions |
30+
| [0026 Scroll Clip Authority — Ownership Is the Parent Edge (Proposed)](0026-scroll-clip-authority.md) | iOS scroll indicators and the visible band, why ownership is read from the parent edge instead of an ancestor walk, what may remove a node from an interactive snapshot, and ejection dispositions |
3131

3232
ADRs record *why*; the registries and gates they describe are the living source of truth — when
3333
prose and a registry disagree, the registry wins and the ADR needs a follow-up.

0 commit comments

Comments
 (0)