@dxos/react-ui-feed 0.11.1

package/src/hooks/follow.ts

@@ -0,0 +1,241 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/**
+ * Speeds are expressed in **rows**, not pixels: a feed of tall messages and one of short replies
+ * should travel at the same perceived rate, and only a row-relative unit gives that.
+ */
+export type FollowOptions = {
+  /** Ceiling on travel speed, rows/s. */
+  maxSpeed?: number;
+  /** Rate the speed ramps up, rows/s². */
+  acceleration?: number;
+  /** Rate the speed sheds on approach, rows/s². Lower than `acceleration` gives a longer landing. */
+  deceleration?: number;
+  /** Height of a row in px, sampled each frame so a measured list can refine it. */
+  rowHeight?: () => number;
+  /** Empty space reserved below the last row, which the follow must stop short of. */
+  trailing?: () => number;
+};
+
+const DEFAULT_MAX_SPEED = 2;
+const DEFAULT_ACCELERATION = 12;
+const DEFAULT_DECELERATION = 6;
+/**
+ * Gentler than the ramp up, and deliberately so.
+ *
+ * Braking distance is `v²/2d`, so matching the two rates sheds full speed in three rows — a travel
+ * of any length then cruises to within a few rows of the target and stops, which reads as an abrupt
+ * halt however correct the curve is. At a third of the acceleration the landing occupies nine rows
+ * and a second and a half, which is long enough to see.
+ */
+const DEFAULT_ROW_HEIGHT = 120;
+
+/** Within this distance the follow has arrived; below it the animation would only jitter. */
+const ARRIVED = 0.5;
+
+/** The physics runs in pixels; rows are converted at the boundary by {@link ScrollFollower}. */
+export type VelocityStep = {
+  /** Current speed, px/s. */
+  velocity: number;
+  /** Remaining distance to the target, px. */
+  distance: number;
+  /** Elapsed time since the last step, seconds. */
+  dt: number;
+  /** Ceiling, px/s. */
+  maxSpeed: number;
+  /** Ramp-up rate, px/s². */
+  acceleration: number;
+  /** Approach rate, px/s². Defaults to `acceleration`. */
+  deceleration?: number;
+};
+
+/**
+ * Speed for the next frame of a follow.
+ *
+ * Ramps up to `maxSpeed` and back down so the travel starts and ends gently rather than jumping.
+ * The cap is whichever is lower: the ceiling, or the speed from which the remaining distance can
+ * still be shed at `acceleration` (`v = sqrt(2·a·d)`) — that second term is what turns the arrival
+ * into a deceleration instead of a stop, and what keeps a growing target at cruise speed.
+ *
+ * Acceleration is rate-limited so a start is gradual; **deceleration is not**, because the braking
+ * curve is already a smooth ramp to zero and easing onto it instead leaves the speed above the
+ * curve for the whole approach — the follow then runs out of distance while still moving and the
+ * arrival reads as a stop rather than a landing.
+ */
+export const stepVelocity = ({
+  velocity,
+  distance,
+  dt,
+  maxSpeed,
+  acceleration,
+  deceleration = acceleration,
+}: VelocityStep): number => {
+  const braking = Math.sqrt(2 * deceleration * Math.max(distance, 0));
+  const desired = Math.min(maxSpeed, braking);
+  return velocity < desired ? Math.min(desired, velocity + acceleration * dt) : desired;
+};
+
+/**
+ * **Not wired into `MessageList` at present.** The placement engine follows the tail by holding an
+ * intent and correcting the offset, which arrives instantly; this class is the animated travel the
+ * old engine used, kept with its tests because the glide is worth having back and nothing about it
+ * was wrong. Wiring it is a decision about feel, not a repair.
+ */
+/**
+ * Keeps an element scrolled to its bottom while its content grows.
+ *
+ * Native `scrollTo({ behavior: 'smooth' })` restarts its easing on every call, so a target that
+ * moves every chunk never leaves the start of the curve — the motion reads as a stutter. This
+ * carries velocity across frames instead: it accelerates as a stream begins, cruises while content
+ * keeps arriving, and decelerates onto the tail when it stops.
+ *
+ * `@dxos/ui-editor`'s `createCrawler` follows a streaming CodeMirror document the same way, with a
+ * critically-damped spring. The two are deliberately separate: that one is bound to `view.scrollDOM`
+ * and driven by editor effects, where a feed owns its own scroll container. The models differ in
+ * feel — a spring's speed falls off with distance, where this holds a ceiling and brakes onto the
+ * target, which keeps a fast stream at a constant rate rather than an ever-widening lag.
+ */
+export class ScrollFollower {
+  readonly #maxSpeed: number;
+  readonly #acceleration: number;
+  readonly #deceleration: number;
+  readonly #rowHeight: () => number;
+  readonly #trailing: () => number;
+
+  #frame: number | undefined;
+  #velocity = 0;
+  #timestamp = 0;
+  #braking = false;
+
+  constructor(
+    private readonly _element: HTMLElement,
+    {
+      maxSpeed = DEFAULT_MAX_SPEED,
+      acceleration = DEFAULT_ACCELERATION,
+      deceleration = DEFAULT_DECELERATION,
+      rowHeight = () => DEFAULT_ROW_HEIGHT,
+      trailing = () => 0,
+    }: FollowOptions = {},
+  ) {
+    this.#maxSpeed = maxSpeed;
+    this.#acceleration = acceleration;
+    this.#deceleration = deceleration;
+    this.#rowHeight = rowHeight;
+    this.#trailing = trailing;
+  }
+
+  /**
+   * The bottom of the last row, which is not the bottom of the document.
+   *
+   * A feed may reserve empty space below its last row so that row can be brought to the top of the
+   * viewport. That space is somewhere the reader may go and nowhere the follow should: chasing the
+   * element's own maximum walks the feed off the end of the conversation and keeps going.
+   */
+  get #bottom(): number {
+    return this._element.scrollHeight - this.#trailing() - this._element.clientHeight;
+  }
+
+  get running(): boolean {
+    return this.#frame !== undefined;
+  }
+
+  /** Current speed, rows/s. Exposed so a harness can show the ramp. */
+  get velocity(): number {
+    return this.#velocity / Math.max(this.#rowHeight(), 1);
+  }
+
+  /** Starts (or continues) travelling towards the bottom. Safe to call on every content change. */
+  start(): void {
+    this.#braking = false;
+    if (this.#frame !== undefined) {
+      return;
+    }
+
+    this.#timestamp = performance.now();
+    this.#frame = requestAnimationFrame(this.#tick);
+  }
+
+  /**
+   * Coasts to a halt, shedding speed at `deceleration` — what a stream ending or a stop control
+   * means. Cutting the animation instead would halt mid-glide, which is the one motion the reader
+   * cannot have caused and so reads as a fault.
+   */
+  stop(): void {
+    if (this.#frame === undefined) {
+      this.#velocity = 0;
+      return;
+    }
+
+    this.#braking = true;
+  }
+
+  /**
+   * Halts immediately, discarding the velocity — the reader has taken over, or the list is going
+   * away. Coasting here would fight a hand already on the scrollbar.
+   */
+  cancel(): void {
+    if (this.#frame !== undefined) {
+      cancelAnimationFrame(this.#frame);
+      this.#frame = undefined;
+    }
+    this.#braking = false;
+    this.#velocity = 0;
+  }
+
+  /** Jumps to the bottom with no animation. */
+  jump(): void {
+    this.cancel();
+    this._element.scrollTop = Math.max(0, this.#bottom);
+  }
+
+  readonly #tick = (timestamp: number): void => {
+    // Clamped because a backgrounded tab resumes with a large gap, which would otherwise apply one
+    // enormous step and teleport the viewport.
+    const dt = Math.min((timestamp - this.#timestamp) / 1_000, 0.05);
+    this.#timestamp = timestamp;
+
+    const target = Math.max(0, this.#bottom);
+    const distance = target - this._element.scrollTop;
+
+    // Coasting: the target no longer matters, only shedding what speed is left. Bounded by the
+    // bottom so a stop late in a travel still cannot run past it.
+    if (this.#braking) {
+      const rowHeight = Math.max(this.#rowHeight(), 1);
+      this.#velocity = Math.max(0, this.#velocity - this.#deceleration * rowHeight * dt);
+      if (this.#velocity <= 0 || distance <= ARRIVED) {
+        this.#frame = undefined;
+        this.#velocity = 0;
+        this.#braking = false;
+        return;
+      }
+
+      this._element.scrollTop = Math.min(target, this._element.scrollTop + this.#velocity * dt);
+      this.#frame = requestAnimationFrame(this.#tick);
+      return;
+    }
+
+    if (distance <= ARRIVED) {
+      this._element.scrollTop = target;
+      this.#frame = undefined;
+      this.#velocity = 0;
+      return;
+    }
+
+    // Rows are converted to pixels every frame rather than once, so a list whose measured rows grow
+    // (a streaming message) travels at the same rate in rows throughout.
+    const rowHeight = Math.max(this.#rowHeight(), 1);
+    this.#velocity = stepVelocity({
+      velocity: this.#velocity,
+      distance,
+      dt,
+      maxSpeed: this.#maxSpeed * rowHeight,
+      acceleration: this.#acceleration * rowHeight,
+      deceleration: this.#deceleration * rowHeight,
+    });
+
+    this._element.scrollTop = Math.min(target, this._element.scrollTop + this.#velocity * dt);
+    this.#frame = requestAnimationFrame(this.#tick);
+  };
+}

package/src/hooks/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './follow';
+export * from './useDecorations';
+export * from './useFeedNavigation';
+export * from './useFollow';
+export * from './useItemSelection';

package/src/hooks/useDecorations.tsx

@@ -0,0 +1,54 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type PropsWithChildren, createContext, useContext, useMemo } from 'react';
+
+/**
+ * A range of one item's rendered text that some producer wants painted (SPEC: Decoration).
+ *
+ * Search is ONE producer — mentions, lint results and diff spans are others — which is why this is
+ * not called a hit: the item painting the range does not care where it came from, and the list does
+ * not know it exists at all.
+ */
+export type Decoration = {
+  /** Item (message) id. */
+  id: string;
+  range: { offset: number; length: number };
+  /** Producer tag: 'search' | 'mention' | ... */
+  kind: string;
+};
+
+const DecorationsContext = createContext<ReadonlyMap<string, readonly Decoration[]>>(new Map());
+
+export type DecorationsProviderProps = PropsWithChildren<{
+  decorations?: readonly Decoration[];
+}>;
+
+/**
+ * THE PATTERN for cross-cutting per-item data (SPEC §Aspects), not a feed feature: a provider at
+ * the host carries what producers made, and an item asks for its own by id. The list neither knows
+ * nor routes — `hits` left its API entirely. Grouped once per change rather than filtered per item,
+ * so a long feed stays O(decorations).
+ */
+export const DecorationsProvider = ({ decorations, children }: DecorationsProviderProps) => {
+  const byId = useMemo(() => {
+    const map = new Map<string, Decoration[]>();
+    for (const decoration of decorations ?? []) {
+      const list = map.get(decoration.id) ?? [];
+      list.push(decoration);
+      map.set(decoration.id, list);
+    }
+
+    return map;
+  }, [decorations]);
+
+  return <DecorationsContext.Provider value={byId}>{children}</DecorationsContext.Provider>;
+};
+
+const NONE: readonly Decoration[] = [];
+
+/** An item's own decorations. Items work without a provider — they are simply undecorated. */
+export const useDecorations = (id: string): readonly Decoration[] => {
+  return useContext(DecorationsContext).get(id) ?? NONE;
+};

package/src/hooks/useFeedNavigation.ts

@@ -0,0 +1,90 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type RefObject, useCallback } from 'react';
+
+import { type Stop } from '../model';
+import { type WindowController } from '../virtualizer';
+
+export type UseFeedNavigationOptions = {
+  controller: RefObject<WindowController | null>;
+  /** The stops policy's current answer; asked per press, so a policy change needs no rewiring. */
+  stops: () => readonly Stop[];
+  /** The row containing the scroll offset — the cursor, derived and never set beside the scroll. */
+  current: () => number;
+  count: () => number;
+  /** Align the last stop to the end unless space is reserved past it (the reserve is scrollable). */
+  scrollPastEnd?: boolean;
+  /**
+   * Told before every jump, with the target index — the follow's `onNavigate` goes here. Without
+   * it a navigation races the follow's correction effect, which runs before the jump's scroll
+   * event can withdraw the intent and snaps the reader straight back to the tail they just left.
+   * The follow may move the view only while content is arriving AND the reader has pinned
+   * themselves to the bottom; navigating into the feed un-pins by definition.
+   */
+  onNavigate?: (index: number) => void;
+};
+
+export type FeedNavigation = {
+  /** Move by `delta` stops. Every press travels: see below. */
+  step: (delta: number) => void;
+  /** Jump to a stop (or a raw index), aligning the last row to the end where that is what it means. */
+  jumpTo: (index: number, behavior?: ScrollBehavior) => void;
+  first: () => void;
+  last: () => void;
+};
+
+/**
+ * The one navigation seam (SPEC: useFeedNavigation): toolbar buttons, arrow keys, the outline rail
+ * and the minimap all call this, so they cannot disagree about what a step is.
+ *
+ * Stepping is from the row containing the scroll offset. The stop above it begins strictly higher
+ * and the stop below strictly lower, so every press moves the viewport — an index compared against
+ * a position cannot promise that while positions are still being measured. Steps glide (corrections
+ * move the window, not the scroll, so nothing cancels the animation); far jumps are instant, since
+ * a glide across unmounted rows is a journey over a blank screen.
+ *
+ * Distinct from react-ui-list's `useListNavigation`, which is focus traversal over fully-mounted
+ * rows — a different problem in the same naming family.
+ */
+export const useFeedNavigation = ({
+  controller,
+  stops,
+  current,
+  count,
+  scrollPastEnd,
+  onNavigate,
+}: UseFeedNavigationOptions): FeedNavigation => {
+  const jumpTo = useCallback(
+    (index: number, behavior: ScrollBehavior = 'auto') => {
+      onNavigate?.(index);
+      const align = !scrollPastEnd && index >= count() - 1 ? 'end' : 'start';
+      controller.current?.scrollToIndex(index, align, behavior);
+    },
+    [controller, count, scrollPastEnd, onNavigate],
+  );
+
+  const step = useCallback(
+    (delta: number) => {
+      const all = stops();
+      if (!all.length) {
+        return;
+      }
+
+      const at = current();
+      const next =
+        delta > 0
+          ? (all.find(({ index }) => index > at) ?? all[all.length - 1])
+          : ([...all].reverse().find(({ index }) => index < at) ?? all[0]);
+
+      jumpTo(next.index, 'smooth');
+    },
+    [stops, current, jumpTo],
+  );
+
+  const first = useCallback(() => jumpTo(0), [jumpTo]);
+  const last = useCallback(() => jumpTo(count() - 1), [jumpTo, count]);
+
+  return { step, jumpTo, first, last };
+};

package/src/hooks/useFollow.ts

@@ -0,0 +1,258 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type RefObject, useCallback, useLayoutEffect, useMemo, useRef } from 'react';
+
+import { type Placement } from '../virtualizer/placement';
+import { ScrollFollower } from './follow';
+
+/** Distance from the end within which the reader counts as being at it. */
+const STICKY_THRESHOLD = 32;
+
+/** How long after a gesture a scroll is still attributable to the reader. */
+const GESTURE_WINDOW = 300;
+
+export type FollowHandle = {
+  /**
+   * A navigation is the reader answering "do you want the tail?" — and it must answer *before* the
+   * scroll moves. The intent is otherwise withdrawn by the scroll event the jump raises, which is
+   * asynchronous: the correction effect can run in between, still believe the reader is following,
+   * and snap them straight back to the tail they just left. Found by the outline rail — a click
+   * near the top of a sticky feed moved the list a few pixels and no further.
+   */
+  onNavigate: (index: number) => void;
+};
+
+export type UseFollowOptions = {
+  scrollerRef: RefObject<HTMLElement | null>;
+  /** The placement whose `endOffset` is the tail's resting place. */
+  placement: Placement;
+  /** Total content extent — the correction re-runs when it changes, which is how growth is noticed. */
+  extent: number;
+  count: number;
+  axis?: 'block' | 'inline';
+  /** Empty extent after the last row; the end the follow rests at is before it. */
+  reserve?: number;
+  /** The standing intent: off means this hook does nothing at all. */
+  enabled?: boolean;
+  /**
+   * Travel to a moved tail instead of teleporting (DECIDED: default on).
+   *
+   * The glide only covers gaps up to a viewport: beyond that the reader could not have followed the
+   * motion anyway, and the travel would cross rows whose extents are still estimates.
+   */
+  glide?: boolean;
+};
+
+/**
+ * The sticky tail as an intent (SPEC: useFollow) — a policy over the window, not part of it.
+ *
+ * Withdrawn by one thing only: a scroll that moves *backwards*. That is the reader; a correction
+ * never moves the offset back, it moves the end away. Re-deriving the intent from proximity on
+ * every commit cannot survive its own corrections — measuring the tail grows the document under a
+ * reader who has not moved, the gap opens past any threshold worth having, and the follow reads
+ * that as the reader leaving and disengages for good (`bridge/Tail`, the second defect).
+ *
+ * Reusable for any streaming container — transcripts, logs — because nothing here knows about
+ * messages: it needs a scroller, a placement, and the two numbers that say the content grew.
+ */
+export const useFollow = ({
+  scrollerRef,
+  placement,
+  extent,
+  count,
+  axis = 'block',
+  reserve = 0,
+  enabled,
+  glide = true,
+}: UseFollowOptions): FollowHandle => {
+  const following = useRef(!!enabled);
+  const wasEnabled = useRef(enabled);
+  if (wasEnabled.current !== enabled) {
+    wasEnabled.current = enabled;
+    following.current = !!enabled;
+  }
+
+  /**
+   * Where the reader has to be for the last row's rendered edge to rest on the viewport's.
+   *
+   * From the row's own rectangle when it is mounted, and from the arithmetic only when it is not:
+   * measured extents are rounded to integers and rendered rows are fractional, so over a mounted
+   * window the sum drifts from the layout by tens of pixels — an "arrived" that the reader can see
+   * is short. The rect already includes the window's transform, so the delta is exact.
+   */
+  const endTarget = useCallback(() => {
+    const scroller = scrollerRef.current;
+    if (!scroller) {
+      return 0;
+    }
+
+    const last = scroller.querySelector<HTMLElement>(`[data-index="${count - 1}"]`);
+    if (last) {
+      const current = axis === 'block' ? scroller.scrollTop : scroller.scrollLeft;
+      const delta =
+        axis === 'block'
+          ? last.getBoundingClientRect().bottom - scroller.getBoundingClientRect().bottom
+          : last.getBoundingClientRect().right - scroller.getBoundingClientRect().right;
+      return Math.max(0, Math.round(current + delta));
+    }
+
+    return placement.endOffset();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [count, axis, placement, scrollerRef.current]);
+
+  // The glide, built once per scroller. Speeds are in rows, so it asks the placement for a live
+  // median of what is mounted rather than being handed a constant.
+  const follower = useMemo(() => {
+    const scroller = scrollerRef.current;
+    if (!scroller || axis !== 'block') {
+      return undefined;
+    }
+
+    return new ScrollFollower(scroller, {
+      // Faster than the class's defaults, which were tuned for a single arrival: a streaming answer
+      // grows at hundreds of px/s, and a follow that cannot outrun the growth reads as falling
+      // behind for the whole turn. The ramp is what keeps this from feeling like a snap.
+      maxSpeed: 8,
+      acceleration: 32,
+      deceleration: 10,
+      // The follower's target is DOM-derived (scrollHeight - trailing - viewport); the authoritative
+      // end is the placement's (the last row's own edge, which the document disagrees with by the
+      // drift while estimates are being replaced). Expressing the placement's end *as* a trailing
+      // makes the two the same number.
+      trailing: () => scroller.scrollHeight - scroller.clientHeight - endTarget(),
+      rowHeight: () => {
+        const { first, last } = placement.layout();
+        const sizes = [];
+        for (let index = first; index <= last; index++) {
+          sizes.push(placement.extentOf(index));
+        }
+
+        sizes.sort((a, b) => a - b);
+        const median = sizes.length ? sizes[Math.floor(sizes.length / 2)] : 100;
+        return Math.min(median, scroller.clientHeight || median);
+      },
+    });
+    // The scroller element is stable for the life of the binding; reserve is read through the closure.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [scrollerRef.current, axis, placement, endTarget]);
+  useLayoutEffect(() => () => follower?.cancel(), [follower]);
+
+  // The intent, read from gestures. Own listener and own last-offset, deliberately: the window's
+  // scroll handler updates `placement.scroll` before this runs, so comparing against it would read
+  // every scroll as stationary.
+  // Why a backwards scroll alone cannot be the withdrawal: the machinery scrolls backwards too. A
+  // shrinking turn makes the browser clamp the offset by itself; a correction can move up; and none
+  // of it is the reader. Direction plus pre-announcement was tried and kept dying in races — this
+  // is the old engine's proven rule instead: the follow writes `scrollTop`, it does not turn wheels
+  // or press keys, so a scroll counts as the reader's only when a gesture preceded it. Returning to
+  // the tail, by any means, opts back in.
+  const lastOffset = useRef(0);
+  const gestureAt = useRef(0);
+  useLayoutEffect(() => {
+    const scroller = scrollerRef.current;
+    if (!scroller || !enabled) {
+      return;
+    }
+
+    const onGesture = () => {
+      gestureAt.current = performance.now();
+    };
+
+    const onScroll = () => {
+      const current = axis === 'block' ? scroller.scrollTop : scroller.scrollLeft;
+      const viewport = axis === 'block' ? scroller.clientHeight : scroller.clientWidth;
+      const total = axis === 'block' ? scroller.scrollHeight : scroller.scrollWidth;
+      const back = current < lastOffset.current - 1;
+      lastOffset.current = current;
+      if (total - reserve - current - viewport <= STICKY_THRESHOLD) {
+        following.current = true;
+      } else if (back && performance.now() - gestureAt.current < GESTURE_WINDOW) {
+        following.current = false;
+        follower?.cancel();
+      }
+    };
+
+    scroller.addEventListener('scroll', onScroll, { passive: true });
+    // Every way a reader can move a scroll container by hand: the wheel, a touch drag, the
+    // keyboard, and a pointer on the scrollbar itself.
+    for (const event of ['wheel', 'touchmove', 'keydown', 'pointerdown'] as const) {
+      scroller.addEventListener(event, onGesture, { passive: true });
+    }
+
+    return () => {
+      scroller.removeEventListener('scroll', onScroll);
+      for (const event of ['wheel', 'touchmove', 'keydown', 'pointerdown'] as const) {
+        scroller.removeEventListener(event, onGesture);
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [scrollerRef.current, enabled, axis, reserve, follower]);
+
+  // The correction. Following is a navigation, not a correction in the §7 sense: the content the
+  // reader is pinned to has moved, so the scroll has to as well.
+  //
+  // Through `endOffset` rather than a jump: a jump re-bases the model on a sum of estimates, and
+  // this effect runs again every time the document's extent changes — so each answer mounted rows
+  // whose measurement changed the sum the next answer was drawn from. That recurs rather than
+  // converging, and React ends it by exceeding the update limit. Keyed on the extent as well as the
+  // count: measuring the rows a scroll reveals moves the end, so a tail pinned once drifts off it
+  // as the estimates are replaced.
+  // Whether the feed has arrived at its tail once. Opening a populated feed is not motion to
+  // follow — the reader was not watching the travel, so it arrives; the glide is for content
+  // arriving at a tail they are looking at.
+  const positioned = useRef(false);
+
+  useLayoutEffect(() => {
+    const scroller = scrollerRef.current;
+    if (!enabled || !following.current || !count || !scroller) {
+      return;
+    }
+
+    const target = endTarget();
+    const current = axis === 'block' ? scroller.scrollTop : scroller.scrollLeft;
+    const gap = target - current;
+    if (Math.abs(gap) <= 1) {
+      positioned.current = true;
+      return;
+    }
+
+    const viewport = axis === 'block' ? scroller.clientHeight : scroller.clientWidth;
+    if (positioned.current && glide && follower && gap > 0 && gap <= viewport) {
+      // The follower recomputes its target every frame, so content arriving faster than the travel
+      // keeps the target ahead; when the arrivals stop, the travel lands by decelerating.
+      follower.start();
+      return;
+    }
+
+    // A far tail, a backwards correction, or no glide: arrive rather than travel. Written directly,
+    // never followed by an invalidate — the write raises a scroll event, which re-renders, which
+    // changes the extent this effect watches; invalidating here as well is a loop, and React says so.
+    follower?.cancel();
+    placement.scrollTo(target);
+    // Pre-announced, so the write's own scroll event cannot read as a gesture: a correction can
+    // move the offset *backwards* (an over-estimated tail shrinking), and the intent listener would
+    // otherwise take that for the reader leaving and withdraw the follow for good.
+    lastOffset.current = target;
+    if (axis === 'block') {
+      scroller.scrollTop = target;
+    } else {
+      scroller.scrollLeft = target;
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, count, extent, placement, axis, glide, follower, endTarget, scrollerRef.current]);
+
+  const onNavigate = useCallback(
+    (index: number) => {
+      const wants = index >= count - 1;
+      following.current = !!enabled && wants;
+      if (!wants) {
+        follower?.cancel();
+      }
+    },
+    [enabled, count, follower],
+  );
+
+  return { onNavigate };
+};