Context
In Agent Institution's Activity history, a very small mouse-wheel gesture can move the Neo.list.Buffered viewport by roughly a full visible page. The symptom occurs in both scroll directions and feels discontinuous relative to the physical input.
This is an operator-observed product witness, not yet an independently reproduced Engine result. Agent Institution #63 records an adjacent observation: Activity kind chips can render over-wide initially and become correct after the first scroll. The two symptoms may share a pool-refresh mechanism, but this ticket does not claim that as cause.
The Problem
A buffered list must preserve native scroll-distance fidelity. Row recycling may change which logical records occupy the bounded physical pool; it must not amplify a small wheel movement into a viewport-sized jump.
Without a small-delta witness, the current suite can stay green while scrolling feels broken:
- unit coverage calls
onScrollCapture() with already-decided absolute scrollTop values;
- the Activity Neural Link e2e uses one deliberate
page.mouse.wheel(0, 620) movement and asserts only that scrolling occurred.
Neither proves incremental wheel input remains incremental through a mounted-range boundary.
The Architectural Reality
- Main-thread
src/main/DomEvents.mjs registers wheel passively. Buffered lists are not in globalWheelTargets, so the browser's native scroll seat remains physical authority.
src/component/Base.mjs#onScrollCapture mirrors captured DOM scroll coordinates into VDOM state.
src/list/Buffered.mjs#onScrollCapture then calls createItems() for every captured root scroll.
calculateMountedRange() deliberately keeps the existing range while its requested buffer remains, but createItems() still rebuilds spacer/slot VDOM and stamps vdom.scrollTop when that range is unchanged.
- The method's own contract says the mounted range changes only when a buffer edge is crossed. The unconditional rebuild is therefore a verified implementation/intent discrepancy and a root-cause candidate—not proof that it produces the observed jump.
The Fix
First add a headed, actual-wheel witness over a generic Neo.list.Buffered fixture. Apply repeated small positive and negative pixel deltas, including the gesture that crosses a mounted-range boundary. Observe, in the same run:
- physical DOM
scrollTop;
- App-Worker
scrollTop;
mountedRange;
- physical pool component ids.
Use the result to correct the smallest Engine seam. The likely direction is to update scroll state without rebuilding when mountedRange is unchanged, and to preserve physical scroll authority when a boundary requires rebinding. Coalesce a boundary rebuild only if the red witness proves event overlap is part of the failure.
Contract Ledger
| Target surface |
Source of authority |
Required behavior |
Fallback |
Evidence |
| Native wheel distance |
Browser scroll seat |
Small pixel deltas remain incremental |
No App-Worker wheel reinterpretation |
Headed Playwright wheel witness |
| App scroll state |
Buffered#onScrollCapture |
Mirrors physical scrollTop without amplification |
Clamp only to valid content bounds |
DOM ↔ App-Worker equality |
| Mounted range |
calculateMountedRange |
Stable inside the buffer; advances only at an edge |
One bounded range refresh |
Range and pool-id trace |
| Store anchor |
captureScrollAnchor / restoreScrollAnchor |
Ordinary wheel input does not become a Store-mutation restoration |
Existing mutation semantics remain |
Existing prepend/filter/sort battery |
Decision Record impact
None — this restores the documented native-scroll and bounded-range contract of Neo.list.Buffered.
Acceptance Criteria
Scope transfer, 2026-08-31. The red witness reduced this ticket to a browser scroll-anchoring
defect with a one-property Engine repair (PR #17944). Three criteria below describe instrument
breadth rather than the defect, and their arms live in the #17940 example/instrument lane
(PR #17941) by @neo-gpt-emmy's scope ruling — that lane must not absorb source changes, and this one
must not close over evidence in an unmerged PR. They are transferred, not dropped: each is restated
verbatim on #17940 and remains required there.
Transferred to #17940: the negative-direction half of AC-2, plus AC-4 and AC-5.
Amended by @neo-opus-ada at the author's direction (RA-1 on PR #17944).
Out of Scope
- Replacing Activity with a grid.
- Normalizing OS-specific wheel acceleration or trackpad momentum.
- Preventing default wheel behavior or translating
deltaY in the App Worker.
- Fixing Institution #63's chip geometry unless a shared Engine cause is independently proven.
- Scroll-edge data acquisition (#17835).
Avoided Traps
- A fixed “one row per wheel event” policy would replace native scrolling with an app-specific feel.
- Testing only
onScrollCapture({scrollTop}) proves state acceptance, not user-input fidelity.
- Calling the unconditional rebuild causal before a headed witness would turn a strong code smell into an unsupported diagnosis.
Related
Product witness: neomjs/neo-agent-institution#63. Buffered-list foundation: #17554 / PR #17557. Activity adoption witness: #17550 / PR #17585. Adjacent but distinct: #17835.
Live latest-open sweep: checked the latest 20 open Engine issues immediately before creation; no equivalent found. #17835 concerns scroll-edge data acquisition, not physical scroll distance. Exact GitHub search returned no match. Recent A2A claims contained no overlapping buffered-list wheel lane. Knowledge Base ticket search returned historical generic scroll work, not this symptom.
Origin Session ID: 5c37632a-b342-4f84-a66f-61510b8382d5
Retrieval Hint: Neo.list.Buffered small wheel delta viewport jump createItems mountedRange
Context
In Agent Institution's Activity history, a very small mouse-wheel gesture can move the
Neo.list.Bufferedviewport by roughly a full visible page. The symptom occurs in both scroll directions and feels discontinuous relative to the physical input.This is an operator-observed product witness, not yet an independently reproduced Engine result. Agent Institution #63 records an adjacent observation: Activity kind chips can render over-wide initially and become correct after the first scroll. The two symptoms may share a pool-refresh mechanism, but this ticket does not claim that as cause.
The Problem
A buffered list must preserve native scroll-distance fidelity. Row recycling may change which logical records occupy the bounded physical pool; it must not amplify a small wheel movement into a viewport-sized jump.
Without a small-delta witness, the current suite can stay green while scrolling feels broken:
onScrollCapture()with already-decided absolutescrollTopvalues;page.mouse.wheel(0, 620)movement and asserts only that scrolling occurred.Neither proves incremental wheel input remains incremental through a mounted-range boundary.
The Architectural Reality
src/main/DomEvents.mjsregisterswheelpassively. Buffered lists are not inglobalWheelTargets, so the browser's native scroll seat remains physical authority.src/component/Base.mjs#onScrollCapturemirrors captured DOM scroll coordinates into VDOM state.src/list/Buffered.mjs#onScrollCapturethen callscreateItems()for every captured root scroll.calculateMountedRange()deliberately keeps the existing range while its requested buffer remains, butcreateItems()still rebuilds spacer/slot VDOM and stampsvdom.scrollTopwhen that range is unchanged.The Fix
First add a headed, actual-wheel witness over a generic
Neo.list.Bufferedfixture. Apply repeated small positive and negative pixel deltas, including the gesture that crosses a mounted-range boundary. Observe, in the same run:scrollTop;scrollTop;mountedRange;Use the result to correct the smallest Engine seam. The likely direction is to update scroll state without rebuilding when
mountedRangeis unchanged, and to preserve physical scroll authority when a boundary requires rebinding. Coalesce a boundary rebuild only if the red witness proves event overlap is part of the failure.Contract Ledger
Buffered#onScrollCapturescrollTopwithout amplificationcalculateMountedRangecaptureScrollAnchor/restoreScrollAnchorDecision Record impact
None — this restores the documented native-scroll and bounded-range contract of
Neo.list.Buffered.Acceptance Criteria
#17940.)DOM→ transferred toscrollTopand App-WorkerscrollTopconverge after each gesture without programmatic snap-back.#17940The physical component pool stays bounded and retains its component identities across the boundary.→ transferred to#17940mountedRangeis unchanged, unless the red witness disproves that prescription — disproved. The unconditionalcreateItems()rebuild is real but is not this defect's cause; browser scroll anchoring compensating for the spacer resize is. The rebuild remains a separate performance concern, deliberately untouched.Out of Scope
deltaYin the App Worker.Avoided Traps
onScrollCapture({scrollTop})proves state acceptance, not user-input fidelity.Related
Product witness: neomjs/neo-agent-institution#63. Buffered-list foundation: #17554 / PR #17557. Activity adoption witness: #17550 / PR #17585. Adjacent but distinct: #17835.
Live latest-open sweep: checked the latest 20 open Engine issues immediately before creation; no equivalent found. #17835 concerns scroll-edge data acquisition, not physical scroll distance. Exact GitHub search returned no match. Recent A2A claims contained no overlapping buffered-list wheel lane. Knowledge Base ticket search returned historical generic scroll work, not this symptom.
Origin Session ID: 5c37632a-b342-4f84-a66f-61510b8382d5
Retrieval Hint:
Neo.list.Buffered small wheel delta viewport jump createItems mountedRange