@marktiderman/genesis-chat 0.1.1 → 0.2.0

package/src/native/topics.tsx

@@ -0,0 +1,179 @@
+/**
+ * @feat:chat
+ * The topic bar on native: "All" and each of a conversation's topics as single-choice chips in a
+ * row that scrolls sideways, a lock on closed ones, and, for owners and admins, an options button
+ * that adds a topic and renames, closes or reopens the one shown (one sheet: the menu, then the
+ * name field). `ChatThreadScreen` shows it when the conversation has topics, and reads the
+ * messages of the topic chosen. The same rules as the web's `ChatTopicBar`.
+ */
+import { useState } from "react";
+import { ScrollView, View } from "react-native";
+import { NativeButton, NativeChip, NativeChipGroup, NativeIcon, NativeInput, NativeListItem, NativeSheet, NativeText, useToast } from "@marktiderman/genesis-ui-native/components";
+import { useThemeRoles } from "@marktiderman/genesis-ui-native/hooks";
+import { topicKey } from "../core/extras";
+import type { ChatRole, ChatTopic, TopicInput } from "../core/types";
+import { fill } from "./copy";
+import { useChatNative } from "./context";
+import { ChatIconButton } from "./icon-button";
+
+const ALL = "__all__";
+
+/** Owners and admins add, rename, close and reopen topics. */
+export function canManageTopics(role: ChatRole | null | undefined): boolean {
+  return role === "owner" || role === "admin";
+}
+
+/** A closed topic takes posts only from owners, admins and observers. */
+export function topicClosedFor(topic: ChatTopic | null | undefined, role: ChatRole | null | undefined): boolean {
+  return Boolean(topic?.closedAt) && role !== "owner" && role !== "admin" && role !== "observer";
+}
+
+export type TopicMenuAction = "new" | "rename" | "close" | "reopen";
+
+/** What the options sheet offers: always New; Rename and Close or Reopen when a topic is shown. */
+export function topicMenuFor(current: ChatTopic | null | undefined): TopicMenuAction[] {
+  if (!current) return ["new"];
+  return ["new", "rename", current.closedAt ? "reopen" : "close"];
+}
+
+/**
+ * Checks a topic's name: its key, or why it can't be saved. Renaming keeps the key (messages
+ * carry it), so only a new topic can clash with another's key.
+ */
+export function checkTopicName(title: string, topics: readonly ChatTopic[], renaming?: string | null): { key: string } | { error: "empty" | "exists" } {
+  const name = title.trim();
+  if (!name) return { error: "empty" };
+  if (renaming) return { key: renaming };
+  const key = topicKey(name);
+  return topics.some((t) => t.topic === key) ? { error: "exists" } : { key };
+}
+
+export interface ChatTopicBarProps {
+  topics: ChatTopic[];
+  /** The topic shown; null for "All". */
+  value: string | null;
+  onValueChange: (topic: string | null) => void;
+  /** Owners and admins (`canManageTopics(role)`): the options button. */
+  canManage?: boolean;
+  /** Saves a topic (`useTopics().setTopic`). */
+  onSetTopic?: (topic: string, input: TopicInput) => Promise<void>;
+  testID?: string;
+}
+
+type SheetState = { step: "menu" } | { step: "name"; renaming: string | null };
+
+export function ChatTopicBar({ topics, value, onValueChange, canManage = false, onSetTopic, testID = "chat-topics" }: ChatTopicBarProps) {
+  const { copy } = useChatNative();
+  const colors = useThemeRoles();
+  const toast = useToast();
+  const [sheet, setSheet] = useState<SheetState | null>(null);
+  const [title, setTitle] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const current = value ? (topics.find((t) => t.topic === value) ?? null) : null;
+
+  const close = () => {
+    if (busy) return;
+    setSheet(null);
+    setError(null);
+  };
+
+  const run = async (action: TopicMenuAction) => {
+    if (action === "new" || action === "rename") {
+      setTitle(action === "rename" ? (current?.title ?? "") : "");
+      setError(null);
+      setSheet({ step: "name", renaming: action === "rename" ? (current?.topic ?? null) : null });
+      return;
+    }
+    if (!current || !onSetTopic) return;
+    setSheet(null);
+    try {
+      await onSetTopic(current.topic, { closed: action === "close" });
+      toast.show({ title: fill(action === "close" ? copy.topicClosedDone : copy.topicReopenedDone, { name: current.title }), variant: "success", duration: 1500 });
+    } catch (e) {
+      toast.show({ title: e instanceof Error ? e.message : copy.actionFailed, variant: "destructive" });
+    }
+  };
+
+  const save = async (renaming: string | null) => {
+    if (!onSetTopic) return;
+    const checked = checkTopicName(title, topics, renaming);
+    if ("error" in checked) {
+      setError(checked.error === "exists" ? copy.topicExists : null);
+      return;
+    }
+    setBusy(true);
+    try {
+      await onSetTopic(checked.key, renaming ? { title: title.trim() } : { title: title.trim(), position: topics.length });
+      setSheet(null);
+      setTitle("");
+      if (!renaming) onValueChange(checked.key);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : copy.actionFailed);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <View testID={testID} style={{ flexDirection: "row", alignItems: "center", backgroundColor: colors.groupedBackground, paddingLeft: 8 }}>
+      <ScrollView horizontal showsHorizontalScrollIndicator={false} accessibilityLabel={copy.topics} contentContainerStyle={{ paddingVertical: 4, paddingRight: 8 }} style={{ flex: 1 }}>
+        <NativeChipGroup mode="single" value={value ?? ALL} onChange={(v) => onValueChange(v === ALL ? null : (v as string))} className="flex-nowrap" testID={`${testID}-group`}>
+          <NativeChip value={ALL} testID={`${testID}-all`}>
+            {copy.topicAll}
+          </NativeChip>
+          {topics.map((t) => (
+            <NativeChip key={t.topic} value={t.topic} testID={`${testID}-${t.topic}`}>
+              <View style={{ flexDirection: "row", alignItems: "center", gap: 4 }}>
+                {t.closedAt ? <NativeIcon name="lock" size={13} color={colors.secondaryLabel} label={copy.topicClosed} /> : null}
+                <NativeText preset="body-sm" numberOfLines={1} style={{ maxWidth: 180, fontWeight: value === t.topic ? "600" : "400", color: value === t.topic ? colors.tint : colors.label }}>
+                  {t.title}
+                </NativeText>
+              </View>
+            </NativeChip>
+          ))}
+        </NativeChipGroup>
+      </ScrollView>
+      {canManage && onSetTopic ? <ChatIconButton testID={`${testID}-menu`} icon="more" label={copy.topicOptions} onPress={() => setSheet({ step: "menu" })} /> : null}
+      <NativeSheet open={sheet !== null} onOpenChange={(o) => (o ? undefined : close())} testID={`${testID}-sheet`}>
+        {sheet?.step === "name" ? (
+          <View style={{ padding: 16, gap: 12 }}>
+            <NativeText preset="h4" accessibilityRole="header">
+              {sheet.renaming ? copy.topicRename : copy.topicNew}
+            </NativeText>
+            <NativeInput
+              testID={`${testID}-name`}
+              label={copy.topicName}
+              value={title}
+              onChangeText={(v) => {
+                setTitle(v);
+                setError(null);
+              }}
+              placeholder={copy.topicNamePlaceholder}
+              maxLength={160}
+              autoFocus
+              returnKeyType="done"
+              onSubmitEditing={() => void save(sheet.renaming)}
+              error={error ?? undefined}
+            />
+            <NativeButton testID={`${testID}-save`} onPress={() => void save(sheet.renaming)} loading={busy} disabled={!title.trim()}>
+              {sheet.renaming ? copy.topicSave : copy.topicAdd}
+            </NativeButton>
+          </View>
+        ) : (
+          <View>
+            {topicMenuFor(current).map((action) => (
+              <NativeListItem
+                key={action}
+                testID={`${testID}-${action}`}
+                title={action === "new" ? copy.topicNew : action === "rename" ? copy.topicRename : action === "close" ? copy.topicClose : copy.topicReopen}
+                leading={<NativeIcon name={action === "new" ? "plus" : action === "rename" ? "edit" : "lock"} />}
+                onPress={() => void run(action)}
+              />
+            ))}
+          </View>
+        )}
+      </NativeSheet>
+    </View>
+  );
+}

