paseo/docs/agent-stream-disclosure.md

Agent stream disclosures

Expanding or collapsing something in the chat timeline (a turn's summary line, a tool-call group, a tool call's inline details, a todo card, a long user message's show more, a plan card) keeps the tapped trigger at the same screen y in the first painted frame. No animation.

The contract

A disclosure component knows nothing about the list. It wraps its state change:

const hold = useDisclosureHold();
const handleToggle = () => hold(() => setExpanded((value) => !value));

view.tsx wraps every timeline row in DisclosureRow, which routes hold to the strategy's holdRow(rowId, apply, triggerEdge) (packages/app/src/agent-stream/disclosure.tsx). Outside a timeline row, apply runs as is. The strategy owns when apply runs and how the row keeps its place. A toggle that calls setState directly skips the hold: on Android the expanded content paints over the next row for a frame before the list learns the new size.

triggerEdge names the edge of the row the trigger sits on, and the strategy keeps that edge in place. Header triggers sit on the top edge, the default. A long user message's show more sits under the text it opens, so MessagePreview passes { triggerEdge: "bottom" }: the text grows and shrinks above the trigger, and the rows below stay put.

Following output:

• A hold detaches the bottom anchor controller (holdForDisclosure), except a bottom-edge hold on native while following: there the end pin already keeps the row's bottom in place.
• When the hold ends, the controller re-sticks only if the list sits at its end and no user scroll owns the viewport (releaseDisclosure({ isAtEnd })). Expanding at the bottom therefore leaves the list detached with the scroll-to-bottom pill showing; collapsing back to the end resumes following.
• Scroll events during the hold never re-stick: the correction is a programmatic scroll that would otherwise read as "back at the bottom".

The trigger can only stay put when the list has scroll room for the change. When the loaded content fits the viewport, or a collapse at the end would need an offset past the end, the list ends at its end and the trigger moves by the difference.

Web

holdRow pins the row's trigger edge in the reading anchor and runs apply; the next reading reconcile restores that edge after layout, before paint (strategy-web.tsx). The pin records the scroll offset it was taken at, because the browser clamps scrollTop when a collapse shrinks the content past the offset, before the reconcile reads it. Restoring from the clamped offset would apply the shrink twice.

Native

On compact layouts, tool calls and tool-call groups open a sheet instead of expanding, so they do not hold. Summary lines, todo cards, plan cards and show more expand inline.

The timeline is a LegendList in forward order: one data array of history rows followed by the live head, oldest first (strategy-native.tsx). LegendList keeps a row in place across a size change in the commit that makes it, so a hold needs no anchor neighbour, native child index or render window stretch. The inverted FlatList it replaced needed all three, and three commits per toggle; its applied commit took up to 3.5 s of JS on a long turn.

Who owns the offset

One owner keeps the scroll offset at any moment:

State	Owner
Before rows are placed	LegendList's initial scroll to the end. It keeps the rows hidden until they are measured.
Following the end	The end pin (native-end-pin.tsx), also for a bottom-edge hold.
Disclosure hold	LegendList's maintainVisibleContentPosition on the hold's anchor row, or the end pin for the last row's bottom.
User scroll	The finger. The controller detaches at drag start.
Detached	LegendList's maintainVisibleContentPosition on the first visible row.
Keyboard motion	Nobody. The keyboard translates the list with the composer and leaves the offset alone.

The end pin is a zero-height view at the bottom of the content and the content's first native child, with React Native's maintainVisibleContentPosition set to { minIndexForVisible: 0 }. The native correction runs on the UI thread around each mount, so a row that grows or lands at the end scrolls in the frame it lays out. The controller scrolls only for a viewport resize (the composer growing or shrinking) and an explicit jump, both through the native scrollToEnd.

Do not use LegendList's maintainScrollAtEnd instead. It scrolls from JS after the mount to the end its JS sizes predict: growth paints below the viewport for a frame, and the scroll lands short of the native end, which the controller reads as the user scrolling away.

The keyboard never changes the list's size, padding or offset. KeyboardTranslateView moves the list and the composer together on the UI thread, and the composer viewport clips the top of the list while the keyboard is open. Do not add a keyboard-sized inset to keep that content reachable: it can only commit after the motion, and while detached or holding nothing corrects for it, so every row jumps by the keyboard height after the keyboard settles.

The hold

holdRow(rowId, apply, triggerEdge) runs in the toggle's event:

1. Pick the anchor and detach the controller (holdForDisclosure). LegendList restores row tops only, so a top-edge hold anchors the toggled row and a bottom-edge hold anchors the row below it, whose top is the toggled row's bottom (disclosureAnchor). The pin goes away and LegendList's maintainVisibleContentPosition takes over, restoring only the anchor row (shouldRestorePosition). A bottom-edge hold while following skips this step: the end pin keeps the content end, and the row's bottom with it, in the frame the new height mounts.

   A bottom-edge hold on the last row, such as a prompt the agent has not answered yet, has no row below it: its bottom is the content end (the running indicator is the list footer, not a row). The hold mounts the end pin while detached, and apply runs a frame later. The pin anchors only once it is mounted, and a pin that mounts in the same commit as the new height anchors nothing. The pin's commit mounts before that frame's JS callbacks run, so apply's commit mounts with the pin already in place. The pin keeps the distance from the end, and each content size change clamps it to the scroll room left, so the hold re-sticks if the list was at its end when tapped or a collapse used up the room. The release tracks that distance instead of reading the offset: the new content size reaches JS before the pin's scroll does. A reply landing below the row ends the pin in the commit that mounts the reply, so the reply grows below the row and the trigger stays where it was. A reply that lands before apply runs moves the hold to the reply's row.

   Upstream LegendList anchors only rows from the first fully visible one down to the last fully visible one, and a size change with no data change keeps the first row in view whatever shouldRestorePosition says. A row cut off at the top would then let the row below it hold instead, and a bottom-edge anchor just under the viewport would not hold at all. The LegendList patch counts the rows cut off at the top, and the row just past the bottom, as in view and applies shouldRestorePosition to size changes too. It also drops LegendList's Android clamp prediction: the scroll view clamps after the adjustment (scroll view corrections), so the prediction moved a collapse near the end to the end.

2. Run apply.

3. Call the row's useSyncLayout trigger. The toggle changes the row from its own state, so LegendList's container does not re-render and would learn the new height from onLayout a task later, after the change painted. The trigger puts the measurement and the corrected positions in the toggle's own commit.

The hold ends two frames after the last item size change, since the list measures the toggled row and any rows it inserted over several frames (native-disclosure-hold.ts). The controller then re-sticks only if the list is within 1 px of its end, the same distance web resumes from.

User scroll

The controller detaches at onScrollBeginDrag, so lines that stream in during a drag grow below the rows under the finger. The detach reaches native a JS round trip after the drag begins, so for those frames the pin is still mounted. The scroll view subclasses skip the pin's correction while the user drags (see scroll view corrections). They skip only the pin's: in the detached state LegendList uses the same native correction, and a history page that lands mid-drag needs it. They key on the drag, not the touch, so a tap or long press while following keeps following.

Following resumes only for a gesture that ends within 1 px of the end, either when the finger lifts or when momentum stops. A release past the end counts: iOS bounces back to the end, and lines that land during the bounce must keep scrolling in. A release anywhere short of the end stays detached with the scroll-to-bottom pill, so the rows the user let go of never move.

Draw distance

drawDistance is 2000 px on each side of the viewport. A fling over rows that were never measured blanks the viewport until LegendList renders and measures them. Twelve flings over a chat with a 15,000 px turn expanded, Android emulator, dev build:

List	Blank viewport	Janky frames	p50 / p90 / p99
Inverted FlatList	1.3 to 1.7 s over 5 flings	10.8%	27 / 48 / 109 ms
LegendList, drawDistance 500	1.0 to 1.5 s per fling
LegendList, drawDistance 2000	none	1.7%	24 / 32 / 48 ms

With every turn collapsed, flinging from a cold open into history did not blank at any value from 500 to 2000, and jank followed host load (19 to 40 on 16 cores) rather than draw distance. Measure 1000 and 1500 on the expanded chat, on a host under load 10, before lowering it.

LegendList patch

patches/@legendapp+list+3.7.1.patch carries twelve changes for the timeline. Its header lists them by purpose, and legend-list #593 reports each upstream. Drop a hunk when the installed LegendList ships its fix.

Scroll view corrections

modules/paseo-scroll replaces React Native's scroll view on both platforms with a subclass: Android's PaseoScrollView and iOS's PaseoScrollViewComponentView. VisibleContentPositionClampTest covers Android; iOS has no native test harness.

Content clamp. A mount that shrinks the content while maintainVisibleContentPosition is set applies the shrink twice on both platforms: the scroll view clamps its offset to the new end during the mount, and React Native then adds the anchor's movement to the clamped offset (RN #58578, fix in PR #58695). A turn that folds while the list follows its end lands above the end. Android defers the clamp to the pre-draw pass, and iOS restores the pre-mount offset for the adjustment and clamps after it.

Removed anchor (iOS). A hold removes the end pin in the same mount that opens the tapped disclosure, and React Native 0.86 on iOS moves the offset by the removed view's frame. The iOS subclass keeps the offset. Android keeps a removed view's last frame, so it keeps the offset already. React Native 0.88 skips the adjustment for a removed anchor (PR #57294).

End pin during a drag. Both subclasses recognize the pin by its native ID, paseo-end-pin, and skip its correction while the user drags (user scroll). This one has no React Native counterpart; it stays while the timeline uses the pin.

Remove the content clamp and removed-anchor overrides once the installed React Native includes their fixes.