@alia.onl/sdk 15.8.0 → 19.1.0

package/src/hooks/useReadAloud.ts

@@ -0,0 +1,92 @@
+import { toast } from '@oxy.so/bloom/toast';
+import { useCallback, useEffect, useRef } from 'react';
+import { useLabels } from '../lib/labels';
+import { useAliaRuntime } from '../runtime/config';
+import { useDictationStore } from './useDictation';
+import { useTTS } from './useTTS';
+
+export type ReadAloudState = 'idle' | 'loading' | 'playing' | 'paused' | 'error';
+
+/**
+ * The screen whose player is sounding, if any.
+ *
+ * `useTTS` keeps its player PER HOOK INSTANCE while the playback state is one shared store — and
+ * a host can keep every visited chat mounted, each with its own thread and so its own instance.
+ * Starting a reply in one chat must stop a reply still playing in another, and only the instance
+ * that owns a player can stop it. So the owner registers its `stop` here, and anyone may call it.
+ */
+let owner: { stop: () => void } | null = null;
+
+/** Silence whatever a thread is reading aloud, on any mounted screen. */
+export function stopReadingAloud(): void {
+  const current = owner;
+  owner = null;
+  current?.stop();
+}
+
+/**
+ * Read one reply aloud, as a toggle.
+ *
+ * - A press starts it; a second press on the same reply stops it — not `useTTS`'s pause, which
+ *   would leave a half-read reply parked with nothing on screen saying so.
+ * - `blocked` is a call or a dictation holding the audio: the button is disabled, and anything
+ *   already being read stops when either starts. Two voices at once, or the microphone recording
+ *   Alia's own voice into the draft, is the thing this prevents.
+ * - A failure is a toast, and the button goes back to idle.
+ *
+ * It speaks with the runtime's `apiUrl` and the host's `speech` preferences.
+ */
+export function useReadAloud(blocked: boolean) {
+  const { t } = useLabels();
+  const { apiUrl, speech } = useAliaRuntime();
+  const { readAloud, stop, activeMessageId, playbackState } = useTTS({ apiUrl, ...speech });
+  const self = useRef<{ stop: () => void }>({ stop });
+  self.current.stop = stop;
+  const owns = owner === self.current && activeMessageId !== null;
+
+  // A call or a dictation began: whatever is being read stops, wherever.
+  const dictating = useDictationStore((s) => s.isRecording);
+  const busy = blocked || dictating;
+  useEffect(() => {
+    if (busy) stopReadingAloud();
+  }, [busy]);
+
+  useEffect(() => {
+    if (!owns || playbackState !== 'error') return;
+    toast.error(t('chat.readAloudFailed'));
+    stopReadingAloud();
+  }, [owns, playbackState, t]);
+
+  // Leaving takes the player with it (`useTTS` releases it); the shared state has to go too, or
+  // every other screen would show a reply still playing.
+  useEffect(() => {
+    const me = self.current;
+    return () => {
+      if (owner === me) stopReadingAloud();
+    };
+  }, []);
+
+  const active = useRef(activeMessageId);
+  active.current = activeMessageId;
+  const toggle = useCallback(
+    (messageId: string, text: string, conversationId?: string) => {
+      const wasThis = active.current === messageId;
+      stopReadingAloud();
+      if (wasThis) return;
+      owner = self.current;
+      // The route makes a clip once and answers every later press — here or after a reload — from
+      // storage. `conversationId` files it under the conversation, so deleting that deletes it;
+      // the caller passes it only for a message the server holds (`Message.unsaved`): for one it
+      // does not, the route answers 404 and nothing would be read.
+      void readAloud(messageId, text, conversationId);
+    },
+    [readAloud],
+  );
+
+  const stateOf = useCallback(
+    (messageId: string): ReadAloudState => (activeMessageId === messageId ? playbackState : 'idle'),
+    [activeMessageId, playbackState],
+  );
+
+  return { toggle, stateOf, blocked: busy };
+}

package/src/hooks/useShareHandler.ts