package/src/native/tus.ts

@@ -0,0 +1,282 @@
+/**
+ * @feat:chat
+ * Resumable uploads for the native outbox: Supabase Storage's TUS endpoint
+ * (`/storage/v1/upload/resumable`), with the person's own token, so storage's
+ * row level security (genesis_chat.can_upload) judges each file as it does a
+ * plain upload. A dropped connection resumes from the last chunk the server
+ * has (HEAD for the offset), within the session; a retry of the same file
+ * reuses its path, so the message's attachment never points at a second copy.
+ * A file on the phone is read one chunk at a time when the app gives
+ * `openFile` (a 100 MB video never sits whole in memory); without it, it is
+ * read whole. A create the server refuses as already there (409) counts as
+ * done only when the object is really there.
+ *
+ *   <ChatProvider upload={createTusUpload({ supabaseUrl, userId, getAccessToken })} …>
+ *
+ * The path is `<conversation>/<uploader>/<uuid>.<ext>`, as `send_message`
+ * expects; the upload finishes before the send (the outbox orders that).
+ */
+import { CHAT_BUCKET, ChatError } from "../core/client";
+import { fileExtension, isAllowedExtension, randomId } from "../core/media";
+import type { LocalFile } from "../core/outbox";
+
+/** Supabase requires 6 MB chunks for TUS (every chunk but the last). */
+export const TUS_CHUNK_BYTES = 6 * 1024 * 1024;
+
+export interface TusUploadOptions {
+  /** The project URL (`https://<ref>.supabase.co`, or the local stack's). */
+  supabaseUrl: string;
+  /** The signed-in user's id (auth.users), the second folder of the path. */
+  userId: string | (() => string);
+  /** The signed-in user's access token (`(await supabase.auth.getSession()).data.session?.access_token`). */
+  getAccessToken: () => Promise<string | null | undefined>;
+  /** The publishable key, sent as `apikey` (the API gateway asks for it on hosted projects). */
+  apikey?: string;
+  /**
+   * Opens a file URI for reading one chunk at a time (expo-file-system's `new File(uri).open()`),
+   * so a big video is never read whole into memory. Without it, `readFile` reads the whole file.
+   */
+  openFile?: (uri: string) => Promise<TusFileHandle> | TusFileHandle;
+  /** Reads a file URI into bytes, whole: used without `openFile`. Default `fetch(uri).arrayBuffer()`. */
+  readFile?: (uri: string) => Promise<ArrayBuffer>;
+  fetch?: typeof fetch;
+  chunkBytes?: number;
+  /** Network failures retried per chunk before the send fails (it can be retried). Default 3. */
+  retries?: number;
+  /** A uuid for each file's name. Default core's `randomId` (crypto.randomUUID where there is one, else getRandomValues). */
+  newId?: () => string;
+  bucket?: string;
+}
+
+/** An open file, read a chunk at a time. */
+export interface TusFileHandle {
+  /** Bytes in the file. */
+  size: number;
+  /** Up to `length` bytes from `offset`. */
+  read(offset: number, length: number): Promise<ArrayBuffer | Uint8Array>;
+  close?(): void;
+}
+
+/** What upload reads its bytes from: the file in chunks, or bytes already in memory. */
+interface Source {
+  size: number;
+  read(from: number, to: number): Promise<ArrayBuffer>;
+  close(): void;
+}
+
+const exact = (bytes: ArrayBuffer | Uint8Array): ArrayBuffer =>
+  bytes instanceof ArrayBuffer ? bytes : (bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer);
+
+const inMemory = (buffer: ArrayBuffer): Source => ({ size: buffer.byteLength, read: async (from, to) => buffer.slice(from, to), close: () => undefined });
+
+interface UploadRecord {
+  path: string;
+  location?: string;
+  done?: boolean;
+}
+
+/** Base64 of a UTF-8 string, for TUS's Upload-Metadata (no `btoa`, which isn't on every Hermes build). */
+export function base64Utf8(text: string): string {
+  const bytes = new TextEncoder().encode(text);
+  const A = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const n = (bytes[i]! << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+    out += A[(n >> 18) & 63]! + A[(n >> 12) & 63]! + (i + 1 < bytes.length ? A[(n >> 6) & 63]! : "=") + (i + 2 < bytes.length ? A[n & 63]! : "=");
+  }
+  return out;
+}
+
+const transientStatus = (status: number) => status === 0 || status === 408 || status === 429 || status >= 500;
+
+export function createTusUpload(options: TusUploadOptions): (conversationId: string, file: LocalFile) => Promise<string> {
+  const doFetch = options.fetch ?? fetch;
+  const chunk = options.chunkBytes ?? TUS_CHUNK_BYTES;
+  const retries = options.retries ?? 3;
+  const bucket = options.bucket ?? CHAT_BUCKET;
+  const endpoint = `${options.supabaseUrl.replace(/\/+$/, "")}/storage/v1/upload/resumable`;
+  const newId = options.newId ?? randomId;
+  const readFile = options.readFile ?? (async (uri: string) => (await doFetch(uri)).arrayBuffer());
+  // By file object: a retry of the same message in this session resumes it. Two messages never
+  // share an object, so deleting one never breaks the other.
+  const byFile = new WeakMap<LocalFile, UploadRecord>();
+
+  async function headers(extra: Record<string, string> = {}) {
+    const token = await options.getAccessToken();
+    if (!token) throw new ChatError("Sign in to send files", "42501", "upload");
+    return {
+      authorization: `Bearer ${token}`,
+      ...(options.apikey ? { apikey: options.apikey } : {}),
+      "tus-resumable": "1.0.0",
+      ...extra,
+    };
+  }
+
+  async function sourceOf(file: LocalFile): Promise<Source> {
+    const data = file.data;
+    if (typeof data === "string") {
+      if (!options.openFile) return inMemory(await readFile(data));
+      const handle = await options.openFile(data);
+      if (!Number.isFinite(handle.size) || handle.size <= 0) {
+        try {
+          handle.close?.();
+        } catch {
+          // Already closed.
+        }
+        throw new ChatError(`${file.name} can't be read on this device`, "22023", "upload");
+      }
+      return {
+        size: handle.size,
+        read: async (from, to) => {
+          const bytes = await handle.read(from, to - from).catch((e: unknown) => {
+            throw new ChatError(`${file.name} can't be read on this device${e instanceof Error ? `: ${e.message}` : ""}`, "22023", "upload");
+          });
+          // A short read would send a hole in the file: fail instead.
+          if (bytes.byteLength !== to - from) throw new ChatError(`${file.name} changed while it was sent`, "22023", "upload");
+          return exact(bytes);
+        },
+        close: () => {
+          try {
+            handle.close?.();
+          } catch {
+            // Already closed.
+          }
+        },
+      };
+    }
+    if (data instanceof ArrayBuffer) return inMemory(data);
+    return { size: data.size, read: (from, to) => data.slice(from, to).arrayBuffer(), close: () => undefined };
+  }
+
+  /**
+   * Whether the object is really in the bucket (a 409 on create says so, and may be wrong).
+   * Storage answers a missing object with 400 (or 404); a refusal is a refusal, anything else is
+   * asked again.
+   */
+  async function objectExists(path: string): Promise<boolean> {
+    const base = options.supabaseUrl.replace(/\/+$/, "");
+    const encoded = path.split("/").map(encodeURIComponent).join("/");
+    const res = await doFetch(`${base}/storage/v1/object/authenticated/${bucket}/${encoded}`, { method: "HEAD", headers: await headers() });
+    if (res.ok) return true;
+    if (res.status === 400 || res.status === 404) return false;
+    return refuse(res, "upload");
+  }
+
+  async function withRetry<T>(op: string, run: () => Promise<T>): Promise<T> {
+    let last: unknown;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        return await run();
+      } catch (e) {
+        last = e;
+        if (e instanceof ChatError && !e.transient) throw e;
+        await new Promise((r) => setTimeout(r, Math.min(4000, 250 * 2 ** attempt)));
+      }
+    }
+    throw last instanceof ChatError ? last : new ChatError(last instanceof Error ? last.message : String(last), undefined, op);
+  }
+
+  const refuse = async (res: Response, op: string): Promise<never> => {
+    const text = await res.text().catch(() => "");
+    // A network-ish status is transient (no code); the rest are refusals.
+    throw new ChatError(text || `Upload failed (${res.status})`, transientStatus(res.status) ? undefined : res.status === 403 || res.status === 401 ? "42501" : "22023", op);
+  };
+
+  async function upload(conversationId: string, file: LocalFile): Promise<string> {
+    const ext = fileExtension(file.name, file.contentType);
+    if (!isAllowedExtension(ext)) throw new ChatError(`Files of type .${ext} can't be sent`, "22023", "upload");
+    let record = byFile.get(file);
+    if (!record) {
+      const userId = typeof options.userId === "function" ? options.userId() : options.userId;
+      record = { path: `${conversationId}/${userId}/${newId()}.${ext}` };
+    }
+    byFile.set(file, record);
+    if (record.done) return record.path;
+
+    const source = await sourceOf(file);
+    try {
+      return await send(file, record, source);
+    } finally {
+      source.close();
+    }
+  };
+
+  async function send(file: LocalFile, rec: UploadRecord, source: Source): Promise<string> {
+    const length = source.size;
+
+    // Create the upload (once), or find how far an earlier attempt got.
+    let offset = 0;
+    if (rec.location) {
+      offset = await withRetry("upload", async () => {
+        const res = await doFetch(rec.location!, { method: "HEAD", headers: await headers() });
+        if (res.status === 404 || res.status === 410) {
+          rec.location = undefined;
+          return 0;
+        }
+        if (!res.ok) return refuse(res, "upload");
+        return Number(res.headers.get("upload-offset") ?? 0);
+      });
+    }
+    // A 409 at a path whose object isn't there (another upload of it never finished): one new path.
+    let fresh = false;
+    while (!rec.location) {
+      const metadata = [
+        `bucketName ${base64Utf8(bucket)}`,
+        `objectName ${base64Utf8(rec.path)}`,
+        `contentType ${base64Utf8(file.contentType)}`,
+        `cacheControl ${base64Utf8("3600")}`,
+      ].join(",");
+      const created = await withRetry("upload", async () => {
+        const res = await doFetch(endpoint, {
+          method: "POST",
+          headers: await headers({ "upload-length": String(length), "upload-metadata": metadata, "x-upsert": "false" }),
+        });
+        // Already there, says the server: an earlier attempt finished but its answer was lost, or
+        // another upload of this path is under way. Only the object itself settles which.
+        if (res.status === 409) return (await objectExists(rec.path)) ? "done" : "conflict";
+        if (res.status !== 201) return refuse(res, "upload");
+        const location = res.headers.get("location");
+        if (!location) throw new ChatError("The upload server gave no location", "22023", "upload");
+        return new URL(location, endpoint).toString();
+      });
+      if (created === "done") {
+        rec.done = true;
+        return rec.path;
+      }
+      if (created === "conflict") {
+        if (fresh) throw new ChatError("The upload is out of step", undefined, "upload");
+        fresh = true;
+        rec.path = `${rec.path.slice(0, rec.path.lastIndexOf("/") + 1)}${newId()}.${rec.path.slice(rec.path.lastIndexOf(".") + 1)}`;
+        continue;
+      }
+      rec.location = created;
+      offset = 0;
+    }
+
+    while (offset < length) {
+      const from = offset;
+      const body = await source.read(from, Math.min(length, from + chunk));
+      offset = await withRetry("upload", async () => {
+        const res = await doFetch(rec.location!, {
+          method: "PATCH",
+          headers: await headers({ "upload-offset": String(from), "content-type": "application/offset+octet-stream" }),
+          body,
+        });
+        if (res.status === 409) {
+          // Out of step (an earlier chunk did land): ask where the server is.
+          const head = await doFetch(rec.location!, { method: "HEAD", headers: await headers() });
+          const at = Number(head.headers.get("upload-offset"));
+          // No answer: a transient failure, so the backoff applies before the next try.
+          if (!head.ok || !Number.isFinite(at) || at === from) throw new ChatError("The upload is out of step", undefined, "upload");
+          return at;
+        }
+        if (res.status !== 204 && !res.ok) return refuse(res, "upload");
+        return Number(res.headers.get("upload-offset") ?? from + body.byteLength);
+      });
+    }
+    rec.done = true;
+    return rec.path;
+  }
+
+  return upload;
+}

