letagents 0.12.34 → 0.12.35

package/shared/message-reaction-store.mjs

@@ -0,0 +1,290 @@
+// The client-side state of a room's reactions, shared by the desktop and web
+// apps. It is framework-free: the app supplies the two API calls and is told
+// when something changed.
+//
+// A message on screen registers itself with `track`. Its reactions start from
+// what the message carried when it was read, so nothing shifts as the room
+// opens, and are then confirmed by a read of the server: shortly after a
+// message is first tracked, and whenever the app calls `refresh` because the
+// room reported a `message_reactions` invalidation or its stream reconnected.
+import {
+  MESSAGE_REACTION_RANGE_MAX_SPAN,
+  normalizeMessageReactionEmoji,
+  normalizeMessageReactions,
+  toggleViewerMessageReaction,
+  viewerReactedWith,
+} from "./message-reactions.mjs";
+
+const NONE = Object.freeze([]);
+
+function messageNumber(id) {
+  const match = /^msg_([1-9]\d*)$/.exec(typeof id === "string" ? id : "");
+  return match ? Number(match[1]) : null;
+}
+
+function sameReactions(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+/** Split sorted message numbers into runs the server will read in one request. */
+function spans(numbers) {
+  const runs = [];
+  for (const number of numbers) {
+    const run = runs.at(-1);
+    if (run && number - run.first < MESSAGE_REACTION_RANGE_MAX_SPAN) run.last = number;
+    else runs.push({ first: number, last: number });
+  }
+  return runs;
+}
+
+export function createMessageReactionStore({ load, mutate, viewer, onChange, onError, refreshDelayMs = 50 }) {
+  let reactions = new Map();
+  // Which emoji the viewer reacted with, per message, once the server said so.
+  // Until then the listed reactors answer, which can miss a viewer past the cap.
+  let viewerEmoji = new Map();
+  // Messages whose own `reactions` were already taken; a later copy of the
+  // same message may be older than what a read has since learned.
+  let seeded = new Set();
+  // One chain of toggles per message, so rapid clicks reach the server in order.
+  let pending = new Map();
+  // Messages on screen: id -> the message and one token per registration.
+  let tracked = new Map();
+  // Orders the viewer's own changes against reads that began before them.
+  let mutationSeq = 0;
+  let lastMutation = new Map();
+  // Answers on their way are dropped when `epoch` moves; registrations made
+  // before `trackingEpoch` moved no longer own anything.
+  let epoch = 0;
+  let trackingEpoch = 0;
+  let refreshing = null;
+  let refreshTimer = null;
+
+  function store(messageId, next) {
+    if (sameReactions(reactions.get(messageId) ?? NONE, next)) return false;
+    if (next.length) reactions.set(messageId, next);
+    else reactions.delete(messageId);
+    return true;
+  }
+
+  function get(messageId) {
+    return reactions.get(messageId) ?? NONE;
+  }
+
+  function viewerReacted(messageId, emoji) {
+    const known = viewerEmoji.get(messageId);
+    if (known) return known.has(emoji);
+    return viewerReactedWith(get(messageId).find((reaction) => reaction.emoji === emoji), viewer()?.login);
+  }
+
+  function seed(message) {
+    const id = message?.id;
+    if (messageNumber(id) === null || seeded.has(id)) return false;
+    seeded.add(id);
+    if (pending.has(id)) return false;
+    return store(id, normalizeMessageReactions(message.reactions));
+  }
+
+  function scheduleRefresh() {
+    if (refreshTimer !== null) return;
+    refreshTimer = setTimeout(() => {
+      refreshTimer = null;
+      void refresh();
+    }, refreshDelayMs);
+  }
+
+  /**
+   * A rendered message registers itself; the returned function unregisters it.
+   * The first registration of a message also asks the server, a moment later
+   * and together with every other message registered meanwhile: the copy on
+   * screen may predate a change that happened while the message was not shown.
+   */
+  function track(message) {
+    const id = message?.id;
+    if (messageNumber(id) === null) return () => {};
+    const registeredIn = trackingEpoch;
+    const token = Symbol("tracked");
+    const entry = tracked.get(id);
+    if (entry) {
+      entry.tokens.add(token);
+      entry.message = message;
+    } else {
+      tracked.set(id, { message, tokens: new Set([token]) });
+      if (seed(message)) onChange?.();
+      scheduleRefresh();
+    }
+    return () => {
+      if (registeredIn !== trackingEpoch) return;
+      const current = tracked.get(id);
+      if (!current?.tokens.delete(token) || current.tokens.size > 0) return;
+      tracked.delete(id);
+    };
+  }
+
+  async function readSpan(first, last, startedIn, startedAtMutation) {
+    let from = first;
+    // Every continuation advances within a span of at most 1,000 messages.
+    // An arbitrary page cap would permanently starve dense ranges' tails.
+    while (from <= last) {
+      let changed = false;
+      const read = await load(`msg_${from}`, `msg_${last}`);
+      // The room changed while this read was in flight.
+      if (startedIn !== epoch) return;
+      const byMessage = read?.reactions && typeof read.reactions === "object" ? read.reactions : {};
+      const viewerByMessage = read?.viewer_reactions && typeof read.viewer_reactions === "object"
+        ? read.viewer_reactions
+        : null;
+      // A read the server cut short is complete only below the message it names.
+      const next = messageNumber(read?.next_first_message_id);
+      const completeBelow = next !== null && next > from ? next : last + 1;
+      for (const [id] of tracked) {
+        const number = messageNumber(id);
+        if (number < from || number >= completeBelow) continue;
+        // The viewer changed this message after the read began: the read is older.
+        if (pending.has(id) || (lastMutation.get(id) ?? 0) > startedAtMutation) continue;
+        seeded.add(id);
+        if (store(id, normalizeMessageReactions(byMessage[id]))) changed = true;
+        if (viewerByMessage) {
+          const mine = new Set((Array.isArray(viewerByMessage[id]) ? viewerByMessage[id] : [])
+            .map(normalizeMessageReactionEmoji)
+            .filter(Boolean));
+          const known = viewerEmoji.get(id);
+          if (!known || known.size !== mine.size || [...mine].some((emoji) => !known.has(emoji))) changed = true;
+          viewerEmoji.set(id, mine);
+        }
+      }
+      // Publish completed pages even if a later page fails or is slow.
+      if (changed) onChange?.();
+      if (next === null || next <= from) break;
+      from = next;
+    }
+  }
+
+  /**
+   * Re-read the reactions of every message on screen. Calls made while a read
+   * is in flight collapse into one follow-up read.
+   */
+  function refresh() {
+    if (refreshTimer !== null) {
+      clearTimeout(refreshTimer);
+      refreshTimer = null;
+    }
+    if (refreshing) {
+      refreshing.again = true;
+      return refreshing.promise;
+    }
+    const startedIn = epoch;
+    const cycle = { again: false, promise: null };
+    refreshing = cycle;
+    cycle.promise = (async () => {
+      do {
+        cycle.again = false;
+        const startedAtMutation = mutationSeq;
+        const numbers = Array.from(tracked.keys(), messageNumber).sort((left, right) => left - right);
+        try {
+          for (const span of spans(numbers)) {
+            if (startedIn !== epoch) break;
+            await readSpan(span.first, span.last, startedIn, startedAtMutation);
+          }
+        } catch (error) {
+          // Keep what is shown; the next invalidation reads again.
+          if (startedIn === epoch) onError?.(error, "load");
+        }
+      } while (cycle.again && startedIn === epoch);
+    })().finally(() => {
+      if (refreshing === cycle) refreshing = null;
+    });
+    return cycle.promise;
+  }
+
+  /** Add the viewer's reaction, or remove it if it is already there. */
+  function toggle(messageId, emoji) {
+    const person = viewer();
+    if (!person || messageNumber(messageId) === null) return Promise.resolve();
+    const startedIn = epoch;
+
+    const run = async () => {
+      if (startedIn !== epoch) return;
+      const before = get(messageId);
+      const mineBefore = viewerEmoji.get(messageId);
+      const listed = viewerReactedWith(before.find((reaction) => reaction.emoji === emoji), person.login);
+      const reacted = mineBefore ? mineBefore.has(emoji) : listed;
+      // A viewer the list does not name can only lower or raise the count.
+      const optimistic = reacted === listed
+        ? toggleViewerMessageReaction(before, emoji, person)
+        : before
+          .map((reaction) => (reaction.emoji === emoji ? { ...reaction, count: reaction.count + (reacted ? -1 : 1) } : reaction))
+          .filter((reaction) => reaction.count > 0);
+      const mineOptimistic = new Set(mineBefore ?? before
+        .filter((reaction) => viewerReactedWith(reaction, person.login))
+        .map((reaction) => reaction.emoji));
+      if (reacted) mineOptimistic.delete(emoji);
+      else mineOptimistic.add(emoji);
+
+      lastMutation.set(messageId, ++mutationSeq);
+      store(messageId, optimistic);
+      viewerEmoji.set(messageId, mineOptimistic);
+      onChange?.();
+      try {
+        const result = await mutate(messageId, emoji, !reacted);
+        if (startedIn !== epoch) return;
+        lastMutation.set(messageId, ++mutationSeq);
+        seeded.add(messageId);
+        // The server's list may hold what others did meanwhile; whether the
+        // viewer reacted is exactly what was just asked for.
+        store(messageId, normalizeMessageReactions(result?.reactions));
+        onChange?.();
+        // An invalidation read may have been skipped while this write was
+        // pending. Confirm all viewer emoji too (another tab may change them).
+        scheduleRefresh();
+      } catch (error) {
+        if (startedIn !== epoch) return;
+        lastMutation.set(messageId, ++mutationSeq);
+        store(messageId, before);
+        if (mineBefore) viewerEmoji.set(messageId, mineBefore);
+        else viewerEmoji.delete(messageId);
+        onChange?.();
+        onError?.(error, "mutate");
+        // A read that landed during the attempt was skipped for this message.
+        scheduleRefresh();
+      }
+    };
+
+    const queued = (pending.get(messageId) ?? Promise.resolve()).then(run);
+    const settled = queued.finally(() => {
+      if (pending.get(messageId) === settled) pending.delete(messageId);
+    });
+    pending.set(messageId, settled);
+    return settled;
+  }
+
+  /**
+   * Forget everything. With `keepTracked`, the messages on screen stay
+   * registered and start again from what they carried (the signed-in person
+   * changed); without it they are dropped too (the room changed).
+   */
+  function reset({ keepTracked = false } = {}) {
+    const hadAny = reactions.size > 0 || viewerEmoji.size > 0;
+    // Answers on their way belong to the previous room or person.
+    epoch += 1;
+    // A stalled old-room read must not delay the next room or viewer. Its
+    // eventual cleanup owns only its own cycle, never the new refresh.
+    refreshing = null;
+    reactions = new Map();
+    viewerEmoji = new Map();
+    seeded = new Set();
+    lastMutation = new Map();
+    pending = new Map();
+    if (refreshTimer !== null) clearTimeout(refreshTimer);
+    refreshTimer = null;
+    if (keepTracked) {
+      for (const entry of tracked.values()) seed(entry.message);
+      if (tracked.size) scheduleRefresh();
+    } else {
+      trackingEpoch += 1;
+      tracked = new Map();
+    }
+    if (hadAny || tracked.size) onChange?.();
+  }
+
+  return { get, viewerReacted, track, refresh, toggle, reset };
+}

package/shared/message-reactions.d.mts

@@ -0,0 +1,73 @@
+export const MESSAGE_REACTION_EMOJI_MAX_BYTES: 64;
+export const MESSAGE_REACTION_MAX_DISTINCT_PER_MESSAGE: 20;
+/** A reaction always reports its exact count; only the named reactors are capped. */
+export const MESSAGE_REACTION_MAX_REACTORS_LISTED: 50;
+/** One range read covers at most this many message numbers. */
+export const MESSAGE_REACTION_RANGE_MAX_SPAN: 1000;
+/** One range read returns at most this many reactor rows before it stops and names where to continue. */
+export const MESSAGE_REACTION_MAX_PER_READ: 2000;
+export const MESSAGE_REACTION_QUICK_EMOJI: readonly string[];
+
+/** Public identity only; account ids stay internal. */
+export interface MessageReactor {
+  login: string;
+  name: string;
+  avatar_url: string | null;
+}
+
+export interface MessageReaction {
+  emoji: string;
+  /** Exact number of people who reacted with this emoji. */
+  count: number;
+  /** Earliest first, at most MESSAGE_REACTION_MAX_REACTORS_LISTED. */
+  reactors: MessageReactor[];
+}
+
+/** `GET /rooms/:room/messages/reactions` */
+export interface MessageReactionsRangeResponse {
+  room_id: string;
+  first_message_id: string;
+  last_message_id: string;
+  /** Only messages that have at least one reaction appear. */
+  reactions: Record<string, MessageReaction[]>;
+  /**
+   * The emoji the signed-in caller reacted with, per message. Present only
+   * for a person's session; exact even where `reactors` is capped.
+   */
+  viewer_reactions?: Record<string, string[]>;
+  /**
+   * Null when the whole range was read. Otherwise the read stopped early:
+   * it is complete below this message, and continues from it.
+   */
+  next_first_message_id: string | null;
+}
+
+/** `PUT` and `DELETE /rooms/:room/messages/:message/reactions/:emoji` */
+export interface MessageReactionMutationResponse {
+  room_id: string;
+  message_id: string;
+  emoji: string;
+  /** False when the request repeated a reaction the viewer already had (or had already removed). */
+  changed: boolean;
+  reactions: MessageReaction[];
+}
+
+/** The canonical form of one emoji, or null when the value is anything else. */
+export function normalizeMessageReactionEmoji(value: unknown): string | null;
+/** Read a server reaction list defensively; malformed entries are dropped. */
+export function normalizeMessageReactions(value: unknown): MessageReaction[];
+export function viewerReactedWith(
+  reaction: Pick<MessageReaction, "reactors"> | null | undefined,
+  viewerLogin: string | null | undefined,
+): boolean;
+/** "You, Ada and 3 others reacted with 👍" */
+export function describeMessageReaction(
+  reaction: MessageReaction,
+  viewerLogin: string | null | undefined,
+): string;
+/** The reaction list after the viewer toggles one emoji, for an optimistic update. */
+export function toggleViewerMessageReaction(
+  reactions: readonly MessageReaction[] | null | undefined,
+  emoji: string,
+  viewer: MessageReactor,
+): MessageReaction[];

package/shared/message-reactions.mjs

@@ -0,0 +1,130 @@
+// Emoji reactions on room messages: the limits, the quick palette and the one
+// validation rule that the server and both clients share.
+
+export const MESSAGE_REACTION_EMOJI_MAX_BYTES = 64;
+export const MESSAGE_REACTION_MAX_DISTINCT_PER_MESSAGE = 20;
+// A reaction always reports its exact count; only the named reactors are capped.
+export const MESSAGE_REACTION_MAX_REACTORS_LISTED = 50;
+// One range read covers at most this many message numbers, and returns at most
+// this many reactor rows before it stops and names where to continue.
+export const MESSAGE_REACTION_RANGE_MAX_SPAN = 1000;
+export const MESSAGE_REACTION_MAX_PER_READ = 2000;
+
+export const MESSAGE_REACTION_QUICK_EMOJI = Object.freeze([
+  "👍", "👎", "✅", "❌", "👀", "🙏", "🎉", "🚀",
+  "❤️", "😂", "🤔", "😅", "🔥", "💯", "👏", "🙌",
+  "🤝", "⚠️", "🐛", "🔧", "📌", "⏳", "💡", "❓",
+]);
+
+const VARIATION_SELECTOR_16 = "️";
+const encoder = new TextEncoder();
+
+// `\p{RGI_Emoji}` needs the `v` flag, which every runtime we ship has. The
+// fallback keeps an older browser usable; the server stays the authority.
+const emojiPattern = (() => {
+  try {
+    return new RegExp("^\\p{RGI_Emoji}$", "v");
+  } catch {
+    return /^(?:\p{Regional_Indicator}{2}|[#*0-9]️?⃣|\p{Extended_Pictographic}(?:️|\p{Emoji_Modifier})?(?:‍\p{Extended_Pictographic}(?:️|\p{Emoji_Modifier})?)*)$/u;
+  }
+})();
+
+/**
+ * Return the canonical form of one emoji, or null when the value is anything
+ * else (text, several emoji, an oversized sequence).
+ */
+export function normalizeMessageReactionEmoji(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed || encoder.encode(trimmed).length > MESSAGE_REACTION_EMOJI_MAX_BYTES) return null;
+  if (emojiPattern.test(trimmed)) return trimmed;
+  // A bare text-style symbol such as "❤" is the same reaction as "❤️".
+  const qualified = `${trimmed}${VARIATION_SELECTOR_16}`;
+  return emojiPattern.test(qualified) ? qualified : null;
+}
+
+function normalizeReactor(value) {
+  if (!value || typeof value !== "object") return null;
+  const login = typeof value.login === "string" ? value.login.trim() : "";
+  if (!login || login.length > 256) return null;
+  const name = typeof value.name === "string" && value.name.trim() ? value.name.trim().slice(0, 256) : login;
+  const avatarUrl = typeof value.avatar_url === "string" && /^https:\/\//.test(value.avatar_url)
+    ? value.avatar_url.slice(0, 2048)
+    : null;
+  return { login, name, avatar_url: avatarUrl };
+}
+
+/**
+ * Read a server reaction list defensively. Anything malformed is dropped, so a
+ * client never renders a reaction it could not also send.
+ */
+export function normalizeMessageReactions(value) {
+  if (!Array.isArray(value)) return [];
+  const reactions = [];
+  const seen = new Set();
+  for (const item of value) {
+    if (reactions.length >= MESSAGE_REACTION_MAX_DISTINCT_PER_MESSAGE) break;
+    if (!item || typeof item !== "object") continue;
+    const emoji = normalizeMessageReactionEmoji(item.emoji);
+    if (!emoji || seen.has(emoji)) continue;
+    const reactors = (Array.isArray(item.reactors) ? item.reactors : [])
+      .slice(0, MESSAGE_REACTION_MAX_REACTORS_LISTED)
+      .map(normalizeReactor)
+      .filter(Boolean);
+    const count = Number.isSafeInteger(item.count) && item.count > 0 ? item.count : reactors.length;
+    if (count <= 0) continue;
+    seen.add(emoji);
+    reactions.push({ emoji, count: Math.max(count, reactors.length), reactors });
+  }
+  return reactions;
+}
+
+function sameLogin(left, right) {
+  return typeof left === "string" && typeof right === "string"
+    && left.length > 0 && left.toLowerCase() === right.toLowerCase();
+}
+
+/** Whether the listed reactors include the viewer. */
+export function viewerReactedWith(reaction, viewerLogin) {
+  return Boolean(reaction?.reactors?.some((reactor) => sameLogin(reactor.login, viewerLogin)));
+}
+
+/** "You, Ada and 3 others reacted with 👍" — the tooltip and the accessible name. */
+export function describeMessageReaction(reaction, viewerLogin) {
+  const reactors = Array.isArray(reaction?.reactors) ? reaction.reactors : [];
+  const viewerReacted = viewerReactedWith(reaction, viewerLogin);
+  const names = [
+    ...(viewerReacted ? ["You"] : []),
+    ...reactors.filter((reactor) => !sameLogin(reactor.login, viewerLogin)).map((reactor) => reactor.name),
+  ];
+  const count = Math.max(Number(reaction?.count) || 0, names.length);
+  const shown = names.slice(0, 3);
+  const others = count - shown.length;
+  if (others > 0) shown.push(others === 1 ? "1 other" : `${others} others`);
+  const who = shown.length <= 1
+    ? shown[0] ?? "Someone"
+    : `${shown.slice(0, -1).join(", ")} and ${shown.at(-1)}`;
+  return `${who} reacted with ${reaction?.emoji ?? ""}`.trim();
+}
+
+/**
+ * The reaction list after the viewer toggles one emoji, for an optimistic
+ * update. The server's answer replaces it either way.
+ */
+export function toggleViewerMessageReaction(reactions, emoji, viewer) {
+  const current = Array.isArray(reactions) ? reactions : [];
+  const existing = current.find((reaction) => reaction.emoji === emoji);
+  if (!existing) {
+    return [...current, { emoji, count: 1, reactors: [{ ...viewer }] }];
+  }
+  if (viewerReactedWith(existing, viewer.login)) {
+    const reactors = existing.reactors.filter((reactor) => !sameLogin(reactor.login, viewer.login));
+    const count = existing.count - 1;
+    return count <= 0
+      ? current.filter((reaction) => reaction !== existing)
+      : current.map((reaction) => (reaction === existing ? { ...existing, count, reactors } : reaction));
+  }
+  return current.map((reaction) => (reaction === existing
+    ? { ...existing, count: existing.count + 1, reactors: [...existing.reactors, { ...viewer }] }
+    : reaction));
+}

package/shared/message-search-controller.d.mts

@@ -0,0 +1,38 @@
+import type { MessageSearchQueryError, MessageSearchResponse } from "./message-search.mjs";
+
+export const MESSAGE_SEARCH_DEBOUNCE_MS: 250;
+
+export interface MessageSearchState<Hit extends { id: string }> {
+  /**
+   * `idle`: nothing to search yet. `invalid`: the query breaks a limit (see `error`).
+   * `loading`: the first page is on its way. `ready` / `error`: it arrived, or failed.
+   */
+  status: "idle" | "invalid" | "loading" | "ready" | "error";
+  terms: readonly string[];
+  /** Newest first. */
+  hits: readonly Hit[];
+  hasMore: boolean;
+  loadingMore: boolean;
+  /** A query limit name when `invalid`; otherwise the last request's failure, if any. */
+  error: MessageSearchQueryError | string | null;
+}
+
+export interface MessageSearchController<Hit extends { id: string }> {
+  readonly state: MessageSearchState<Hit>;
+  /** Search for a new query after a short pause in typing. */
+  setQuery(value: string): void;
+  /** Read the next, older page of the current results. */
+  loadMore(): Promise<void>;
+  /** Stop searching; call when the search closes or the room changes. */
+  reset(): void;
+}
+
+/**
+ * The client-side state of one room's history search, shared by the desktop
+ * and web apps. Answers that arrive for an earlier query are dropped.
+ */
+export function createMessageSearchController<Hit extends { id: string }>(options: {
+  search(query: string, before: string | null): Promise<Pick<MessageSearchResponse<Hit>, "messages" | "has_more" | "next_before"> & { terms?: string[] }>;
+  onChange?(): void;
+  debounceMs?: number;
+}): MessageSearchController<Hit>;

package/shared/message-search-controller.mjs

@@ -0,0 +1,99 @@
+// The client-side state of one room's history search, shared by the desktop
+// and web apps. Framework-free: the app supplies the request and is told when
+// something changed.
+import { parseMessageSearchQuery } from "./message-search.mjs";
+
+export const MESSAGE_SEARCH_DEBOUNCE_MS = 250;
+
+const IDLE = Object.freeze({ status: "idle", terms: [], hits: [], hasMore: false, loadingMore: false, error: null });
+
+export function createMessageSearchController({ search, onChange, debounceMs = MESSAGE_SEARCH_DEBOUNCE_MS }) {
+  let state = IDLE;
+  let query = "";
+  let nextBefore = null;
+  // Every new query (and reset) starts an epoch; answers from an earlier one are dropped.
+  let epoch = 0;
+  let timer = null;
+
+  function set(next) {
+    state = next;
+    onChange?.();
+  }
+
+  function cancelTimer() {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+  }
+
+  async function run(terms, startedIn) {
+    try {
+      const page = await search(query, null);
+      if (startedIn !== epoch) return;
+      nextBefore = page?.next_before ?? null;
+      set({
+        status: "ready",
+        terms: Array.isArray(page?.terms) ? page.terms : terms,
+        hits: Array.isArray(page?.messages) ? page.messages : [],
+        hasMore: Boolean(page?.has_more && nextBefore),
+        loadingMore: false,
+        error: null,
+      });
+    } catch (error) {
+      if (startedIn !== epoch) return;
+      set({ ...IDLE, status: "error", terms, error: error instanceof Error && error.message ? error.message : "Search failed." });
+    }
+  }
+
+  /** Search for a new query after a short pause in typing. */
+  function setQuery(value) {
+    const next = typeof value === "string" ? value : "";
+    if (next.trim() === query.trim() && state !== IDLE) return;
+    query = next;
+    epoch += 1;
+    cancelTimer();
+    nextBefore = null;
+    const parsed = parseMessageSearchQuery(query);
+    if (parsed.error) {
+      // Too short is simply "not searching yet"; the other limits are worth saying.
+      set(parsed.error === "too_short" ? IDLE : { ...IDLE, status: "invalid", error: parsed.error });
+      return;
+    }
+    const startedIn = epoch;
+    set({ ...IDLE, status: "loading", terms: parsed.terms });
+    timer = setTimeout(() => {
+      timer = null;
+      void run(parsed.terms, startedIn);
+    }, debounceMs);
+  }
+
+  /** Read the next, older page of the current results. */
+  async function loadMore() {
+    if (state.status !== "ready" || !state.hasMore || state.loadingMore || !nextBefore) return;
+    const startedIn = epoch;
+    const before = nextBefore;
+    set({ ...state, loadingMore: true, error: null });
+    try {
+      const page = await search(query, before);
+      if (startedIn !== epoch) return;
+      nextBefore = page?.next_before ?? null;
+      const known = new Set(state.hits.map((hit) => hit.id));
+      const more = (Array.isArray(page?.messages) ? page.messages : []).filter((hit) => !known.has(hit.id));
+      set({ ...state, hits: [...state.hits, ...more], hasMore: Boolean(page?.has_more && nextBefore), loadingMore: false });
+    } catch (error) {
+      if (startedIn !== epoch) return;
+      // Keep what is shown; the person can press "more" again.
+      set({ ...state, loadingMore: false, error: error instanceof Error && error.message ? error.message : "Search failed." });
+    }
+  }
+
+  /** Stop searching; call when the search closes or the room changes. */
+  function reset() {
+    query = "";
+    epoch += 1;
+    cancelTimer();
+    nextBefore = null;
+    if (state !== IDLE) set(IDLE);
+  }
+
+  return { get state() { return state; }, setQuery, loadMore, reset };
+}

package/shared/message-search.d.mts

@@ -0,0 +1,46 @@
+export const MESSAGE_SEARCH_MIN_QUERY_CHARS: 2;
+export const MESSAGE_SEARCH_MAX_QUERY_CHARS: 200;
+export const MESSAGE_SEARCH_MAX_TERMS: 6;
+export const MESSAGE_SEARCH_DEFAULT_LIMIT: 30;
+export const MESSAGE_SEARCH_MAX_LIMIT: 50;
+
+export type MessageSearchQueryError = "too_short" | "too_long" | "too_many_terms";
+
+export type ParsedMessageSearchQuery =
+  | { terms: string[]; error?: undefined }
+  | { error: MessageSearchQueryError; terms?: undefined };
+
+/**
+ * Split a query into its terms, or say why it cannot be searched. A term is a
+ * word, or a phrase in double quotes; a message matches when it contains every
+ * term as a substring, ignoring case.
+ */
+export function parseMessageSearchQuery(value: unknown): ParsedMessageSearchQuery;
+
+/** Whether a text contains every term, the same test the server applies. */
+export function textMatchesMessageSearch(text: unknown, terms: readonly string[]): boolean;
+
+/** `GET /rooms/:room/messages/search` */
+export interface MessageSearchResponse<Message = unknown> {
+  room_id: string;
+  terms: string[];
+  /** Newest first. */
+  messages: Message[];
+  has_more: boolean;
+  /** Pass as `before` to read the next, older page; null on the last page. */
+  next_before: string | null;
+}
+
+export interface MessageSearchSegment {
+  text: string;
+  match: boolean;
+}
+
+/**
+ * Split a text into runs that do and do not match the terms, for rendering
+ * highlights as plain text nodes (never as HTML).
+ */
+export function highlightMessageSearchText(text: unknown, terms: readonly string[]): MessageSearchSegment[];
+
+/** A short excerpt around the first match, with an ellipsis where text was left out. */
+export function messageSearchSnippet(text: unknown, terms: readonly string[], maxLength?: number): string;