@@ -0,0 +1,24 @@
+import { toast } from '@oxy.so/bloom/toast';
+import { useCallback } from 'react';
+import { useLabels } from '../lib/labels';
+import { type AliaConversationShare, useShareConversation } from '../runtime/sharing';
+
+/**
+ * What the header's share button does: mint the conversation's read-only link, then hand it to
+ * the host, which builds its own URL and shows its own share sheet. `undefined` without a host
+ * `onShare`, so there is no button.
+ */
+export function useShareHandler(
+  onShare: ((share: AliaConversationShare) => void) | undefined,
+): ((conversationId: string | undefined) => void) | undefined {
+  const { share } = useShareConversation();
+  const { t } = useLabels();
+  const handle = useCallback(
+    (conversationId: string | undefined) => {
+      if (conversationId === undefined || onShare === undefined) return;
+      void share(conversationId).then(onShare, () => toast.error(t('chat.shareFailed')));
+    },
+    [share, onShare, t],
+  );
+  return onShare === undefined ? undefined : handle;
+}

package/src/hooks/useSoundEffects.ts

@@ -91,7 +91,7 @@ export function useSoundEffects(enabled: boolean = false, sounds: SoundSources =
 
 /**
  * Hook that automatically triggers sound effects based on voice state changes.
- * Wire this into the conversation page alongside useVoiceMode.
+ * Wire this into the conversation page from the launcher's state (`useVoiceLauncher`).
  */
 export function useVoiceSoundEffects({
   isVoiceActive,

package/src/hooks/useThoughtScope.ts

@@ -0,0 +1,59 @@
+import { useQueryClient } from '@tanstack/react-query';
+import { useEffect, useMemo } from 'react';
+import { aliaQueryKeys } from '../runtime/query-keys';
+import { type ThoughtScope, useThoughtStore } from '../runtime/thought-store';
+import type { FailedTurn } from '../runtime/turn-failure';
+import type { Message } from '../runtime/types';
+
+export interface UseThoughtScopeOptions {
+  /** The conversation being streamed into, or `undefined` for a new chat. */
+  conversationId: string | undefined;
+  messages: Message[];
+  conversationLoading: boolean;
+  isLoading: boolean;
+  failedTurn: FailedTurn | null;
+}
+
+/**
+ * This conversation as the thought panel reads it: its messages, whether they are all here yet,
+ * and the turn in flight — kept in the thought store.
+ *
+ * Keyed on the conversation and its messages, NOT on the panel being open. Syncing only while
+ * the panel was open meant the first press on a tool row rendered against whatever the store held
+ * before — another conversation's messages, or none — and found nothing by id. The store accepts
+ * this only while the open selection belongs to the same conversation, so a new-chat screen
+ * mounted underneath cannot blank a panel opened here.
+ *
+ * A load that failed is read off the query cache at the moment the memo recomputes: the load's
+ * end is what flips `conversationLoading`, so the read is fresh exactly when it matters.
+ */
+export function useThoughtScope({
+  conversationId,
+  messages,
+  conversationLoading,
+  isLoading,
+  failedTurn,
+}: UseThoughtScopeOptions): ThoughtScope {
+  const queryClient = useQueryClient();
+  const sync = useThoughtStore((s) => s.sync);
+
+  const scope = useMemo<ThoughtScope>(() => {
+    const loadFailed =
+      conversationId !== undefined &&
+      queryClient.getQueryState(aliaQueryKeys.conversations.detail(conversationId))?.status ===
+        'error';
+    return {
+      conversationId: conversationId ?? null,
+      messages,
+      status: conversationLoading ? 'loading' : loadFailed ? 'failed' : 'ready',
+      isLoading,
+      failedTurn,
+    };
+  }, [conversationId, messages, conversationLoading, isLoading, failedTurn, queryClient]);
+
+  useEffect(() => {
+    sync(scope);
+  }, [scope, sync]);
+
+  return scope;
+}

package/src/hooks/useThreadRows.ts

@@ -0,0 +1,145 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useLabels } from '../lib/labels';
+import {
+  type Message,
+  type ThreadMessage,
+  arrivedIds,
+  daySeparators,
+  threadSeamIds,
+  turnTimings,
+} from '../runtime/model';
+import { useTimelineShape } from './useTimelineWindow';
+
+/** The history of a conversation that has none, as ONE array: a fresh `[]` per render would break every memo. */
+const NO_HISTORY: ThreadMessage[] = [];
+
+/** For a row the timings map has never heard of: a shared frozen object keeps memoised rows still. */
+const EMPTY_TIMING = Object.freeze({ startedAt: null, endedAt: null });
+
+/** True for Alia's own replies (a delegated agent's are not). */
+function isAliaReply(message: Message): boolean {
+  return message.role === 'assistant' && !message.agentInfo;
+}
+
+export interface UseThreadRowsOptions {
+  /** The conversation being streamed into. */
+  messages: readonly Message[];
+  /** Everything said in the thread before it, oldest first. Empty where nothing is behind it. */
+  history: readonly ThreadMessage[] | undefined;
+  /** The conversation being streamed into: where the seam between the history and the live rows falls. */
+  conversationId: string | undefined;
+  /** The conversation's messages are still on their way. */
+  conversationLoading: boolean;
+}
+
+/**
+ * What the thread draws, derived once per change of its STRUCTURE.
+ *
+ * The live list as ids, roles, stamps and speakers is what a streamed token never changes, so
+ * everything derived from the whole thread (day lines, seams, turn timings, the last answer of
+ * Alia's, the window's ids) is keyed on that rather than on the messages: a token re-derives
+ * nothing, it re-renders the row it was written into and that is all.
+ */
+export function useThreadRows({
+  messages,
+  history: historyMessages,
+  conversationId,
+  conversationLoading,
+}: UseThreadRowsOptions) {
+  const { t, locale } = useLabels();
+  const history = historyMessages ?? NO_HISTORY;
+
+  const live = useMemo(
+    () => messages.filter((m) => m.role === 'user' || m.role === 'assistant'),
+    [messages],
+  );
+
+  /**
+   * Everything on screen, in reading order: the history first, the conversation being streamed
+   * into after it. Every position below — which row is last, which is the last of Alia's — is an
+   * index into THIS, not into the live messages.
+   */
+  const rows = useMemo<Message[]>(
+    () => (history.length === 0 ? live : [...history, ...live]),
+    [history, live],
+  );
+
+  const liveShape = useTimelineShape(live);
+  const shape = useMemo<readonly Message[]>(
+    () => (history.length === 0 ? liveShape : [...history, ...liveShape]),
+    [history, liveShape],
+  );
+  const ids = useMemo(() => shape.map((m) => m.id), [shape]);
+
+  /**
+   * The live rows that arrived since the last change to the list, which are the only ones that
+   * animate in. A history row never does, and neither does a conversation that was loaded or
+   * switched to (`arrivedIds`).
+   */
+  const previousLive = useRef<{ ids: readonly string[]; loading: boolean } | null>(null);
+  const arrived = useMemo(
+    () =>
+      arrivedIds(
+        previousLive.current?.ids ?? null,
+        previousLive.current?.loading ?? false,
+        liveShape,
+      ),
+    [liveShape],
+  );
+  useEffect(() => {
+    previousLive.current = { ids: liveShape.map((m) => m.id), loading: conversationLoading };
+  }, [liveShape, conversationLoading]);
+
+  /**
+   * Every turn's start and end, computed once for the whole thread: asked per row it is O(n²), and
+   * this list re-renders roughly twenty times a second while an answer streams.
+   */
+  const timings = useMemo(() => turnTimings(shape), [shape]);
+
+  /** The day each message starts, when it starts a new one: Bloom's inline date line above it. */
+  const dayLabels = useMemo(() => {
+    const labels = new Map<string, string>();
+    for (const { messageId, label } of daySeparators(shape, new Date(), locale)) {
+      labels.set(
+        messageId,
+        label.kind === 'today'
+          ? t('chat.today')
+          : label.kind === 'yesterday'
+            ? t('chat.yesterday')
+            : label.text,
+      );
+    }
+    return labels;
+  }, [shape, locale, t]);
+
+  /**
+   * Where one conversation of a thread ends and the next begins: the model was given a fresh
+   * context there, and everything above is out of its sight (`threadSeamIds`).
+   */
+  const seamIds = useMemo(
+    () => threadSeamIds(history, liveShape, conversationId ?? ''),
+    [history, liveShape, conversationId],
+  );
+
+  const timingOf = useCallback(
+    (messageId: string) => timings.get(messageId) ?? EMPTY_TIMING,
+    [timings],
+  );
+
+  const lastReplyIndex = useMemo(
+    () => shape.reduce((acc, m, i) => (isAliaReply(m) ? i : acc), -1),
+    [shape],
+  );
+
+  return {
+    rows,
+    live,
+    history,
+    ids,
+    arrived,
+    dayLabels,
+    seamIds,
+    lastReplyIndex,
+    timingOf,
+  };
+}

package/src/hooks/useThreadView.ts

@@ -0,0 +1,68 @@
+import { useCallback, useMemo, useState } from 'react';
+import type { ThreadHistory, ThreadSearchHit } from '../runtime/thread/thread-history';
+import { useThreadHistory } from '../runtime/use-thread-history';
+import { useThreadWindow } from '../runtime/use-thread-search';
+
+/**
+ * What the thread looks at: the present, or a moment in its past.
+ *
+ * An agent's thread has two states and they are not variations of one. At the present, the
+ * history runs into the conversation being streamed into. At a moment — a hit of the thread's
+ * search — the screen shows the stretch around one old message and there is nothing live beneath
+ * it. The way back is leaving, not scrolling: the endpoint pages BACKWARDS only, so walking
+ * forward from a jump would be a road that ends.
+ *
+ * `threadHandle` is the agent's handle; without it the chat is one conversation with nothing
+ * behind it and there is nothing to page into, search or jump to.
+ */
+export function useThreadView(
+  threadHandle: string | undefined,
+  conversationId: string | undefined,
+) {
+  const present = useThreadHistory(threadHandle, conversationId);
+  const [searchOpen, setSearchOpen] = useState(false);
+  /** The message the reader jumped to, by cursor, or `null` for the present. */
+  const [jumpedTo, setJumpedTo] = useState<string | null>(null);
+  const past = useThreadWindow(threadHandle, jumpedTo);
+  const jumped = jumpedTo !== null;
+
+  // Ask for the page above, unless one is already coming. Bloom fires `onStartReached` once per
+  // approach and re-arms when the reader leaves the zone, so the guards left are about the DATA.
+  const source = jumped
+    ? { ...past, loading: past.isLoadingMore || past.isLoading }
+    : { ...present, loading: present.isLoadingMore };
+  const { messages, hasMore, loading, loadMore: fetchMore } = source;
+  const loadMore = useCallback(() => {
+    if (!loading) void fetchMore();
+  }, [loading, fetchMore]);
+
+  const history = useMemo<ThreadHistory | undefined>(
+    () =>
+      threadHandle === undefined
+        ? undefined
+        : { messages, loading, ...(hasMore ? { loadMore } : {}) },
+    [threadHandle, messages, loading, hasMore, loadMore],
+  );
+
+  /**
+   * Open the thread around a hit, and close the search over it. The cursor rather than the
+   * message id: an id addresses a message, and only a cursor addresses a POSITION, which is what
+   * a window is asked for.
+   */
+  const jump = useCallback((hit: ThreadSearchHit) => {
+    setJumpedTo(hit.cursor);
+    setSearchOpen(false);
+  }, []);
+
+  return {
+    history,
+    /** The cursor jumped to, or `null` at the present. */
+    focusCursor: jumpedTo,
+    jumped,
+    jump,
+    backToLatest: useCallback(() => setJumpedTo(null), []),
+    searchOpen,
+    openSearch: useCallback(() => setSearchOpen(true), []),
+    closeSearch: useCallback(() => setSearchOpen(false), []),
+  };
+}

package/src/hooks/useTimelineWindow.ts

@@ -0,0 +1,256 @@
+import {
+  type Message,
+  TAIL,
+  TOP,
+  type TimelineAnchor,
+  type TimelinePosition,
+  collapseToTail,
+  pinAnchor,
+  resolveStart,
+  revealAbove,
+  sameTimelineShape,
+  timelinePositions,
+} from '../runtime/model';
+import type { AiChatThreadHandle } from '@oxy.so/bloom/ai-chat';
+import { useCallback, useLayoutEffect, useMemo, useRef, useState, type RefObject } from 'react';
+import type { LayoutChangeEvent, NativeScrollEvent, NativeSyntheticEvent } from 'react-native';
+
+/**
+ * The list, handed back as the SAME array for as long as only what its
+ * messages say has changed (`sameTimelineShape`).
+ *
+ * The array it returns may hold an older copy of the message being streamed
+ * into, so it is for deriving structure — ids, roles, stamps, speakers — and
+ * never for drawing text.
+ */
+export function useTimelineShape<
+  T extends Pick<Message, 'id' | 'role' | 'createdAt' | 'agentInfo'>,
+>(list: readonly T[]): readonly T[] {
+  const shape = useRef(list);
+  if (!sameTimelineShape(shape.current, list)) shape.current = list;
+  return shape.current;
+}
+
+interface Options {
+  /** Every row's id, in reading order. Keep its identity stable across tokens. */
+  ids: readonly string[];
+  /**
+   * What a saved position belongs to — the conversation — or `null` for a view
+   * that is not remembered (a cursor jump's window of the past).
+   */
+  scrollKey: string | null;
+  /** The conversation's messages have loaded; a restore waits for it. */
+  ready: boolean;
+  /** Index of a cursor jump's target row, or -1. It is always mounted. */
+  focusIndex: number;
+  /** A turn is streaming; the window is never folded under it. */
+  turnInFlight: boolean;
+  atBottomThreshold: number;
+  threadRef: RefObject<AiChatThreadHandle | null>;
+  /** Ask for the page of history above the first loaded row. */
+  onLoadHistory?: () => void;
+  onScroll?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+}
+
+/**
+ * What is still to be done to the scroll once the rows it needs are laid out.
+ * A restore remembers the list it was set against: that list may still be the
+ * previous conversation's, and only a list that changed after it can say the
+ * saved row is really gone.
+ */
+type PendingScroll =
+  | { kind: 'end' }
+  | { kind: 'offset'; position: TimelinePosition; setAgainst: readonly string[] };
+
+/**
+ * A restore is waiting for its conversation's rows: the row it was saved
+ * against is not on screen, and the list has not changed since it was set. A
+ * list that did change without bringing that row back means the row is gone
+ * (edited away, regenerated), and the restore falls back to the newest turn.
+ */
+function awaitingRows(pending: { current: PendingScroll | null }, ids: readonly string[]): boolean {
+  const todo = pending.current;
+  if (todo?.kind !== 'offset' || ids.includes(todo.position.probeId)) return false;
+  if (ids === todo.setAgainst) return true;
+  pending.current = { kind: 'end' };
+  return false;
+}
+
+/** The state before the first key: nothing mounted yet, so nothing to remember. */
+const MOUNTING = Symbol('mounting');
+
+const nextFrame = (run: () => void): void => {
+  if (typeof requestAnimationFrame === 'function') requestAnimationFrame(run);
+  else setTimeout(run, 0);
+};
+
+/**
+ * Which rows the thread mounts, and the scroll that goes with them: the window
+ * over a long history, and the position a conversation is returned to.
+ *
+ * ## The window
+ *
+ * The newest `INITIAL_ROWS` rows mount first. Near the top, Bloom's
+ * `onStartReached` reveals `PAGE_ROWS` more — or, with none left, asks for the
+ * thread's history — and `maintainStartPosition` holds the reader on the row
+ * they were reading while either lands above. The window folds back to its
+ * opening size only when the reader is at the bottom and nothing is streaming.
+ * See `runtime/thread/timeline.ts` for why it is this and not virtualization.
+ *
+ * ## The position
+ *
+ * Leaving a conversation — by navigating away or by switching the screen to
+ * another — saves the offset, whether the reader was at the bottom, and the
+ * window's anchor. Coming back restores the anchor first, so the same rows are
+ * mounted above the reader, and the offset once they have laid out. Coming
+ * back from a cursor jump does not restore: "back to latest" means the latest.
+ */
+export function useTimelineWindow({
+  ids,
+  scrollKey,
+  ready,
+  focusIndex,
+  turnInFlight,
+  atBottomThreshold,
+  threadRef,
+  onLoadHistory,
+  onScroll,
+}: Options) {
+  const [state, setState] = useState<{ key: string | null; anchor: TimelineAnchor }>({
+    key: scrollKey,
+    anchor: TAIL,
+  });
+  // The render after a key change and before its effect: the new conversation
+  // starts from the newest rows until the effect says otherwise.
+  const anchor = state.key === scrollKey ? state.anchor : TAIL;
+  const start = useMemo(() => resolveStart(anchor, ids, focusIndex), [anchor, ids, focusIndex]);
+
+  const setAnchor = useCallback(
+    (next: TimelineAnchor) => setState((current) => ({ key: current.key, anchor: next })),
+    [],
+  );
+
+  /** This render's facts, for callbacks and cleanups that outlive it. */
+  const latest = useRef({ ids, start, anchor, ready, turnInFlight, onLoadHistory });
+  useLayoutEffect(() => {
+    latest.current = { ids, start, anchor, ready, turnInFlight, onLoadHistory };
+  });
+
+  /** The last position the thread reported for the current key. */
+  const lastOffset = useRef<number | null>(null);
+  const atBottom = useRef(true);
+  const pending = useRef<PendingScroll | null>(null);
+  const previousKey = useRef<string | null | typeof MOUNTING>(MOUNTING);
+
+  useLayoutEffect(() => {
+    const cameFrom = previousKey.current;
+    previousKey.current = scrollKey;
+    lastOffset.current = null;
+    atBottom.current = true;
+    // Returning from a jump is a request for the present, not for the past.
+    // A reader who left from the bottom comes back to the newest page, which
+    // is where they were; only a position mid-thread brings its rows back.
+    const read =
+      scrollKey !== null && cameFrom !== null ? timelinePositions.read(scrollKey) : undefined;
+    const saved = read?.atBottom === false ? read : undefined;
+    pending.current =
+      scrollKey === null
+        ? null
+        : saved === undefined
+          ? { kind: 'end' }
+          : { kind: 'offset', position: saved, setAgainst: ids };
+    setState({ key: scrollKey, anchor: saved?.anchor ?? TAIL });
+
+    return () => {
+      if (scrollKey === null) return;
+      const { ids: rows, start: first, anchor: kept } = latest.current;
+      if (rows.length === 0) return;
+      timelinePositions.save(scrollKey, {
+        anchor: kept,
+        offset: lastOffset.current ?? 0,
+        atBottom: atBottom.current,
+        probeId: rows[first],
+      });
+    };
+  }, [scrollKey]);
+
+  /**
+   * Pin the opening window to its first row once the rows exist, so a turn
+   * appended at the bottom grows the window rather than sliding it — a slide
+   * would unmount the top row under a reader who is mid-thread. Re-pinned the
+   * same way when the pinned row has gone (the list was replaced) — except
+   * while a restore waits for its conversation's rows: the rows on screen are
+   * still the last conversation's, and the anchor being restored is not in
+   * them yet.
+   */
+  useLayoutEffect(() => {
+    if (ids.length === 0 || awaitingRows(pending, ids)) return;
+    const stale = anchor.kind === 'tail' || (anchor.kind === 'row' && !ids.includes(anchor.id));
+    if (!stale) return;
+    setState((current) =>
+      current.key === scrollKey && current.anchor === anchor
+        ? { key: current.key, anchor: pinAnchor(ids, start) }
+        : current,
+    );
+  }, [ids, anchor, start, scrollKey]);
+
+  const handleStartReached = useCallback(() => {
+    const { ids: rows, start: first, onLoadHistory: loadHistory } = latest.current;
+    const next = revealAbove(rows, first);
+    if (next !== null) {
+      setAnchor(next);
+      return;
+    }
+    setAnchor(TOP);
+    loadHistory?.();
+  }, [setAnchor]);
+
+  const handleScroll = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      const { contentOffset, contentSize, layoutMeasurement } = event.nativeEvent;
+      lastOffset.current = contentOffset.y;
+      const wasAtBottom = atBottom.current;
+      atBottom.current =
+        contentSize.height - contentOffset.y - layoutMeasurement.height <= atBottomThreshold;
+      if (atBottom.current && !wasAtBottom && !latest.current.turnInFlight) {
+        const { ids: rows, start: first } = latest.current;
+        const folded = collapseToTail(rows, first);
+        if (folded !== null) {
+          pending.current = { kind: 'end' };
+          setAnchor(folded);
+        }
+      }
+      onScroll?.(event);
+    },
+    [atBottomThreshold, onScroll, setAnchor],
+  );
+
+  /**
+   * The rows have laid out: carry out whatever scroll was waiting for them.
+   * A frame later, so it lands after the thread's own reaction to the same
+   * layout (on web it follows to the end on its first one).
+   */
+  const handleListLayout = useCallback(
+    (_event: LayoutChangeEvent) => {
+      const { ids: rows, ready: loaded } = latest.current;
+      if (pending.current === null || !loaded || rows.length === 0) return;
+      if (awaitingRows(pending, rows)) return;
+      const todo = pending.current;
+      pending.current = null;
+      nextFrame(() => {
+        if (todo.kind === 'end') threadRef.current?.scrollToEnd({ animated: false });
+        else threadRef.current?.scrollToOffset({ offset: todo.position.offset });
+      });
+    },
+    [threadRef],
+  );
+
+  return {
+    /** Index of the first mounted row. */
+    start,
+    /** For `AiChatThread`: absent when there is nothing above to reveal or load. */
+    onStartReached: start > 0 || onLoadHistory !== undefined ? handleStartReached : undefined,
+    onScroll: handleScroll,
+    onListLayout: handleListLayout,
+  };
+}