package/src/native/use-composer.ts

@@ -0,0 +1,71 @@
+/**
+ * @feat:chat
+ * The composer's state for one thread, with its draft (per signed-in person):
+ * restored when the thread opens, saved a moment after typing stops and when
+ * the screen closes or moves to another thread, cleared on send. The thread screen owns it, so a swipe or the long-press
+ * sheet can set what the next message replies to.
+ */
+import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
+import { composerReducer, createDraftSaver, draftKey, emptyComposer, loadDraft, memoryDraftStorage, toSend, type ComposerAction, type ComposerState, type ReplyTarget } from "./composer-state";
+import { useChatNative } from "./context";
+
+const memoryDrafts = memoryDraftStorage();
+
+/** `userId` is the signed-in person's (`useChat().userId`): drafts are kept per person. */
+export function useChatComposer(conversationId: string, threadRootId: string | null | undefined, userId: string) {
+  const { modules } = useChatNative();
+  const storage = modules.drafts ?? memoryDrafts;
+  const key = draftKey(userId, conversationId, threadRootId);
+  const [state, dispatch] = useReducer(composerReducer, emptyComposer);
+  const saver = useMemo(() => createDraftSaver(storage, key), [storage, key]);
+  const restored = useRef<string | null>(null);
+  // The key the state belongs to. Another conversation in the same screen starts empty, so one
+  // thread's text, reply or files never show, save or send in the next (the draft flushed for the
+  // old key first, in the cleanup below).
+  // Kept in state, not a ref written during render (React's "storing information from previous
+  // renders"): a render React drops would leave a ref on the new key with the reset never applied.
+  const [stateKey, setStateKey] = useState(key);
+  if (stateKey !== key) {
+    setStateKey(key);
+    dispatch({ type: "reset" });
+  }
+
+  useEffect(() => {
+    let live = true;
+    restored.current = null;
+    void loadDraft(storage, key).then((draft) => {
+      if (!live) return;
+      if (draft) dispatch({ type: "restore", draft });
+      // Only this key's own load: a late answer for a thread left behind must not stop this one saving.
+      restored.current = key;
+    });
+    return () => {
+      live = false;
+      saver.flush();
+    };
+  }, [storage, key, saver]);
+
+  useEffect(() => {
+    // Don't overwrite the stored draft with the empty state before it has been read.
+    if (restored.current !== key) return;
+    saver.save({ text: state.text, replyTo: state.replyTo });
+  }, [state.text, state.replyTo, saver, key]);
+
+  const setReply = useCallback((to: ReplyTarget | null) => dispatch({ type: "reply", to }), []);
+
+  // A second tap before the re-render must not send the same message again.
+  const taken = useRef<ComposerState | null>(null);
+  /** What to send (null when this state was already sent), and empties the composer and its draft. */
+  const take = useCallback(() => {
+    if (taken.current === state) return null;
+    taken.current = state;
+    const payload = toSend(state);
+    dispatch({ type: "sent" });
+    saver.clear();
+    return payload;
+  }, [state, saver]);
+
+  return { state, dispatch: dispatch as (action: ComposerAction) => void, setReply, take };
+}
+
+export type ChatComposerHandle = ReturnType<typeof useChatComposer>;

