The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
import type { ScrollBoxHandle } from '@hermes/ink'
import {
type RefObject,
useCallback,
useDeferredValue,
useEffect,
useLayoutEffect,
useRef,
useState,
useSyncExternalStore
} from 'react'
const ESTIMATE = 4
// Overscan was 40 (= viewport) which is way more than needed when heights
// are well-estimated. Cutting in half saves ~20 mounted items per scroll
// edge → smaller fiber tree → less buffer-compose work per frame. HN/CC
// dev (https://news.ycombinator.com/item?id=46699072) confirmed GC pressure
// from large JSX trees was their main perf issue post-rewrite.
const OVERSCAN = 20
// Hard cap on mounted items. Was 260; profiling showed ~23k live Yoga
// nodes during sustained PageUp catch-up (renderer p99=106ms). The
// viewport+2*overscan = 80 rows of needed coverage = ~25 items at avg 3
// rows/item, so 120 leaves >4× headroom and never blanks the viewport
// even when items are tiny.
const MAX_MOUNTED = 120
const COLD_START = 30
// Floor on unmeasured row height used when computing coverage — guarantees
// the mounted span physically reaches the viewport bottom regardless of how
// small items actually are (at the cost of over-mounting when items are
// larger; overscan absorbs that).
const PESSIMISTIC = 1
// Tightest safe scrollTop bin for the useSyncExternalStore snapshot. Small
// wheel ticks that don't cross a bin short-circuit React's commit entirely;
// Ink keeps painting via ScrollBox.forceRender + direct scrollTop reads.
// Half of OVERSCAN keeps ≥20 rows of cushion before the mounted range
// would actually need to shift.
const QUANTUM = OVERSCAN >> 1
// Renders to keep the mount range frozen after width change (heights scaled
// but not yet re-measured). Render #1 skips measurement so pre-resize Yoga
// doesn't poison the scaled cache; render #2's useLayoutEffect captures
// post-resize heights; render #3 recomputes range with accurate data.
const FREEZE_RENDERS = 2
// Cap on NEW items mounted per commit when scrolling fast. Without this,
// a single PageUp into unmeasured territory mounts ~190 rows with
// PESSIMISTIC=1 coverage — each row running marked lexer + syntax
// highlighting for ~3ms = ~600ms sync block. Sliding toward the target
// over several commits keeps per-commit mount cost bounded. Tightened
// from 25 → 12: each new item adds ~100 fibers / Yoga nodes, and a
// 25-item commit was the dominant contributor to the 100ms+ p99 frames.
const SLIDE_STEP = 12
const MAX_VIRTUAL_ITEM_HEIGHT = 100_000
const MAX_VIRTUAL_GEOMETRY = 1_000_000_000
const NOOP = () => {}
const validVirtualItemHeight = (value: number): boolean =>
Number.isFinite(value) && value > 0 && value <= MAX_VIRTUAL_ITEM_HEIGHT
const safeUnsignedGeometry = (value: number, fallback = 0): number =>
Number.isFinite(value) && value >= 0 && value <= MAX_VIRTUAL_GEOMETRY ? value : fallback
const safeSignedGeometry = (value: number, fallback = 0): number =>
Number.isFinite(value) && Math.abs(value) <= MAX_VIRTUAL_GEOMETRY ? value : fallback
export const pruneVirtualHeightCache = (cache: Map<string, number>, items: readonly { key: string }[]): void => {
const active = new Set(items.map(item => item.key))
for (const key of cache.keys()) {
if (!active.has(key) || !validVirtualItemHeight(cache.get(key)!)) {
cache.delete(key)
}
}
}
export const virtualHistorySnapshotKey = (s?: ScrollBoxHandle | null): string => {
if (!s) {
return 'none'
}
const target = safeUnsignedGeometry(safeUnsignedGeometry(s.getScrollTop()) + safeSignedGeometry(s.getPendingDelta()))
const bin = Math.floor(target / QUANTUM)
const viewportHeight = safeUnsignedGeometry(s.getViewportHeight())
return `${s.isSticky() ? ~bin : bin}:${viewportHeight}`
}
const upperBound = (arr: ArrayLike<number>, target: number, length = arr.length) => {
let lo = 0
let hi = length
while (lo < hi) {
const mid = (lo + hi) >> 1
arr[mid]! <= target ? (lo = mid + 1) : (hi = mid)
}
return lo
}
export const shouldSetVirtualClamp = ({
itemCount,
liveTailActive = false,
sticky,
viewportHeight
}: {
itemCount: number
liveTailActive?: boolean
sticky: boolean
viewportHeight: number
}) => itemCount > 0 && viewportHeight > 0 && !sticky && !liveTailActive
export const ensureVirtualItemHeight = (
heights: Map<string, number>,
key: string,
index: number,
estimate: number,
estimateHeight?: (index: number, key: string) => number
) => {
const cached = heights.get(key)
if (cached !== undefined && validVirtualItemHeight(cached)) {
return Math.floor(cached)
}
if (cached !== undefined) {
heights.delete(key)
}
const fallback = validVirtualItemHeight(estimate) ? Math.floor(estimate) : estimate === 0 ? 1 : ESTIMATE
const candidate = estimateHeight?.(index, key) ?? fallback
const seeded = validVirtualItemHeight(candidate) ? Math.floor(candidate) : candidate === 0 ? 1 : fallback
heights.set(key, seeded)
return seeded
}
export function useVirtualHistory(
scrollRef: RefObject<ScrollBoxHandle | null>,
items: readonly { key: string }[],
columns: number,
{
estimate = ESTIMATE,
estimateHeight,
generation = 0,
initialHeights,
liveTailActive = false,
onHeightsChange,
overscan = OVERSCAN,
maxMounted = MAX_MOUNTED,
coldStartCount = COLD_START,
nativeMode = false
}: VirtualHistoryOptions = {}
) {
const nodes = useRef(new Map<string, unknown>())
const heights = useRef(new Map(initialHeights))
const initialHeightsRef = useRef(initialHeights)
const refs = useRef(new Map<string, (el: unknown) => void>())
const measuredBottoms = useRef(new Map<string, number>())
const unmountViewport = useRef<{ sticky: boolean; top: number } | null>(null)
const onHeightsChangeRef = useRef(onHeightsChange)
// Bump whenever heightCache mutates so offsets rebuild on next read.
// Ref (not state) — checked during render phase, zero extra commits.
const offsetVersion = useRef(0)
// Cached offsets: reused Float64Array keyed on (itemCount, version). Clean
// renders reuse it, but a point-height invalidation still rebuilds the full
// prefix array; this is allocation reuse, not incremental prefix indexing.
const offsetsCache = useRef<{ arr: Float64Array; n: number; version: number }>({
arr: new Float64Array(0),
n: -1,
version: -1
})
const [hasScrollRef, setHasScrollRef] = useState(false)
// Height cache writes happen in layout effects; bump once so offsets and
// clamp bounds rebuild without waiting for the next scroll/input event.
const [measuredHeightVersion, bumpMeasuredHeightVersion] = useState(0)
const metrics = useRef({ sticky: true, top: 0, vp: 0 })
const lastScrollTopRef = useRef(0)
// Width change: scale cached heights by oldCols/newCols instead of clearing
// (clearing forces a pessimistic back-walk mounting ~190 rows at once, each
// a fresh marked.lexer + syntax highlight ≈ 3ms). Freeze the mount range
// for 2 renders so warm memos survive; skip one measurement pass so
// useLayoutEffect doesn't poison the scaled cache with pre-resize Yoga
// heights.
const prevColumns = useRef(columns)
const skipMeasurement = useRef(false)
const prevRange = useRef<null | readonly [number, number]>(null)
const freezeRenders = useRef(0)
const generationRef = useRef<number | string>(generation)
onHeightsChangeRef.current = onHeightsChange
if (generationRef.current !== generation) {
generationRef.current = generation
nodes.current.clear()
refs.current.clear()
measuredBottoms.current.clear()
unmountViewport.current = null
heights.current = new Map(initialHeights)
initialHeightsRef.current = initialHeights
prevRange.current = null
freezeRenders.current = 0
skipMeasurement.current = false
lastScrollTopRef.current = 0
offsetVersion.current++
}
if (initialHeightsRef.current !== initialHeights) {
initialHeightsRef.current = initialHeights
heights.current = new Map(initialHeights)
offsetVersion.current++
}
if (prevColumns.current !== columns && prevColumns.current > 0 && columns > 0) {
const ratio = prevColumns.current / columns
prevColumns.current = columns
for (const [k, h] of heights.current) {
const scaled = Math.round(h * ratio)
if (validVirtualItemHeight(scaled)) {
heights.current.set(k, scaled)
} else {
heights.current.delete(k)
}
}
offsetVersion.current++
skipMeasurement.current = true
freezeRenders.current = FREEZE_RENDERS
}
useLayoutEffect(() => {
setHasScrollRef(Boolean(scrollRef.current))
}, [scrollRef])
// Quantized snapshot: same-bin scrolls (most wheel ticks) produce the same
// key → React.Object.is short-circuits the commit entirely. The key includes
// sticky state, target scroll position, and viewport height so resize-only
// changes still recompute the mounted transcript window.
const subscribe = useCallback(
(cb: () => void) => (hasScrollRef ? scrollRef.current?.subscribe(cb) : null) ?? NOOP,
[hasScrollRef, scrollRef]
)
useSyncExternalStore(
subscribe,
() => virtualHistorySnapshotKey(scrollRef.current),
() => 'none'
)
useEffect(() => {
const keep = new Set(items.map(i => i.key))
let dirty = false
for (const k of heights.current.keys()) {
if (!keep.has(k)) {
heights.current.delete(k)
nodes.current.delete(k)
refs.current.delete(k)
measuredBottoms.current.delete(k)
dirty = true
}
}
if (dirty) {
offsetVersion.current++
}
}, [items])
// Offsets: Float64Array reused across renders, invalidated by offsetVersion
// bumps from heightCache writers (measureRef, resize-scale, GC). Binary
// search tolerates either monotone source, so no need to rebuild unless
// something changed.
const n = items.length
if (offsetsCache.current.version !== offsetVersion.current || offsetsCache.current.n !== n) {
const arr = offsetsCache.current.arr.length >= n + 1 ? offsetsCache.current.arr : new Float64Array(n + 1)
arr[0] = 0
for (let i = 0; i < n; i++) {
arr[i + 1] = arr[i]! + ensureVirtualItemHeight(heights.current, items[i]!.key, i, estimate, estimateHeight)
}
offsetsCache.current = { arr, n, version: offsetVersion.current }
}
const offsets = offsetsCache.current.arr
const total = offsets[n] ?? 0
const top = safeUnsignedGeometry(scrollRef.current?.getScrollTop() ?? 0)
const pendingDelta = safeSignedGeometry(scrollRef.current?.getPendingDelta() ?? 0)
const target = safeUnsignedGeometry(top + pendingDelta)
const vp = safeUnsignedGeometry(scrollRef.current?.getViewportHeight() ?? 0)
const sticky = scrollRef.current?.isSticky() ?? true
const recentManual = Date.now() - (scrollRef.current?.getLastManualScrollAt() ?? 0) < 1200
// During a freeze, drop the frozen range if items shrank past its start
// (/clear, compaction) — clamping would collapse to an empty mount and
// flash blank. Fall through to the normal path in that case.
const frozenRangeCandidate =
freezeRenders.current > 0 && prevRange.current && prevRange.current[0] < n
? ([prevRange.current[0], Math.min(prevRange.current[1], n)] as const)
: null
// Width grows can shrink wrapped rows enough that the old tail window no
// longer covers the viewport. In that case freezing preserves stale spacers
// and visually cuts off the last message, so recompute immediately.
const frozenRange = (() => {
if (!frozenRangeCandidate || vp <= 0) {
return frozenRangeCandidate
}
const visibleTop = sticky && !recentManual ? Math.max(0, total - vp) : target
const visibleBottom = visibleTop + vp
const rangeTop = offsets[frozenRangeCandidate[0]] ?? 0
const rangeBottom = offsets[frozenRangeCandidate[1]] ?? total
return rangeTop <= visibleTop && rangeBottom >= visibleBottom ? frozenRangeCandidate : null
})()
let start = 0
let end = n
if (nativeMode) {
// Native mode deliberately leaves the transcript in ordinary document
// flow. The terminal owns scrollback; there is no viewport window to
// virtualize or reconcile against.
start = 0
end = n
} else if (frozenRange) {
start = frozenRange[0]
end = Math.min(frozenRange[1], n)
} else if (n > 0) {
if (vp <= 0) {
start = Math.max(0, n - coldStartCount)
} else if (sticky && !recentManual) {
const budget = vp + overscan
start = n
while (start > 0 && total - offsets[start - 1]! < budget) {
start--
}
} else {
// User scrolled up. Span [committed..target] so every drain frame is
// covered. Claude-code caps the span at 3×viewport so pendingDelta
// growing unbounded (MX Master free-spin) doesn't blow the mount
// budget; the clamp (setClampBounds) shows edge-of-mounted content
// during catch-up.
const MAX_SPAN = vp * 3
const rawLo = Math.min(top, target)
const rawHi = Math.max(top, target)
const span = rawHi - rawLo
const clampedLo = span > MAX_SPAN ? (pendingDelta < 0 ? rawHi - MAX_SPAN : rawLo) : rawLo
const clampedHi = clampedLo + Math.min(span, MAX_SPAN)
const lo = Math.max(0, clampedLo - overscan)
const hi = clampedHi + vp + overscan
// Binary search — offsets is monotone. Linear walk was O(n) at n=10k+,
// ~2ms per render during scroll.
start = Math.max(0, Math.min(n - 1, upperBound(offsets, lo, n + 1) - 1))
end = Math.max(start + 1, Math.min(n, upperBound(offsets, hi, n + 1)))
}
}
if (!nativeMode && end - start > maxMounted) {
sticky ? (start = Math.max(0, end - maxMounted)) : (end = Math.min(n, start + maxMounted))
}
// Coverage guarantee: ensure sum(real or pessimistic heights) ≥
// viewportH + 2*overscan so the viewport is physically covered even when
// items are tiny. Pessimistic because uncached items use a floor of 1 —
// over-mounts when items are large, never leaves blank spacer showing.
if (!nativeMode && n > 0 && vp > 0 && !frozenRange) {
const needed = vp + 2 * overscan
let coverage = 0
for (let i = start; i < end; i++) {
coverage += ensureVirtualItemHeight(heights.current, items[i]!.key, i, PESSIMISTIC, estimateHeight)
}
if (sticky) {
const minStart = Math.max(0, end - maxMounted)
while (start > minStart && coverage < needed) {
start--
coverage += ensureVirtualItemHeight(heights.current, items[start]!.key, start, PESSIMISTIC, estimateHeight)
}
} else {
const maxEnd = Math.min(n, start + maxMounted)
while (end < maxEnd && coverage < needed) {
coverage += ensureVirtualItemHeight(heights.current, items[end]!.key, end, PESSIMISTIC, estimateHeight)
end++
}
}
}
// Slide cap: limit how many NEW items mount this commit. Gates on scroll
// VELOCITY (|scrollTop delta since last commit| + |pendingDelta| >
// 2×viewport — key-repeat PageUp moves ~viewport/2 per press). Covers
// both scrollBy (pendingDelta) and scrollTo (direct write). Normal single
// PageUp skips this; the clamp holds the viewport at the mounted edge
// during catch-up so there's no blank screen. Only caps range GROWTH;
// shrinking is unbounded.
if (!nativeMode && !frozenRange && prevRange.current && vp > 0) {
const velocity = Math.abs(top - lastScrollTopRef.current) + Math.abs(pendingDelta)
if (velocity > vp * 2) {
const [pS, pE] = prevRange.current
start = Math.max(start, pS - SLIDE_STEP)
end = Math.min(end, pE + SLIDE_STEP)
// A large jump past the capped end can invert (start > end); mount
// SLIDE_STEP items from the new start so the viewport isn't blank
// during catch-up.
if (start > end) {
end = Math.min(start + SLIDE_STEP, n)
}
}
}
lastScrollTopRef.current = top
if (freezeRenders.current > 0) {
freezeRenders.current--
} else {
prevRange.current = [start, end]
}
// Time-slice range growth via useDeferredValue. Urgent render keeps Ink
// painting with the OLD range (all memo hits, fast); deferred render
// transitions to the NEW range (fresh mounts: Md, syntax highlight) in a
// non-blocking background commit. The clamp (setClampBounds) pins the
// viewport to the mounted edge so there's no visual artifact from the
// deferred range lagging briefly. Only deferral range GROWTH — shrinking
// is cheap (unmount = remove fiber, no parse).
const dStart = useDeferredValue(start)
const dEnd = useDeferredValue(end)
let effStart = nativeMode ? 0 : start < dStart ? dStart : start
let effEnd = nativeMode ? n : end > dEnd ? dEnd : end
// Inverted range (large jump with deferred value lagging) or sticky snap
// (scrollToBottom needs the tail mounted NOW so maxScroll lands on content,
// not bottomSpacer) — skip deferral.
if (effStart > effEnd || sticky) {
effStart = start
effEnd = end
}
// Scrolling DOWN — bypass effEnd deferral so the tail mounts immediately.
// Without this, the clamp holds scrollTop short of the real bottom and
// the user feels "stuck before bottom". effStart stays deferred so scroll-
// UP keeps time-slicing (older messages parse on mount).
if (pendingDelta > 0) {
effEnd = end
}
// Final O(viewport) enforcement. Deferred+bypass combinations above can
// leak: during sustained PageUp, concurrent mode interleaves dStart updates
// with effEnd=end bypasses across commits and the effective window drifts
// wider than either bound alone. Trim the far edge by viewport position
// (not pendingDelta direction — that flips mid-settle under concurrent
// scheduling and yanks scrollTop).
if (!nativeMode && effEnd - effStart > maxMounted && vp > 0) {
const mid = (offsets[effStart]! + offsets[effEnd]!) / 2
if (top < mid) {
effEnd = effStart + maxMounted
} else {
effStart = effEnd - maxMounted
}
}
const measureRef = useCallback(
(key: string) => {
let fn = refs.current.get(key)
if (!fn) {
const refGeneration = generationRef.current
fn = (el: unknown) => {
if (refGeneration !== generationRef.current) {
return
}
if (el) {
nodes.current.set(key, el)
return
}
// A width-change render has already scaled the cache, but outgoing
// refs still point at Yoga from the previous layout. The render-phase
// skip flag remains set through mutation refs, so ignore that stale
// measurement and let the post-resize layout pass own correction.
if (skipMeasurement.current) {
nodes.current.delete(key)
measuredBottoms.current.delete(key)
return
}
// Measure-at-unmount: the yogaNode is still valid here (reconciler
// calls ref(null) before removeChild → freeRecursive), so we grab
// the final height before WASM release. Without this, items
// scrolled out during fast pan keep a stale estimate in heightCache
// and offset math drifts until the next mount/remount cycle.
const existing = nodes.current.get(key) as MeasuredNode | undefined
const h = Math.ceil(existing?.yogaNode?.getComputedHeight?.() ?? 0)
const previousHeight = heights.current.get(key)
if (validVirtualItemHeight(h) && previousHeight !== h) {
const s = scrollRef.current
const measuredBottom = measuredBottoms.current.get(key)
// All null refs in this commit share the viewport boundary captured
// before the first adjustment. Otherwise an earlier compensation
// can make an intersecting sibling look wholly above later in the
// same unmount batch.
const viewport = (unmountViewport.current ??= {
sticky: s?.isSticky() ?? true,
top: safeUnsignedGeometry(s?.getScrollTop() ?? 0)
})
if (
s &&
previousHeight !== undefined &&
measuredBottom !== undefined &&
measuredBottom <= viewport.top &&
!viewport.sticky
) {
s.adjustScrollTop(h - previousHeight)
}
heights.current.set(key, h)
offsetVersion.current++
onHeightsChangeRef.current?.(heights.current)
}
nodes.current.delete(key)
measuredBottoms.current.delete(key)
}
refs.current.set(key, fn)
}
return fn
},
[scrollRef]
)
useLayoutEffect(() => {
unmountViewport.current = null
const s = scrollRef.current
let dirty = false
let heightDirty = false
let anchorDelta = 0
if (nativeMode) {
return
}
// Give the renderer the mounted-row coverage for passive scroll clamping.
// Clamp MUST use the EFFECTIVE (deferred) range, not the immediate one.
// During fast scroll, immediate [start,end] may already cover the new
// scrollTop position, but children still render at the deferred range.
// If clamp used immediate bounds, render-node-to-output's drain-gate
// would drain past the deferred children's span → viewport lands in
// spacer → white flash.
if (s && shouldSetVirtualClamp({ itemCount: n, liveTailActive, sticky, viewportHeight: vp })) {
const effTopSpacer = offsets[effStart] ?? 0
const effBottom = offsets[effEnd] ?? total
const clampMin = effStart === 0 ? 0 : effTopSpacer
// Preserve the intentional open tail: when the mounted range reaches
// the final row, Yoga may already know about growth that the measured
// height cache has not reconciled yet. A finite estimated clamp would
// trap a manual, non-sticky viewport above that newly grown tail.
const clampMax = effEnd === n ? Number.POSITIVE_INFINITY : Math.max(effTopSpacer, effBottom - vp)
if (
safeUnsignedGeometry(clampMin, -1) >= 0 &&
(clampMax === Number.POSITIVE_INFINITY || safeUnsignedGeometry(clampMax, -1) >= clampMin)
) {
s.setClampBounds(clampMin, clampMax)
} else {
s.setClampBounds(undefined, undefined)
}
} else {
s?.setClampBounds(undefined, undefined)
}
// Stable metadata for measure-at-unmount. Ref(null) runs before the next
// commit's layout effects, so an outgoing row sees the bottom recorded by
// the last committed mounted range. This stays O(mounted), not O(history).
for (let i = effStart; i < effEnd; i++) {
const k = items[i]?.key
if (k) {
const bottom = offsets[i + 1] ?? 0
if (safeUnsignedGeometry(bottom, -1) >= 0) {
measuredBottoms.current.set(k, bottom)
}
}
}
if (skipMeasurement.current) {
skipMeasurement.current = false
bumpMeasuredHeightVersion(n => n + 1)
} else {
for (let i = effStart; i < effEnd; i++) {
const k = items[i]?.key
if (!k) {
continue
}
const h = Math.ceil((nodes.current.get(k) as MeasuredNode | undefined)?.yogaNode?.getComputedHeight?.() ?? 0)
const previousHeight = heights.current.get(k)
if (validVirtualItemHeight(h) && previousHeight !== h) {
// Keep the same content at the same screen row when estimates above
// the committed viewport converge. Rows intersecting or below the
// viewport intentionally retain the current scrollTop.
if (previousHeight !== undefined && (offsets[i + 1] ?? 0) <= top) {
anchorDelta += h - previousHeight
}
heights.current.set(k, h)
dirty = true
heightDirty = true
}
}
}
// Sticky/live-tail positioning is owned by ScrollBox's bottom-follow
// logic. Manual viewports need an additive adjustment that leaves any
// pending input intact; scrollTo would clear that intent and other state.
if (s && anchorDelta !== 0 && !s.isSticky()) {
s.adjustScrollTop(anchorDelta)
}
if (s) {
const next = {
sticky: s.isSticky(),
top: safeUnsignedGeometry(s.getScrollTop() + safeSignedGeometry(s.getPendingDelta())),
vp: safeUnsignedGeometry(s.getViewportHeight())
}
if (
next.sticky !== metrics.current.sticky ||
next.top !== metrics.current.top ||
next.vp !== metrics.current.vp
) {
metrics.current = next
dirty = true
}
}
if (dirty) {
offsetVersion.current++
onHeightsChangeRef.current?.(heights.current)
}
if (heightDirty) {
bumpMeasuredHeightVersion(n => n + 1)
}
}, [
effEnd,
effStart,
items,
liveTailActive,
measuredHeightVersion,
n,
nativeMode,
offsets,
scrollRef,
sticky,
top,
total,
vp
])
return {
bottomSpacer: Math.max(0, total - (offsets[effEnd] ?? total)),
end: effEnd,
measureRef,
offsets,
start: effStart,
topSpacer: offsets[effStart] ?? 0
}
}
interface MeasuredNode {
yogaNode?: { getComputedHeight?: () => number } | null
}
interface VirtualHistoryOptions {
coldStartCount?: number
estimate?: number
estimateHeight?: (index: number, key: string) => number
generation?: number | string
initialHeights?: ReadonlyMap<string, number>
liveTailActive?: boolean
maxMounted?: number
onHeightsChange?: (heights: ReadonlyMap<string, number>) => void
overscan?: number
nativeMode?: boolean
}