letagents 0.12.34 → 0.12.36

package/shared/message-pin-store.mjs

@@ -0,0 +1,102 @@
+import { isPinMessageId, MESSAGE_PIN_LIMIT } from "./message-pins.mjs";
+
+/** One authoritative, bounded room list. All async work is fenced by context. */
+export function createMessagePinStore(options) {
+  let epoch = 0;
+  let generation = 0;
+  let context = null;
+  let disposed = false;
+  let reading = null;
+  let queued = false;
+  let mutation = null;
+  let state = { pins: [], available: false, loading: false, pending: null, error: null };
+  const changed = () => options.onChange?.(state);
+  function reset(next = null) {
+    epoch++;
+    generation++;
+    context = next;
+    reading = null;
+    mutation = null;
+    queued = false;
+    state = { pins: [], available: false, loading: false, pending: null, error: null };
+    changed();
+    if (next && !disposed) void refresh();
+  }
+  async function refresh() {
+    if (!context || disposed) return;
+    if (reading || mutation) { queued = true; return reading ?? mutation; }
+    const ownEpoch = epoch;
+    const ownGeneration = generation;
+    const ownContext = context;
+    state = { ...state, loading: true };
+    changed();
+    const job = Promise.resolve().then(async () => {
+      if (ownEpoch !== epoch || disposed) return;
+      try {
+        const response = await options.load(ownContext);
+        if (ownEpoch !== epoch || ownGeneration !== generation || disposed) return;
+        const seen = new Set();
+        const pins = (response.pins ?? []).filter((pin) => {
+          if (!isPinMessageId(pin.message_id) || seen.has(pin.message_id)) return false;
+          seen.add(pin.message_id);
+          return true;
+        }).slice(0, MESSAGE_PIN_LIMIT);
+        state = { ...state, pins, available: response.available !== false, error: null, pending: null };
+      } catch (error) {
+        if (ownEpoch === epoch && ownGeneration === generation && !disposed) {
+          state = { ...state, pending: null, error: error instanceof Error ? error.message : "Pins could not be loaded." };
+        }
+      } finally {
+        if (ownEpoch === epoch && !disposed) {
+          reading = null;
+          state = { ...state, loading: false };
+          changed();
+          if (queued && !mutation) { queued = false; void refresh(); }
+        }
+      }
+    });
+    reading = job;
+    return job;
+  }
+  async function setPinned(messageId, pinned) {
+    if (disposed || !context || !state.available || mutation || state.pending || !isPinMessageId(messageId)) return;
+    const ownEpoch = epoch;
+    const ownContext = context;
+    // A read started before this write is no longer authoritative.
+    generation++;
+    state = { ...state, pending: messageId, error: null };
+    changed();
+    const job = Promise.resolve().then(async () => {
+      if (ownEpoch !== epoch || disposed) return;
+      let succeeded = false;
+      try {
+        await options.mutate(ownContext, messageId, pinned);
+        succeeded = true;
+      } catch (error) {
+        if (ownEpoch === epoch && !disposed) {
+          const message = error instanceof Error ? error.message : "Pins could not be saved.";
+          state = { ...state, error: message };
+          options.onError?.(message);
+        }
+      } finally {
+        if (ownEpoch === epoch && !disposed) {
+          mutation = null;
+          state = { ...state, pending: succeeded ? messageId : null };
+          changed();
+        }
+      }
+      if (ownEpoch === epoch && !disposed && (succeeded || queued)) {
+        // If an older read is still running it must finish before the repair.
+        queued = false;
+        await refresh();
+      }
+    });
+    mutation = job;
+    return job;
+  }
+  return {
+    get state() { return state; },
+    reset, refresh, setPinned,
+    dispose() { disposed = true; reset(); },
+  };
+}

package/shared/message-pins.d.mts