package/src/native/use-jump.ts

@@ -0,0 +1,91 @@
+/**
+ * @feat:chat
+ * Going to one message in a thread (a search result, a pinned message): earlier pages load until
+ * it is held (`useConversation().loadUntil(seq)`), then the list scrolls to it and it is
+ * highlighted for two seconds. A message that can't be found (deleted, or out of reach) says so.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { ThreadRow } from "./rows";
+
+export interface JumpTarget {
+  messageId: string;
+  seq?: number;
+}
+
+/** The row a message is drawn in, or -1. */
+export function rowIndexOf(rows: readonly ThreadRow[], messageId: string): number {
+  return rows.findIndex((r) => r.type === "message" && r.item.type === "message" && r.item.message.id === messageId);
+}
+
+export interface UseJumpOptions {
+  /** What to go to; a new target (another id or seq) starts again. */
+  target: JumpTarget | null | undefined;
+  rows: readonly ThreadRow[];
+  /** The thread's first page is still loading. */
+  loading: boolean;
+  has: (messageId: string) => boolean;
+  loadUntil: (seq: number) => Promise<boolean>;
+  /** Scroll the list to this row (centred); the message id, for a retry once rows have moved. */
+  scrollTo: (index: number, messageId: string) => void;
+  /** Called before loading or scrolling (stop following the bottom). */
+  onStart?: () => void;
+  /** It was scrolled to (say so to VoiceOver). */
+  onLanded?: (messageId: string) => void;
+  /** It isn't there any more (go back to where the thread was). */
+  onGone: () => void;
+  onError: (e: unknown) => void;
+}
+
+type Pending = JumpTarget & { phase: "new" | "loading" | "loaded" };
+
+export function useJumpToMessage({ target, rows, loading, has, loadUntil, scrollTo, onStart, onLanded, onGone, onError }: UseJumpOptions) {
+  const [pending, setPending] = useState<Pending | null>(target ? { ...target, phase: "new" } : null);
+  const [highlightedId, setHighlightedId] = useState<string | null>(null);
+  useEffect(() => {
+    if (target) setPending({ ...target, phase: "new" });
+  }, [target?.messageId, target?.seq]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const latest = useRef({ rows, scrollTo, onStart, onLanded, onGone, onError });
+  latest.current = { rows, scrollTo, onStart, onLanded, onGone, onError };
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => () => {
+    if (timer.current) clearTimeout(timer.current);
+  }, []);
+
+  const go = useCallback((messageId: string) => {
+    const index = rowIndexOf(latest.current.rows, messageId);
+    if (index < 0) return;
+    latest.current.onStart?.();
+    latest.current.scrollTo(index, messageId);
+    latest.current.onLanded?.(messageId);
+    setHighlightedId(messageId);
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => setHighlightedId((h) => (h === messageId ? null : h)), 2000);
+  }, []);
+
+  useEffect(() => {
+    if (!pending || loading) return;
+    const { messageId, seq, phase } = pending;
+    if (has(messageId)) {
+      setPending(null);
+      go(messageId);
+      return;
+    }
+    if (phase === "loading") return;
+    if (phase === "loaded" || seq == null) {
+      setPending(null);
+      latest.current.onGone();
+      return;
+    }
+    latest.current.onStart?.();
+    setPending({ messageId, seq, phase: "loading" });
+    const settle = () => setPending((p) => (p && p.messageId === messageId ? { ...p, phase: "loaded" } : p));
+    void loadUntil(seq).then(settle, (e) => {
+      latest.current.onError(e);
+      // Not found after all: the "loaded" step says so and puts the thread back.
+      settle();
+    });
+  }, [pending, loading, has, loadUntil, go]);
+
+  return { highlightedId, jumping: pending !== null };
+}