@opengeni/react 0.12.0 → 0.15.0

package/src/hooks/use-turn-queue.ts

@@ -1,135 +1,125 @@
-import type { SessionEvent, SessionTurn, UpdateSessionTurnRequest } from "@opengeni/sdk";
-import { useCallback, useEffect, useRef, useState } from "react";
+import type {
+  ComposerDraft,
+  EffectiveSessionControl,
+  SessionEvent,
+  SessionQueueMutationResponse,
+  SessionQueueSnapshot,
+  SessionTurn,
+} from "@opengeni/sdk";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
-import { useDebouncedCallback, useMutationRunner, useSessionEventTrigger, type SessionEventFeedOptions } from "./internal";
+import {
+  useDebouncedCallback,
+  useSessionEventTrigger,
+  type SessionEventFeedOptions,
+} from "./internal";
 
-/** Event types that change the turn queue (queue/edit/reorder/claim/finish). */
+/** Events that can change the authoritative prompt queue or effective control. */
 export function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean {
-  return event.type.startsWith("turn.");
-}
-
-/** Queued turns in execution order (position, then creation time). */
-export function queueFromTurns(turns: SessionTurn[]): SessionTurn[] {
-  return turns
-    .filter((turn) => turn.status === "queued")
-    .sort((a, b) => a.position - b.position || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
-}
-
-/** The turn currently holding the session (running or awaiting approval). */
-export function activeTurnFromTurns(turns: SessionTurn[]): SessionTurn | null {
-  return turns.find((turn) => turn.status === "running" || turn.status === "requires_action") ?? null;
-}
-
-/** Optimistic projection of a queued-turn edit. */
-export function applyTurnEdit(turns: SessionTurn[], turnId: string, update: UpdateSessionTurnRequest): SessionTurn[] {
-  return turns.map((turn) => {
-    if (turn.id !== turnId || turn.status !== "queued") {
-      return turn;
-    }
-    return {
-      ...turn,
-      ...(update.prompt !== undefined ? { prompt: update.prompt } : {}),
-      ...(update.resources !== undefined ? { resources: update.resources } : {}),
-      ...(update.tools !== undefined ? { tools: update.tools } : {}),
-      ...(update.model !== undefined ? { model: update.model } : {}),
-      ...(update.reasoningEffort !== undefined ? { reasoningEffort: update.reasoningEffort } : {}),
-      ...(update.sandboxBackend !== undefined ? { sandboxBackend: update.sandboxBackend } : {}),
-      ...(update.metadata !== undefined ? { metadata: update.metadata } : {}),
-    };
-  });
-}
-
-/**
- * Optimistic projection of a reorder, mirroring the server: the listed
- * queued turns get positions 1..n in the given order; everything else keeps
- * its position.
- */
-export function applyTurnReorder(turns: SessionTurn[], turnIds: string[]): SessionTurn[] {
-  const positions = new Map(turnIds.map((turnId, index) => [turnId, index + 1] as const));
-  return turns.map((turn) => {
-    const position = positions.get(turn.id);
-    return position !== undefined && turn.status === "queued" ? { ...turn, position } : turn;
-  });
+  return (
+    event.type.startsWith("turn.") ||
+    event.type.startsWith("session.queue.") ||
+    event.type.startsWith("session.control.") ||
+    event.type.startsWith("workspace.inference.")
+  );
 }
 
-/** Optimistic projection of a queued-turn delete (server marks it cancelled). */
-export function applyTurnRemoval(turns: SessionTurn[], turnId: string): SessionTurn[] {
-  return turns.map((turn) => (turn.id === turnId && turn.status === "queued" ? { ...turn, status: "cancelled" as const } : turn));
-}
+export type QueueMutationKind = "move" | "edit" | "steer" | "delete";
 
-export type UseTurnQueueOptions = ClientOverride & SessionEventFeedOptions & {
-  /** Optional safety-net polling (ms). Off by default — turn.* events drive updates. */
-  pollIntervalMs?: number | undefined;
-};
+export type UseTurnQueueOptions = ClientOverride &
+  SessionEventFeedOptions & {
+    pollIntervalMs?: number | undefined;
+  };
 
 export type UseTurnQueueResult = {
-  /** All turns the API returned (history + queue), newest server view. */
-  turns: SessionTurn[];
-  /** Queued turns in execution order — render this as the editable queue. */
+  snapshot: SessionQueueSnapshot | null;
+  /** Human/API prompts exactly in server execution order. Never client-sorted. */
   queue: SessionTurn[];
-  /** The running / requires_action turn, if any. */
-  activeTurn: SessionTurn | null;
+  effectiveControl: EffectiveSessionControl | null;
   loading: boolean;
   error: Error | null;
   refresh: () => Promise<void>;
-  /** Edit a queued turn (optimistic; rolls back via refetch on failure). */
-  editTurn: (turnId: string, update: UpdateSessionTurnRequest) => Promise<SessionTurn | null>;
-  /** Reorder the queue to the given queued-turn id order (optimistic). */
-  reorderTurns: (turnIds: string[]) => Promise<SessionTurn[] | null>;
-  /** Delete (cancel) a queued turn before it is claimed (optimistic). */
-  removeTurn: (turnId: string) => Promise<SessionTurn | null>;
-  /** True while an edit/reorder/remove is in flight. */
+  moveTurn: (turnId: string, beforeTurnId: string | null) => Promise<boolean>;
+  /** Atomically withdraw a waiting prompt into the private durable composer draft. */
+  editTurn: (
+    turnId: string,
+    options: { expectedDraftRevision: number; replaceDraft: boolean },
+  ) => Promise<ComposerDraft | null>;
+  /** Advance the same durable waiting prompt; no duplicate prompt is created. */
+  steerTurn: (turnId: string) => Promise<boolean>;
+  removeTurn: (turnId: string) => Promise<boolean>;
+  pendingByTurn: Readonly<Record<string, QueueMutationKind>>;
+  mutationFor: (turnId: string) => QueueMutationKind | null;
   mutating: boolean;
-  /** Last failed mutation, until the next mutation or clear. */
   mutationError: Error | null;
   clearMutationError: () => void;
 };
 
 /**
- * The live turn queue — the heart of the queue-by-default interaction model.
- * Messages sent mid-turn stack up here, visible and editable/reorderable/
- * deletable until the worker claims them. Updates arrive over the session
- * event stream (`turn.*`), either shared via `options.events` (pass the log
- * from `useSessionEvents` to reuse its connection) or a dedicated tail
- * stream. All mutations apply optimistically and reconcile with the server.
+ * The one authoritative human prompt queue. Every mutation carries the exact
+ * server versions the operator saw and accepts only monotonic snapshots. A
+ * conflict immediately reloads server truth; the client never invents order.
  */
-export function useTurnQueue(sessionId: string | null | undefined, options: UseTurnQueueOptions = {}): UseTurnQueueResult {
-  const { client, workspaceId } = useOpenGeni(options);
+export function useTurnQueue(
+  sessionId: string | null | undefined,
+  options: UseTurnQueueOptions = {},
+): UseTurnQueueResult {
+  const { client, workspaceId, workspaceControlEvent, registerSessionReconciler } =
+    useOpenGeni(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
-  const [turns, setTurns] = useState<SessionTurn[]>([]);
+  const [snapshot, setSnapshot] = useState<SessionQueueSnapshot | null>(null);
   const [loading, setLoading] = useState(enabled);
   const [error, setError] = useState<Error | null>(null);
-  const mutation = useMutationRunner();
-  const generation = useRef(0);
+  const [mutationError, setMutationError] = useState<Error | null>(null);
+  const [pendingByTurn, setPendingByTurn] = useState<Record<string, QueueMutationKind>>({});
+  const pendingRef = useRef<Record<string, QueueMutationKind>>({});
+  const readGeneration = useRef(0);
   const targetKeyRef = useRef<string | null>(null);
+  const snapshotRef = useRef<SessionQueueSnapshot | null>(null);
 
-  const load = useCallback(async (): Promise<void> => {
-    if (!sessionId) {
-      return;
+  const acceptSnapshot = useCallback((next: SessionQueueSnapshot | null): boolean => {
+    const current = snapshotRef.current;
+    if (
+      next &&
+      current &&
+      (next.version < current.version ||
+        next.effectiveControl.controlVersion < current.effectiveControl.controlVersion)
+    ) {
+      return false;
     }
-    const ticket = ++generation.current;
+    snapshotRef.current = next;
+    setSnapshot(next);
+    return true;
+  }, []);
+
+  const load = useCallback(async (): Promise<void> => {
+    if (!sessionId) return;
+    const ticket = ++readGeneration.current;
     try {
-      const fetched = await client.listTurns(workspaceId, sessionId);
-      if (ticket === generation.current) {
-        setTurns(fetched);
+      const fetched = await client.getQueue(workspaceId, sessionId);
+      if (ticket === readGeneration.current) {
+        acceptSnapshot(fetched);
         setError(null);
         setLoading(false);
       }
     } catch (cause) {
-      if (ticket === generation.current) {
-        setError(cause instanceof Error ? cause : new Error(String(cause)));
+      if (ticket === readGeneration.current) {
+        setError(asError(cause));
         setLoading(false);
       }
     }
-  }, [client, workspaceId, sessionId]);
+  }, [client, workspaceId, sessionId, acceptSnapshot]);
 
-  // Reset when the target session changes; initial load + optional polling.
   useEffect(() => {
     const targetKey = `${workspaceId}\u0000${sessionId ?? ""}`;
     if (targetKeyRef.current !== targetKey) {
       targetKeyRef.current = targetKey;
-      setTurns([]);
+      readGeneration.current += 1;
+      acceptSnapshot(null);
       setError(null);
+      setMutationError(null);
+      setPendingByTurn({});
+      pendingRef.current = {};
     }
     if (!enabled) {
       setLoading(false);
@@ -140,90 +130,155 @@ export function useTurnQueue(sessionId: string | null | undefined, options: UseT
     const pollIntervalMs = options.pollIntervalMs;
     if (pollIntervalMs === undefined || pollIntervalMs <= 0) {
       return () => {
-        generation.current += 1;
+        readGeneration.current += 1;
       };
     }
     const timer = setInterval(() => void load(), pollIntervalMs);
     return () => {
       clearInterval(timer);
-      generation.current += 1;
+      readGeneration.current += 1;
     };
-  }, [load, enabled, workspaceId, sessionId, options.pollIntervalMs]);
+  }, [load, enabled, workspaceId, sessionId, options.pollIntervalMs, acceptSnapshot]);
+
+  useEffect(() => {
+    if (enabled && workspaceControlEvent) void load();
+  }, [enabled, load, workspaceControlEvent]);
+  useEffect(() => {
+    if (!sessionId || !enabled) return;
+    return registerSessionReconciler(sessionId, "queue", load);
+  }, [enabled, load, registerSessionReconciler, sessionId]);
 
-  // Live updates: any turn.* event re-syncs the queue (debounced).
   const scheduleRefresh = useDebouncedCallback(() => void load());
   useSessionEventTrigger(client, workspaceId, sessionId, isTurnQueueEvent, scheduleRefresh, {
     enabled,
     ...(options.events !== undefined ? { events: options.events } : {}),
   });
 
-  const editTurn = useCallback(
-    async (turnId: string, update: UpdateSessionTurnRequest): Promise<SessionTurn | null> => {
-      if (!sessionId) {
+  const mutate = useCallback(
+    async (
+      turnId: string,
+      kind: QueueMutationKind,
+      command: (
+        current: SessionQueueSnapshot,
+        turn: SessionTurn,
+      ) => Promise<SessionQueueMutationResponse>,
+    ): Promise<SessionQueueMutationResponse | null> => {
+      if (!sessionId || pendingRef.current[turnId]) return null;
+      const current = snapshotRef.current;
+      const turn = current?.items.find((candidate) => candidate.id === turnId);
+      if (!current || !turn) return null;
+      pendingRef.current = { ...pendingRef.current, [turnId]: kind };
+      setPendingByTurn(pendingRef.current);
+      setMutationError(null);
+      try {
+        const result = await command(current, turn);
+        acceptSnapshot(result.snapshot);
+        return result;
+      } catch (cause) {
+        setMutationError(asError(cause));
+        await load();
         return null;
+      } finally {
+        if (turnId in pendingRef.current) {
+          const next = { ...pendingRef.current };
+          delete next[turnId];
+          pendingRef.current = next;
+          setPendingByTurn(next);
+        }
       }
-      setTurns((current) => applyTurnEdit(current, turnId, update));
-      const result = await mutation.run(() => client.updateQueuedTurn(workspaceId, sessionId, turnId, update));
-      if (result) {
-        setTurns((current) => current.map((turn) => (turn.id === result.id ? result : turn)));
-      } else {
-        void load();
-      }
-      return result;
     },
-    [client, workspaceId, sessionId, mutation.run, load],
+    [acceptSnapshot, load, sessionId],
   );
 
-  const reorderTurns = useCallback(
-    async (turnIds: string[]): Promise<SessionTurn[] | null> => {
-      if (!sessionId || turnIds.length === 0) {
-        return null;
-      }
-      setTurns((current) => applyTurnReorder(current, turnIds));
-      const result = await mutation.run(() => client.reorderQueuedTurns(workspaceId, sessionId, turnIds));
-      if (result) {
-        // The server returns the queued turns; merge them over local state.
-        setTurns((current) => {
-          const bySId = new Map(result.map((turn) => [turn.id, turn] as const));
-          return current.map((turn) => bySId.get(turn.id) ?? turn);
-        });
-      } else {
-        void load();
-      }
-      return result;
+  const moveTurn = useCallback(
+    async (turnId: string, beforeTurnId: string | null): Promise<boolean> => {
+      const result = await mutate(turnId, "move", (current) =>
+        client.moveQueueItem(workspaceId, sessionId!, turnId, {
+          clientEventId: operationKey(),
+          expectedQueueVersion: current.version,
+          beforeTurnId,
+        }),
+      );
+      return result !== null;
+    },
+    [client, mutate, sessionId, workspaceId],
+  );
+
+  const editTurn = useCallback(
+    async (
+      turnId: string,
+      edit: { expectedDraftRevision: number; replaceDraft: boolean },
+    ): Promise<ComposerDraft | null> => {
+      const result = await mutate(turnId, "edit", (_current, turn) =>
+        client.editQueueItem(workspaceId, sessionId!, turnId, {
+          clientEventId: operationKey(),
+          expectedTurnVersion: turn.version,
+          expectedDraftRevision: edit.expectedDraftRevision,
+          replaceDraft: edit.replaceDraft,
+        }),
+      );
+      return result?.draft ?? null;
     },
-    [client, workspaceId, sessionId, mutation.run, load],
+    [client, mutate, sessionId, workspaceId],
+  );
+
+  const steerTurn = useCallback(
+    async (turnId: string): Promise<boolean> => {
+      const result = await mutate(turnId, "steer", (current, turn) =>
+        client.steerQueueItem(workspaceId, sessionId!, turnId, {
+          clientEventId: operationKey(),
+          expectedTurnVersion: turn.version,
+          controlEtag: current.effectiveControl.controlEtag,
+        }),
+      );
+      return result !== null;
+    },
+    [client, mutate, sessionId, workspaceId],
   );
 
   const removeTurn = useCallback(
-    async (turnId: string): Promise<SessionTurn | null> => {
-      if (!sessionId) {
-        return null;
-      }
-      setTurns((current) => applyTurnRemoval(current, turnId));
-      const result = await mutation.run(() => client.deleteQueuedTurn(workspaceId, sessionId, turnId));
-      if (result) {
-        setTurns((current) => current.map((turn) => (turn.id === result.id ? result : turn)));
-      } else {
-        void load();
-      }
-      return result;
+    async (turnId: string): Promise<boolean> => {
+      const result = await mutate(turnId, "delete", (_current, turn) =>
+        client.deleteQueueItem(workspaceId, sessionId!, turnId, {
+          clientEventId: operationKey(),
+          expectedTurnVersion: turn.version,
+          reason: "Deleted from the prompt queue",
+        }),
+      );
+      return result !== null;
     },
-    [client, workspaceId, sessionId, mutation.run, load],
+    [client, mutate, sessionId, workspaceId],
   );
 
+  const mutationFor = useCallback(
+    (turnId: string): QueueMutationKind | null => pendingByTurn[turnId] ?? null,
+    [pendingByTurn],
+  );
+  const mutating = useMemo(() => Object.keys(pendingByTurn).length > 0, [pendingByTurn]);
+
   return {
-    turns,
-    queue: queueFromTurns(turns),
-    activeTurn: activeTurnFromTurns(turns),
+    snapshot,
+    queue: snapshot?.items ?? [],
+    effectiveControl: snapshot?.effectiveControl ?? null,
     loading,
     error,
     refresh: load,
+    moveTurn,
     editTurn,
-    reorderTurns,
+    steerTurn,
     removeTurn,
-    mutating: mutation.mutating,
-    mutationError: mutation.mutationError,
-    clearMutationError: mutation.clearMutationError,
+    pendingByTurn,
+    mutationFor,
+    mutating,
+    mutationError,
+    clearMutationError: useCallback(() => setMutationError(null), []),
   };
 }
+
+function operationKey(): string {
+  return globalThis.crypto.randomUUID();
+}
+
+function asError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}

package/src/hooks/use-windowed-sections.ts

@@ -0,0 +1,204 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+/* ----------------------------------------------------------------------------
+   Windowed sections — variable-height file-section virtualization.
+
+   The Changes tab stacks N file diffs in one scroll pane. Mounting N Shiki
+   highlighters (Pierre's `PatchDiff`) at once is the exact wart this replaces,
+   so we mount only the sections inside the visible window ± overscan and reserve
+   the rest as empty space (dossier §10.7, D2).
+
+   Why NOT `virtua` here (unlike the file tree/rail): Pierre renders each diff in
+   a shadow DOM with its own internal overflow/virtualization, so an outer
+   measuring virtualizer can read a collapsed or fixed height and lay sections
+   out wrong (dossier risk #6). This hook windows by mounting/unmounting whole
+   file sections off a scroll offset and a per-section height ESTIMATE (refined
+   by measurement when a real browser provides it), which never depends on
+   Pierre reporting its own height — and the math is pure + deterministic, so
+   D2 is provable in both happy-dom (drive scrollTop/clientHeight) and a real
+   browser (Playwright, the verification-matrix path).
+   -------------------------------------------------------------------------- */
+
+export type WindowRange = {
+  /** First mounted index (inclusive). */
+  start: number;
+  /** One past the last mounted index (exclusive). */
+  end: number;
+};
+
+/**
+ * Pure windowing math: given each section's height (px), the scroll offset, the
+ * viewport height, and an overscan count, return the `[start, end)` index window
+ * to mount. Robust to a zero viewport (a headless/pre-layout pass) — it then
+ * mounts a small overscan window anchored at the item under `scrollTop` rather
+ * than the whole list.
+ */
+export function computeWindowRange(
+  heights: readonly number[],
+  scrollTop: number,
+  viewport: number,
+  overscan: number,
+): WindowRange {
+  const n = heights.length;
+  if (n === 0) return { start: 0, end: 0 };
+  const top = Math.max(scrollTop, 0);
+  const bottom = top + Math.max(viewport, 0);
+
+  let firstVisible = -1;
+  let lastVisible = -1;
+  let acc = 0;
+  let anchor = 0; // the item containing `scrollTop` — the zero-viewport fallback
+  for (let i = 0; i < n; i++) {
+    const secTop = acc;
+    const secBottom = secTop + Math.max(heights[i] ?? 0, 0);
+    if (secTop <= top) anchor = i;
+    // A section is visible when it overlaps [top, bottom); with viewport 0 the
+    // half-open interval is empty, so nothing matches and we fall back to anchor.
+    if (secBottom > top && secTop < bottom) {
+      if (firstVisible === -1) firstVisible = i;
+      lastVisible = i;
+    }
+    acc = secBottom;
+  }
+
+  if (firstVisible === -1) {
+    firstVisible = anchor;
+    lastVisible = anchor;
+  }
+
+  return {
+    start: Math.max(0, firstVisible - overscan),
+    end: Math.min(n, lastVisible + 1 + overscan),
+  };
+}
+
+export type WindowedSections = {
+  /** Attach to the scroll container. */
+  scrollRef: React.RefObject<HTMLDivElement | null>;
+  /** The mounted window `[start, end)`. */
+  range: WindowRange;
+  /** Prefix offsets: `offsets[i]` is the top px of section `i`; `offsets[count]`
+   *  is the total content height. */
+  offsets: number[];
+  /** Total content height (px) — set on the spacer so scroll length is stable. */
+  totalHeight: number;
+  /** Report a MOUNTED section's real height (px) so the layout refines as async
+   *  content — e.g. Pierre's Shiki render — grows. Drive it from a ResizeObserver;
+   *  a zero/idle value is ignored so a headless pass keeps the estimate. */
+  measure: (index: number, height: number) => void;
+  /** Scroll section `index` to the top of the pane (the rail-jump). */
+  scrollToIndex: (index: number) => void;
+};
+
+/**
+ * Variable-height section windowing over a scroll container. Seeds every section
+ * to `estimateHeight(i)`, mounts only `range`, and refines heights from real
+ * measurements (a no-op in a zero-layout headless pass, which keeps the estimate
+ * — deterministic for tests). Pass a STABLE `estimateHeight` (wrap in useCallback).
+ */
+export function useWindowedSections(opts: {
+  count: number;
+  estimateHeight: (index: number) => number;
+  overscan?: number | undefined;
+}): WindowedSections {
+  const { count, estimateHeight, overscan = 3 } = opts;
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+
+  const [heights, setHeights] = useState<number[]>(() =>
+    Array.from({ length: count }, (_, i) => estimateHeight(i)),
+  );
+
+  // Re-seed heights when the section count changes (a new diff arrives), keeping
+  // any already-measured heights for surviving indices.
+  useEffect(() => {
+    setHeights((prev) => {
+      if (prev.length === count) return prev;
+      return Array.from({ length: count }, (_, i) => prev[i] ?? estimateHeight(i));
+    });
+    // estimateHeight is expected stable; count is the real trigger.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [count]);
+
+  const heightsRef = useRef(heights);
+  heightsRef.current = heights;
+
+  const [range, setRange] = useState<WindowRange>(() => ({
+    start: 0,
+    end: Math.min(count, overscan + 1),
+  }));
+
+  const recompute = useCallback(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const next = computeWindowRange(heightsRef.current, el.scrollTop, el.clientHeight, overscan);
+    setRange((prev) => (prev.start === next.start && prev.end === next.end ? prev : next));
+  }, [overscan]);
+
+  // Recompute on scroll (rAF-coalesced) and on container resize.
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    let raf = 0;
+    const onScroll = () => {
+      if (raf) return;
+      raf =
+        typeof requestAnimationFrame === "function"
+          ? requestAnimationFrame(() => {
+              raf = 0;
+              recompute();
+            })
+          : (recompute(), 0);
+    };
+    el.addEventListener("scroll", onScroll, { passive: true });
+    const ro = typeof ResizeObserver !== "undefined" ? new ResizeObserver(() => recompute()) : null;
+    ro?.observe(el);
+    recompute();
+    return () => {
+      el.removeEventListener("scroll", onScroll);
+      ro?.disconnect();
+      if (raf && typeof cancelAnimationFrame === "function") cancelAnimationFrame(raf);
+    };
+  }, [recompute, count]);
+
+  const measure = useCallback((index: number, height: number) => {
+    if (height <= 0) return; // zero-layout pass — keep the estimate
+    setHeights((prev) => {
+      if (Math.abs((prev[index] ?? 0) - height) < 1) return prev;
+      const next = prev.slice();
+      next[index] = height;
+      return next;
+    });
+  }, []);
+
+  const offsets = useMemo(() => {
+    const out = new Array<number>(count + 1);
+    out[0] = 0;
+    for (let i = 0; i < count; i++) out[i + 1] = (out[i] ?? 0) + Math.max(heights[i] ?? 0, 0);
+    return out;
+  }, [heights, count]);
+
+  // A measured height can shift the window (e.g. estimates were short) — keep the
+  // mounted set in sync without waiting for the next scroll.
+  useEffect(() => {
+    recompute();
+  }, [offsets, recompute]);
+
+  const scrollToIndex = useCallback(
+    (index: number) => {
+      const el = scrollRef.current;
+      if (!el) return;
+      const clamped = Math.max(0, Math.min(count - 1, index));
+      el.scrollTop = offsets[clamped] ?? 0;
+    },
+    [offsets, count],
+  );
+
+  return {
+    scrollRef,
+    range,
+    offsets,
+    totalHeight: offsets[count] ?? 0,
+    measure,
+    scrollToIndex,
+  };
+}