@@ -0,0 +1,25 @@
+export const MESSAGE_PIN_LIMIT: 50;
+export const MESSAGE_PIN_SNIPPET_LENGTH: 240;
+export const MESSAGE_PIN_LIMIT_NOTICE: string;
+export function isPinMessageId(value: unknown): value is string;
+export function messagePinSnippet(text: string, displayText?: string | null): string;
+export interface MessagePin {
+  message_id: string;
+  sender: string;
+  source: string | null;
+  timestamp: string;
+  thread_root_id: string | null;
+  snippet: string;
+  pinned_at: string;
+  pinned_by: { login: string; name: string; avatar_url: string | null };
+}
+export interface MessagePinsResponse {
+  room_id: string;
+  pins: MessagePin[];
+  available?: boolean;
+}
+export interface MessagePinMutationResponse {
+  room_id: string;
+  message_id: string;
+  changed: boolean;
+}

package/shared/message-pins.mjs

@@ -0,0 +1,16 @@
+export const MESSAGE_PIN_LIMIT = 50;
+export const MESSAGE_PIN_SNIPPET_LENGTH = 240;
+export const MESSAGE_PIN_LIMIT_NOTICE = "This room already has 50 pinned messages. Unpin a message first.";
+
+export function isPinMessageId(value) {
+  return typeof value === "string" && /^msg_[1-9]\d*$/.test(value)
+    && Number(value.slice(4)) <= 2147483647;
+}
+
+/** Match the clients' displayed-text fallback; return text, never HTML. */
+export function messagePinSnippet(text, displayText) {
+  const chars = Array.from((displayText || text || "").replace(/\s+/gu, " ").trim());
+  return chars.length > MESSAGE_PIN_SNIPPET_LENGTH
+    ? chars.slice(0, MESSAGE_PIN_SNIPPET_LENGTH - 1).join("") + "…"
+    : chars.join("");
+}

package/shared/message-reaction-store.d.mts

@@ -0,0 +1,51 @@
+import type { MessageReaction, MessageReactor } from "./message-reactions.mjs";
+
+export interface MessageReactionStoreOptions {
+  /**
+   * Read the reactions of the messages from `firstMessageId` to `lastMessageId`
+   * (at most MESSAGE_REACTION_RANGE_MAX_SPAN apart). The answer may stop early
+   * and name the message to continue from.
+   */
+  load(firstMessageId: string, lastMessageId: string): Promise<{
+    reactions: Record<string, unknown>;
+    viewer_reactions?: Record<string, unknown>;
+    next_first_message_id?: string | null;
+  }>;
+  /** Add (`reacted: true`) or remove the viewer's reaction; resolves with the message's reactions. */
+  mutate(messageId: string, emoji: string, reacted: boolean): Promise<{ reactions: unknown }>;
+  /** The signed-in person, or null when nobody can react. */
+  viewer(): MessageReactor | null;
+  onChange?(): void;
+  onError?(error: unknown, during: "load" | "mutate"): void;
+  /** How long newly tracked messages are gathered before one read confirms them. */
+  refreshDelayMs?: number;
+}
+
+export interface MessageReactionStore {
+  /** A stable empty list when the message has no reactions. */
+  get(messageId: string): readonly MessageReaction[];
+  viewerReacted(messageId: string, emoji: string): boolean;
+  /**
+   * A rendered message registers itself; the returned function unregisters it.
+   * Its reactions start from what it carried and are confirmed by a read a
+   * moment after it is first tracked.
+   */
+  track(message: { id: string; reactions?: unknown }): () => void;
+  /** Re-read the reactions of every message on screen. */
+  refresh(): Promise<void>;
+  /** Add the viewer's reaction, or remove it if it is already there. */
+  toggle(messageId: string, emoji: string): Promise<void>;
+  /**
+   * Forget everything. With `keepTracked` the messages on screen stay
+   * registered (the signed-in person changed); without it they are dropped
+   * too (the room changed).
+   */
+  reset(options?: { keepTracked?: boolean }): void;
+}
+
+/**
+ * The client-side state of a room's reactions, shared by the desktop and web
+ * apps: seeded from the messages on screen, confirmed and kept current by
+ * reading the server.
+ */
+export function createMessageReactionStore(options: MessageReactionStoreOptions): MessageReactionStore;

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));
+}