RFC: Anchor an arbitrary index and grow around it

[astronautfa]

We shipped a streaming AI chat on TanStack Virtual. We read the chat blog and started from the new toggles: anchorTo: 'end', followOnAppend, scrollEndThreshold. They solve the classic case well. Prepend stays stable. The tail follows only when you are already pinned.

But our chat is not tail anchored. When you send a message we pin your message to the top of the viewport. The answer then streams in below it. We hold your question in place until the turn settles, then we release. This is the ChatGPT and Claude behavior. The anchor is a chosen index near the bottom, not the end.

So we turned the new toggles off. We run anchorTo: 'start' with followOnAppend: false and we rebuilt the chat behavior on top. This RFC is what we had to build, and what the package could own instead.

What we wanted:
Pin index N to a fixed offset from the top. Let the last item grow below it. Issue no scroll compensation while it grows. Release the pin when streaming ends. Follow the tail only if the reader asked to.

What we had to build:
A growth reserve. We add a dynamic bottom pad as paddingEnd. It is one viewport tall at submit. As tokens arrive the content fills the reserve and the pad shrinks by the same amount. Total size stays constant, so virtual core issues no compensation of its own, and the anchored message does not move. This is the load bearing trick. It only works because we keep total size flat by hand.

An owned tween for the rise. We move the message to the top with our own rAF tween at 220ms. We tried scrollToIndex(index, { align: 'start', behavior: 'smooth' }). It degrades to an instant jump once the dynamic target falls under one viewport, so it slid halfway then snapped. We had to own the animation to stay smooth over a moving target.

Compensation before paint for shrink. When the loader row is removed at the first token, or an artifact shell collapses, the content below the viewport shrinks. The browser clamps scrollTop to the new smaller max, the pinned message visibly drops, and any later fix animates it back. That is the stream start jitter. We hold scrollTop in a layout effect that runs before paint to absorb it.

Intent rebuilt from deltas. stick to bottom is not a boolean for us. We model three mode to know why the viewport detached. Was it a user gesture, a resize, or content growth?

What the package could own:

1. Anchor any index, not only start or end. Something like anchor: { index, align, offset }. Pin a chosen row to a chosen offset and keep it stable while neighbors change. This is the one primitive that removes most of our code.
2. A built in growth reserve. Let the anchored item grow without changing total size, with the package managing the shrinking pad. Today we do this by hand through paddingEnd.
3. A consistent behavior argument. scrollToEnd accepts instant, scrollToIndex does not. And smooth on scrollToIndex degrades to a jump over a dynamic target. A real instant on both, and a smooth that holds over a moving target, would let us drop our tween.
4. Intent aware sticky. Expose the detach reason. gesture, resize, append, or programmatic. An onAnchorChange style callback beats a bare isAtEnd boolean. We would delete our delta tracking.
5. Compensate shrink before paint. When content below the anchor shrinks, hold the anchor rather than let the browser clamp and then re animate. This kills the stream start jitter at the source.

Summary:
The new toggles nailed the tail anchored case. The streaming case wants a movable anchor. Pin an index, reserve room, grow around it, release. If virtual core owned the anchor and the reserve, the rest of our machine would mostly go away.

[piecyk]

Thanks for the unusually thorough RFC, this is one of the clearest write-ups of the streaming‑chat scroll problem I've seen.

I took your use case and built a small reference example to pin down exactly what the package is missing vs. what's already possible. https://stackblitz.com/edit/vitejs-vite-tvutgddd

Two things worth checking against your mental model.

First: is this the behavior you're after?

There seem to be two distinct "keep the question up top" models, and they need very different things from the library:

• A — Immediate pin (what the RFC describes): on submit the question jumps to the top before the answer exists, and is held there while the answer streams into reserved space below. This is the one that needs the growth reserve — and the reserve is inseparable from a viewport of empty space under a short answer (it shrinks as tokens arrive; ChatGPT/Claude have it too).
• B — Stick‑on‑scroll: the question is a sticky header; the answer streams with the view following the bottom, and the question rises to the top and sticks as the answer grows past a viewport. No reserve, no reserved whitespace.

We found B is fully achievable today with no core changes, on existing primitives:

const virtualizer = useVirtualizer({
  // …
  anchorTo: 'end',        // follow the streamed answer; keeps prepend stable too
  followOnAppend: true,
  rangeExtractor: (range) => {
    // active question = last user message at/above the viewport top
    activeSticky.current =
      userIndexes.findLast((i) => range.startIndex >= i) ?? 0
    // keep it rendered even when scrolled out of range
    return [...new Set([activeSticky.current, ...defaultRangeExtractor(range)])]
      .sort((a, b) => a - b)
  },
})
// render the active question with `position: sticky; top: 0`

