Make snapshot membership loss attributable: scroll clip authority + ejection dispositions
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 25/100
- Issue type
- Bug
- Clarity
- Mostly clear
- Activity status
- Active
- Tech stack
- swift, typescript
Research direction
Start with ADR 0026 and the ownership logic in packages/capture-kit/src/ios-snapshot-engine/scroll.ts, then run the existing differential and conformance tests. Trace properties.test.ts, projection.ts, SnapshotPresentationProjection.swift, semantic-index.ts, and the named suppression rules before surveying captured trees. Done means the presented TextView and WebView cases pass, eligibility parity and typed ejections are enforced, the wrapper result is recorded, and the specified affected, conformance, and differential suites pass.
Written by the indexing model from the issue text.
Description
Purpose
snapshot -i lost every list row after a row holding selectable text (#2214 in 0.21.0, patched for that
one type by #2740). The type-specific fix closed one instance. The class stays open: presentation still
finds a scroll indicator's owner by walking up past its parent, so any host that scrolls but publishes
as a non-scroll type (WebView, a map view, a paged cell) misattributes its indicator to the enclosing
list and clips that list to the host's band. Measured: a synthetic Element(58) row with its own indicator
drops Reply on origin/main.
Design record: ADR 0026 — Scroll Clip Authority: Ownership Is the Parent Edge (proposed, #2755).
Required behavior
Step 1 — ownership is read from the parent edge. The owner of an indicator is its parent, and a band
derives only when that parent is a scroll type. Delete the ancestor walk and isTextViewType from
packages/capture-kit/src/ios-snapshot-engine/scroll.ts. Evidence already collected on a scratch
branch: pnpm test:unit → 10,959 passed / 1 skipped with this substitution, and the Element(58) shape
above stops dropping rows. Land it with the red→green cases from step 2.
Step 2 — extend the differential to the runner stage. assertProjectionSubsets
(packages/capture-kit/src/ios-snapshot-engine/properties.test.ts) asserts interactive ⊆ regular ⊆ raw
but builds acquired inputs only; the Swift differential drops interactive cases. Add a stage: 'presented'
arm plus authored cases for a TextView row (#2740's shape) and a WebView row. Each must fail on
origin/main first, per docs/agents/testing.md. Assert source-level membership, not literally
interactive ⊆ full: the full projection skips semantic compaction.
Step 3 — survey real captured trees for under-clipping. Removing the walk can lose a band when a
real tree places an indicator under a labelled wrapper instead of directly under its scroll view, letting
content scrolled under the chrome survive — the leak class #1784/#1797 removed. Survey captured runner
trees before landing step 1, and record the count of indicators whose parent is not a scroll type. If the
shape is real, decide on evidence whether to skip unlabeled Other wrappers — do not add the tolerance
speculatively.
Step 4 — pair the two eligibility lists, and settle ScrollArea for macOS.
REGULAR_ELIGIBLE_TYPES (ios-snapshot-engine/projection.ts) and eligibleInteractiveTypes
(apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotPresentationProjection.swift)
are one fact in two languages and no test currently references either. They are what makes the parent edge
survive projection: an ineligible wrapper is re-parented to the nearest presented ancestor, which is the
scroll host. Add a shared-table or dual-assertion guard. Note the pair excludes scrollarea while
isScrollableSnapshotType includes it: the iOS runner never emits that type, but macOS desktop capture
reaches these rules (snapshot-desktop-surface.ts → ios-snapshot-runtime.ts → publishIosSnapshot) and
its helper emits ScrollArea. Decide whether macOS needs it eligible before the rule is reused there —
do not resolve it by editing a set for iOS's sake.
Step 5 — inventory ejections, then make them typed. ~23 suppressNode call sites across ten rules
(rows, web, transitions, noise-search, noise-redundancy, noise-structural, noise-overlay,
noise-viewport, action-shelf, scroll); at least two also rewrite rects. Extend the existing
presentedIndexesBySourceIndex (ios-snapshot-engine/semantic-index.ts) into a typed disposition — every
source ends presented with representatives, or removed with at least one reason. If eject requires a
reason the ledger is complete by construction, so no separate gate is needed. Internal evidence only: no
suppression vocabulary on the snapshot wire.
Observable completion conditions
- A
stage: 'presented'case for both theTextViewandWebViewrow shapes fails onorigin/mainand
passes with the change. - No band can derive from anything other than a parent that is a scroll type; grep proves no ancestor walk
remains inscroll.ts. - The wrapper survey result is recorded on this issue with tree counts, and any tolerance it justifies
carries a captured-tree fixture. - Eligibility parity is enforced, not asserted in prose, and the
ScrollAreaquestion is answered for
macOS surfaces — either decided with a case, or recorded as out of scope with the reason. pnpm check:affected --runon the exact pushed head, plus the engine conformance and differential suites.
New ownership cases joincontracts/fixtures/ios-snapshot-engine-conformance.json; they join the Swift
fixture only once Swift implements the same behavior.
Non-goals
- A producer-reported ownership field or capture-local index remapping: the parent edge already carries it.
- Producer-computed visible bands.
- A scroll-capability matrix, or adding
TextView/WebViewto a universal scroll-container set. - A rule-graph/effect framework, or a two-API reshape/eject split before step 5's inventory.
- Treating the unexplained 74 → 67 node delta as an acceptance baseline without a captured artifact.
Dependencies and sequencing
- Blocked by: maintainer decision on ADR 0026 (#2755).
- Steps 1 and 2 land together. Step 3's survey gates step 1's merge. Step 4 is independent. Step 5 last.
runner-presentation.test.tspins the band contract, so the band must not be deleted to dodge the
problem.
Related: #2214 (introduced), #2740 (type-specific fix), ADR 0004 §host-side ownership boundary and the
#2638 regression note ("an absent fact is not a negative answer").
- Dominant language
- TypeScript
- Stars
- 4.7k
- Forks
- 304
- Avg merge
- 11h 46m
- Merged PRs (30d)
- 496
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from callstack/agent-device
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
callstack/agent-device#1869 ·
-
needs-triage
Difficulty 4/5 3-5 days Newbie friendliness 52/100
callstack/agent-device#2751 ·
-
bug ready-for-agent
Difficulty 5/5 Over a week Newbie friendliness 38/100
callstack/agent-device#2728 ·
-
enhancement needs-triage
Difficulty 5/5 Over a week Newbie friendliness 25/100
callstack/agent-device#2725 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 48/100
callstack/agent-device#2719 ·
All issues in callstack/agent-device
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
bug v2
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
modelcontextprotocol/inspector#2458 · 1 comment ·
-
Difficulty 1/5 Under an hour Newbie friendliness 75/100
railmapgen/rmp-gallery#4068 ·
-
Mend: dependency security vulnerability status: needs triage 🕵️♀️
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
carbon-design-system/ibm-products#9907 ·