That already gives prepend stability (your point 1's common case), streaming follow, and sticky question headers — including "scroll past the current question and the previous one takes over."

So the question for you: does B cover your product, or do you specifically need A's immediate pin (question at the top before any answer text)? Because A is the only variant that actually needs your "growth reserve" / movable‑anchor primitive — and even then it scopes down to essentially one thing (a built‑in bottom reserve tied to a target index that shrinks as content fills it), not the full movable‑anchor system in the RFC.

Second: two gaps we hit building B that we'd like to fix regardless

1. directDomUpdates can't be used with sticky rows. Its DOM‑write pass writes top/transform to every measured element, so a position: sticky row gets overwritten. We'd like it to (a) leave consumer‑positioned rows alone, and (b) ideally own the sticky positioning and the "push the previous header up" handoff inside its existing scroll‑driven, re‑render‑free pass. That makes sticky headers smooth and free of per‑scroll React re‑renders (which is otherwise the only way to drive the push from userland).

2. Sticky handling is fiddly. The rangeExtractor + position: sticky + manual push math is a lot of consumer boilerplate. A small built‑in — e.g. a getStickyIndex(range) the virtualizer understands — would collapse this to a couple of lines and make keeping the header rendered/positioned the library's job.

Happy to contribute the example + these two improvements if the direction sounds right. Mostly want your read on A vs. B first, since it decides whether the growth reserve is worth adding at all.

[astronautfa]

Thanks for taking the time, and for the StackBlitz example.

We need A. On submit we move the question to the top right away, before any answer text exists, and hold it there while the response streams into reserved space below.

The reserve moves in both directions

One correction. The reserve does not only shrink as tokens arrive. It also grows. The loader row is removed at first token. An inline artifact shell collapses when its stream ends. Tool chrome appears and swaps. So the reserve absorbs size changes below the anchor in both directions during a single turn.

The primitive we want holds anchor index N at a fixed offset while the content below it resizes in both directions.

The anchor is any row that starts a turn

This is our biggest difference from B. The B example picks the last user message with userIndexes.findLast(...). Our anchor can be a marker, a fork or branch checkpoint, a join or handoff separator, or an assistant only turn with no user text.

The new Shadcn Message Scroller block landed the same idea. Its scrollAnchor is a per row flag and works on any row regardless of role. A user message, a marker component, and a handoff event can all anchor. After reading it we refactored our own code so anchoring runs through one predicate instead of a hardcoded last user message check. A non user anchor is now a one line change for us.

A sticky header is the wrong shape for us. Our anchor is a real row in the flow, held by the reserve. A floating sticky element would sit on top of the artifact and tool cards we render right under the question.

Embedded artifacts are what make the reserve hard

By artifacts we mean rich blocks like Claude Artifacts or ChatGPT Canvas. Claude puts those in a side panel. Ours render inline, embedded in the message flow, like ChatGPT.

These blocks stream and resize. A card starts near a 320px estimate, grows as content arrives, then settles to a smaller final size when the stream ends. All of that happens below the pinned question, during the pinned turn. We absorb it before paint by adjusting the reserve so the question never jumps. This is the fix for the stream start and artifact end jitter.

It is also why directDomUpdates does not work for us today. It writes top and transform to every measured element. That overwrites the positions of our artifact slots, the same way it overwrites a sticky row. So we run our own pin loop instead.

Scroll restoration of previous chats

TanStack Router provides this natively. Reopen a past thread in most chat apps and they land the scroller at the bottom. We wanted to restore the place the reader left.

On unmount we call takeSnapshot() and store the measured row sizes keyed by row key, plus the scroll position, in sessionStorage per thread. On the next mount we seed initialMeasurementsCache from that snapshot and set initialOffset to the saved position. For a fresh open with no saved position we land the last anchor at the top. The measurements matter. Without them the estimated sizes drift and the restore lands on the wrong row.

The awkward part is the handoff with the virtualizer. It reasserts initialOffset on element attach, after our own layout effects run. So we feed the exact destination through initialOffset every time and reconcile by hand.

What we would propose for the API

Each item below is something we already do by hand. A native version would let us delete most of our scroll layer.

A pinned anchor with a growth reserve

Today we set paddingEnd to a base value plus a dynamic spacer, run an animation frame loop that holds the last anchor row at a 16px offset, and recompute the spacer before paint whenever rows below resize.

A native anchor option would own all of that.

const virtualizer = useVirtualizer({
  // ...
  anchor: {
    index: anchorIndex, // the row to hold
    offset: 16,         // px from the viewport top
    reserve: true,      // reserve space below so growth and shrink never move it
  },
})

The virtualizer owns the reserve inside getTotalSize(), holds the row at the offset across resizes in both directions before paint, and releases when anchor is cleared. No consumer spacer math, no frame loop.

Anchor identity from a consumer predicate

Today we pick the active anchor with our own predicate and a backward walk from the viewport top, then feed that index into the pin and into the table of contents.

A predicate option would let the virtualizer find it.

useVirtualizer({
  isAnchor: (index) => rows[index].startsTurn,
})

// virtualizer.getActiveAnchorIndex() -> last anchor at or above the viewport top

The pin target and the active turn id then come from one source.

directDomUpdates that skips consumer positioned rows

Today we avoid directDomUpdates entirely because it writes to every measured element and overwrites our artifact slots.

A skip predicate would let the fast path leave those rows alone.

useVirtualizer({
  directDomUpdates: {
    skip: (index) => rows[index].selfPositioned,
  },
})

That keeps the re render free scroll path for normal rows and lets us drop our custom pin loop.

A serializable restore snapshot

Today we serialize takeSnapshot() into sessionStorage, then restore through initialMeasurementsCache and initialOffset, and reconcile because initialOffset is reasserted on element attach.

A single restore object would remove the reconcile step.

const state = virtualizer.getRestoreState()
// { measurements (keyed by item key), anchorIndex, offset } — serializable

// on the next mount:
useVirtualizer({ restoreState: state })

restoreState lands on the exact pixel offset and is not overwritten by a later reassert. It composes with router scroll restoration so the two do not fight.

Out of scope for us

We will leave the sticky specific items, like getStickyIndex, out of our ask. They fit the B shape, and we do not want the reserve work tied to them.

Happy to share a trimmed repro of the artifact resize case, if that helps scope the reserve.