letagents 0.12.34 → 0.12.35

package/shared/message-search.mjs

@@ -0,0 +1,114 @@
+// Searching a room's messages: the limits and the one query grammar that the
+// server and both apps share. A query is a list of terms; a message matches
+// when it contains every term, ignoring case. A term is a word, or a phrase
+// in double quotes. Matching is by substring, so part of an identifier, a
+// file path or an error string finds the message.
+
+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;
+
+/**
+ * Split a query into its terms, or say why it cannot be searched.
+ * Returns `{ terms }` or `{ error: "too_short" | "too_long" | "too_many_terms" }`.
+ */
+export function parseMessageSearchQuery(value) {
+  const query = typeof value === "string" ? value.trim() : "";
+  if (query.length > MESSAGE_SEARCH_MAX_QUERY_CHARS) return { error: "too_long" };
+
+  const terms = [];
+  const seen = new Set();
+  // A phrase runs to its closing quote, or to the end when the quote is never closed.
+  for (const match of query.matchAll(/"([^"]*)"?|(\S+)/g)) {
+    const term = (match[1] ?? match[2] ?? "").replace(/\s+/g, " ").trim();
+    const key = term.toLowerCase();
+    if (!term || seen.has(key)) continue;
+    seen.add(key);
+    terms.push(term);
+  }
+  if (terms.join("").length < MESSAGE_SEARCH_MIN_QUERY_CHARS) return { error: "too_short" };
+  if (terms.length > MESSAGE_SEARCH_MAX_TERMS) return { error: "too_many_terms" };
+  return { terms };
+}
+
+/** Whether a text contains every term, the same test the server applies. */
+export function textMatchesMessageSearch(text, terms) {
+  const haystack = String(text ?? "").toLowerCase();
+  return terms.length > 0 && terms.every((term) => haystack.includes(term.toLowerCase()));
+}
+
+function matchRanges(text, terms) {
+  const lower = text.toLowerCase();
+  // Lowercasing can expand a character (İ -> i + combining dot). Keep the
+  // original UTF-16 boundaries so highlights and snippets still slice source text.
+  let sourceOffsets = null;
+  if (lower.length !== text.length) {
+    sourceOffsets = [];
+    let start = 0;
+    for (const character of text) {
+      const end = start + character.length;
+      for (let index = 0; index < character.toLowerCase().length; index += 1) {
+        sourceOffsets.push([start, end]);
+      }
+      start = end;
+    }
+    // Context-sensitive casing must not leave offsets outside the map.
+    if (sourceOffsets.length !== lower.length) return [];
+  }
+  const ranges = [];
+  for (const term of terms) {
+    const needle = term.toLowerCase();
+    if (!needle) continue;
+    for (let at = lower.indexOf(needle); at !== -1; at = lower.indexOf(needle, at + 1)) {
+      ranges.push(sourceOffsets
+        ? [sourceOffsets[at][0], sourceOffsets[at + needle.length - 1][1]]
+        : [at, at + needle.length]);
+    }
+  }
+  ranges.sort((left, right) => left[0] - right[0] || left[1] - right[1]);
+  // Overlapping and touching matches read as one highlighted run.
+  const merged = [];
+  for (const range of ranges) {
+    const last = merged.at(-1);
+    if (last && range[0] <= last[1]) last[1] = Math.max(last[1], range[1]);
+    else merged.push([...range]);
+  }
+  return merged;
+}
+
+/**
+ * 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, terms) {
+  const source = String(text ?? "");
+  const segments = [];
+  let cursor = 0;
+  for (const [start, end] of matchRanges(source, terms)) {
+    if (start > cursor) segments.push({ text: source.slice(cursor, start), match: false });
+    segments.push({ text: source.slice(start, end), match: true });
+    cursor = end;
+  }
+  if (cursor < source.length) segments.push({ text: source.slice(cursor), match: false });
+  return segments;
+}
+
+/**
+ * A short excerpt around the first match: whitespace collapsed, cut at
+ * `maxLength` characters, with an ellipsis where text was left out.
+ */
+export function messageSearchSnippet(text, terms, maxLength = 220) {
+  const source = String(text ?? "").replace(/\s+/g, " ").trim();
+  if (source.length <= maxLength) return source;
+  const first = matchRanges(source, terms)[0]?.[0] ?? 0;
+  // Keep a little lead-in so the match is read in its sentence.
+  let start = Math.max(0, Math.min(first - Math.floor(maxLength / 4), source.length - maxLength));
+  if (start > 0) {
+    const space = source.indexOf(" ", start);
+    if (space !== -1 && space < first) start = space + 1;
+  }
+  const end = Math.min(source.length, start + maxLength);
+  return `${start > 0 ? "…" : ""}${source.slice(start, end).trim()}${end < source.length ? "…" : ""}`;
+}

package/shared/room-message-urls.d.mts

@@ -0,0 +1,25 @@
+export const LETAGENTS_ROOM_ORIGIN: string;
+export const MESSAGE_ID_PATTERN: RegExp;
+
+export function isValidMessageId(messageId: unknown): messageId is string;
+export function encodeRoomPathIdentifier(identifier: string): string;
+export function decodeRoomPath(path: string): string;
+export function isLocalRoomIdentifier(identifier: string | null | undefined): boolean;
+
+export function buildLetAgentsMessageUrl(
+  roomIdentifier: string,
+  messageId: string,
+  origin?: string,
+): string;
+
+export function parseLetAgentsMessageUrl(
+  rawUrl: string,
+  configuredOrigin?: string,
+): { roomIdentifier: string; messageId: string | null } | null;
+
+export function resolveSameRoomMessageReference(
+  rawUrl: string | null | undefined,
+  currentRoomIdentifier: string | null | undefined,
+  configuredOrigin?: string,
+): string | null;
+

package/shared/room-message-urls.mjs

@@ -0,0 +1,119 @@
+export const LETAGENTS_ROOM_ORIGIN = "https://letagents.chat";
+
+export const MESSAGE_ID_PATTERN = /^msg_[1-9]\d*$/;
+
+export function isValidMessageId(messageId) {
+  return typeof messageId === "string" && MESSAGE_ID_PATTERN.test(messageId);
+}
+
+export function encodeRoomPathIdentifier(identifier) {
+  return String(identifier ?? "")
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+export function decodeRoomPath(path) {
+  return String(path ?? "")
+    .split("/")
+    .map((segment) => {
+      try {
+        return decodeURIComponent(segment);
+      } catch {
+        return segment;
+      }
+    })
+    .join("/");
+}
+
+export function isLocalRoomIdentifier(identifier) {
+  const value = String(identifier ?? "").trim();
+  return /^local[_-]/i.test(value) || /^git-room:local:/i.test(value);
+}
+
+export function buildLetAgentsMessageUrl(
+  roomIdentifier,
+  messageId,
+  origin = LETAGENTS_ROOM_ORIGIN,
+) {
+  const cleanId = String(messageId ?? "").trim();
+  if (!isValidMessageId(cleanId)) {
+    throw new Error(`Invalid message ID for permalink: ${messageId}`);
+  }
+  const cleanRoom = String(roomIdentifier ?? "").trim();
+  if (!cleanRoom) {
+    throw new Error("Room identifier is required for permalink.");
+  }
+  const base = origin ? origin.replace(/\/+$/, "") : "";
+  return `${base}/in/${encodeRoomPathIdentifier(cleanRoom)}?message=${cleanId}`;
+}
+
+export function parseLetAgentsMessageUrl(
+  rawUrl,
+  configuredOrigin = LETAGENTS_ROOM_ORIGIN,
+) {
+  if (typeof rawUrl !== "string") return null;
+  const trimmed = rawUrl.trim();
+  if (!trimmed) return null;
+
+  let parsed;
+  let isRelative = false;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    if (trimmed.startsWith("/in/") || trimmed.startsWith("in/")) {
+      try {
+        parsed = new URL(trimmed.startsWith("/") ? trimmed : `/${trimmed}`, "http://localhost");
+        isRelative = true;
+      } catch {
+        return null;
+      }
+    } else {
+      return null;
+    }
+  }
+
+  if (!isRelative) {
+    let normalizedConfiguredOrigin;
+    try {
+      normalizedConfiguredOrigin = new URL(configuredOrigin).origin.toLowerCase();
+    } catch {
+      normalizedConfiguredOrigin = String(configuredOrigin).replace(/\/+$/, "").toLowerCase();
+    }
+    if (parsed.origin.toLowerCase() !== normalizedConfiguredOrigin) {
+      return null;
+    }
+  }
+
+  const pathname = parsed.pathname.replace(/^\/+|\/+$/g, "");
+  if (!pathname.startsWith("in/")) {
+    return null;
+  }
+  const rawRoom = pathname.slice("in/".length);
+  if (!rawRoom) return null;
+  const roomIdentifier = decodeRoomPath(rawRoom);
+  if (!roomIdentifier.trim()) return null;
+
+  const rawMessageId = parsed.searchParams.get("message");
+  const messageId = isValidMessageId(rawMessageId) ? rawMessageId.trim() : null;
+
+  return {
+    roomIdentifier,
+    messageId,
+  };
+}
+
+export function resolveSameRoomMessageReference(
+  rawUrl,
+  currentRoomIdentifier,
+  configuredOrigin = LETAGENTS_ROOM_ORIGIN,
+) {
+  if (typeof rawUrl !== "string" || !currentRoomIdentifier) return null;
+  const parsed = parseLetAgentsMessageUrl(rawUrl, configuredOrigin);
+  if (!parsed?.messageId) return null;
+  if (parsed.roomIdentifier.trim() !== String(currentRoomIdentifier).trim()) {
+    return null;
+  }
+  return parsed.messageId;
+}
+

package/shared/room-notification-client.d.mts

@@ -0,0 +1,18 @@
+import type { RoomNotificationPreference, RoomNotificationPreferenceChange, RoomNotificationPreferenceEntry, RoomNotificationPreferenceList } from './room-notification-preferences.mjs';
+export interface RoomNotificationClientState {
+  preference: RoomNotificationPreference; ready: boolean; loading: boolean; busy: boolean; error: string; version: number;
+}
+export declare function createRoomNotificationClient(api: {
+  get(roomId: string): Promise<RoomNotificationPreferenceEntry>;
+  list?(): Promise<RoomNotificationPreferenceList>;
+  put?(roomId: string, change: RoomNotificationPreferenceChange): Promise<RoomNotificationPreferenceEntry>;
+}, changed?: () => void, normalizeKey?: (roomId: string) => string): {
+  setViewer(viewer: { id: string; login: string } | null): void;
+  signedIn(): boolean;
+  allowsAfterRead(roomId: string, text: unknown): Promise<boolean>;
+  state(roomId: string): RoomNotificationClientState;
+  refresh(roomId: string): Promise<void>;
+  refreshAll(): Promise<void>;
+  update(roomId: string, change: RoomNotificationPreferenceChange): Promise<void>;
+  allows(roomId: string, text: unknown, now?: number): boolean;
+};

package/shared/room-notification-client.mjs

@@ -0,0 +1,140 @@
+import { allowsRoomNotification, DEFAULT_ROOM_NOTIFICATION_PREFERENCE } from './room-notification-preferences.mjs';
+
+/** Personal cache shared by desktop and the read-only web sound gate. */
+export function createRoomNotificationClient(api, changed = () => {}, normalizeKey = (id) => id) {
+  let viewer = null;
+  let epoch = 0;
+  let listVersion = 0;
+  let listLoading = false;
+  const rooms = new Map();
+  const pendingReads = new Map();
+  let pendingList = null;
+  function state(roomId) {
+    roomId = normalizeKey(roomId);
+    if (!rooms.has(roomId)) rooms.set(roomId, {
+      preference: { ...DEFAULT_ROOM_NOTIFICATION_PREFERENCE }, ready: false, loading: false,
+      busy: false, error: '', version: 0,
+    });
+    return rooms.get(roomId);
+  }
+  function setViewer(next) {
+    if (viewer?.id === next?.id && viewer?.login === next?.login) return;
+    viewer = next;
+    epoch++;
+    listVersion++;
+    listLoading = false;
+    rooms.clear();
+    pendingReads.clear();
+    pendingList = null;
+    changed();
+  }
+  async function performRefresh(roomId) {
+    if (!viewer || !roomId) return;
+    const row = state(roomId);
+    if (row.busy) return;
+    const version = ++row.version;
+    const currentEpoch = epoch;
+    row.loading = true;
+    changed();
+    try {
+      const preference = await api.get(roomId);
+      if (epoch !== currentEpoch || row.version !== version) return;
+      row.preference = preference;
+      row.error = '';
+    } catch (error) {
+      if (epoch !== currentEpoch || row.version !== version) return;
+      if (!row.ready) row.preference = { ...DEFAULT_ROOM_NOTIFICATION_PREFERENCE };
+      row.error = error instanceof Error ? error.message : 'Notification settings could not be loaded.';
+    } finally {
+      if (epoch === currentEpoch && row.version === version) {
+        row.loading = false;
+        row.ready = true;
+        changed();
+      }
+    }
+  }
+  function refresh(roomId) {
+    roomId = normalizeKey(roomId);
+    const pending = performRefresh(roomId);
+    pendingReads.set(roomId, pending);
+    void pending.then(() => { if (pendingReads.get(roomId) === pending) pendingReads.delete(roomId); });
+    return pending;
+  }
+  async function performRefreshAll() {
+    if (!viewer || !api.list) return;
+    const currentEpoch = epoch;
+    const version = ++listVersion;
+    listLoading = true;
+    const roomVersions = new Map([...rooms].map(([id, row]) => [id, row.version]));
+    try {
+      const result = await api.list();
+      if (currentEpoch !== epoch || version !== listVersion) return;
+      const entries = new Map(result.preferences.map((entry) => [normalizeKey(entry.room_id), entry]));
+      for (const id of new Set([...rooms.keys(), ...entries.keys()])) {
+        const row = state(id);
+        if (row.version !== (roomVersions.get(id) ?? 0) || row.loading || row.busy) continue;
+        if (!entries.has(id) && result.truncated) continue;
+        row.preference = entries.get(id) ?? { ...DEFAULT_ROOM_NOTIFICATION_PREFERENCE };
+        row.ready = true;
+        row.error = '';
+      }
+    } catch (error) {
+      if (currentEpoch !== epoch || version !== listVersion) return;
+      for (const [id, row] of rooms) {
+        if (row.version !== (roomVersions.get(id) ?? 0) || row.loading || row.busy) continue;
+        if (!row.ready) row.preference = { ...DEFAULT_ROOM_NOTIFICATION_PREFERENCE };
+        row.ready = true;
+        row.error = error instanceof Error ? error.message : 'Notification settings could not be loaded.';
+      }
+    }
+    if (version === listVersion && currentEpoch === epoch) listLoading = false;
+    changed();
+  }
+  function refreshAll() {
+    const pending = performRefreshAll();
+    pendingList = pending;
+    void pending.then(() => { if (pendingList === pending) pendingList = null; });
+    return pending;
+  }
+  async function update(roomId, change) {
+    roomId = normalizeKey(roomId);
+    if (!viewer || !api.put) throw new Error('Sign in to manage your room notifications.');
+    const row = state(roomId);
+    if (row.busy) return;
+    row.busy = true;
+    row.loading = false;
+    row.version++;
+    listVersion++;
+    listLoading = false;
+    const currentEpoch = epoch;
+    changed();
+    try {
+      const preference = await api.put(roomId, change);
+      if (currentEpoch !== epoch) return;
+      row.preference = preference;
+      row.ready = true;
+      row.error = '';
+    } catch (error) {
+      if (currentEpoch !== epoch) return;
+      row.error = error instanceof Error ? error.message : 'Notification settings could not be saved.';
+    } finally {
+      if (currentEpoch === epoch) { row.busy = false; changed(); }
+    }
+  }
+  function allows(roomId, text, now = Date.now()) {
+    const row = state(roomId);
+    if ((row.loading || listLoading) && !row.ready) return false;
+    return allowsRoomNotification(row.preference, text, viewer?.login, now);
+  }
+  async function allowsAfterRead(roomId, text) {
+    roomId = normalizeKey(roomId);
+    const currentEpoch = epoch;
+    while (currentEpoch === epoch && !state(roomId).ready) {
+      const pending = pendingReads.get(roomId) ?? pendingList;
+      if (!pending) break;
+      await pending;
+    }
+    return currentEpoch === epoch && allows(roomId, text);
+  }
+  return { setViewer, state, refresh, refreshAll, update, allows, allowsAfterRead, signedIn: () => Boolean(viewer) };
+}

package/shared/room-notification-preferences.d.mts

@@ -0,0 +1,17 @@
+export type RoomNotificationLevel = 'all' | 'mentions' | 'muted';
+export interface RoomNotificationPreference {
+  level: RoomNotificationLevel;
+  snoozed_until: string | null;
+}
+export interface RoomNotificationPreferenceEntry extends RoomNotificationPreference { room_id: string }
+export interface RoomNotificationPreferenceList { preferences: RoomNotificationPreferenceEntry[]; truncated: boolean }
+export type RoomNotificationPreferenceChange = Partial<RoomNotificationPreference>;
+export type RoomNotificationSnoozePreset = '1h' | '8h' | 'tomorrow';
+export declare const ROOM_NOTIFICATION_LEVELS: readonly RoomNotificationLevel[];
+export declare const DEFAULT_ROOM_NOTIFICATION_PREFERENCE: Readonly<RoomNotificationPreference>;
+export declare const PERSON_MENTION_START: string;
+export declare const PERSON_MENTION_END: string;
+export declare function mentionsPerson(text: unknown, login: string | null | undefined): boolean;
+export declare function roomNotificationsSuppressed(preference: RoomNotificationPreference | null | undefined, now?: number): boolean;
+export declare function allowsRoomNotification(preference: RoomNotificationPreference | null | undefined, text: unknown, login: string | null | undefined, now?: number): boolean;
+export declare function roomNotificationSnoozeUntil(preset: RoomNotificationSnoozePreset, now?: Date): string;

package/shared/room-notification-preferences.mjs

@@ -0,0 +1,34 @@
+export const ROOM_NOTIFICATION_LEVELS = ['all', 'mentions', 'muted'];
+export const DEFAULT_ROOM_NOTIFICATION_PREFERENCE = Object.freeze({ level: 'all', snoozed_until: null });
+// Shared with PostgreSQL's regex predicate. A final sentence period is punctuation;
+// a dot followed by a handle character is part of a longer handle.
+export const PERSON_MENTION_START = '(^|[^A-Za-z0-9_./@:-])@';
+export const PERSON_MENTION_END = '(?![A-Za-z0-9_/@:-]|\\.[A-Za-z0-9_])';
+
+export function mentionsPerson(text, login) {
+  if (typeof login !== 'string' || !login) return false;
+  const escaped = login.replace(/[^A-Za-z0-9_-]/g, '\\$&');
+  return new RegExp(PERSON_MENTION_START + escaped + PERSON_MENTION_END, 'i').test(String(text ?? ''));
+}
+
+export function roomNotificationsSuppressed(preference, now = Date.now()) {
+  return preference?.level === 'muted' || Date.parse(preference?.snoozed_until ?? '') > now;
+}
+
+export function allowsRoomNotification(preference, text, login, now = Date.now()) {
+  if (roomNotificationsSuppressed(preference, now)) return false;
+  return preference?.level !== 'mentions' || mentionsPerson(text, login);
+}
+
+export function roomNotificationSnoozeUntil(preset, now = new Date()) {
+  const date = new Date(now);
+  if (preset === 'tomorrow') {
+    date.setDate(date.getDate() + 1);
+    date.setHours(9, 0, 0, 0);
+  } else if (preset === '1h' || preset === '8h') {
+    date.setTime(date.getTime() + (preset === '1h' ? 1 : 8) * 60 * 60 * 1000);
+  } else {
+    throw new Error('Choose a snooze duration.');
+  }
+  return date.toISOString();
+}

package/shared/room-resource-invalidation.d.mts

@@ -5,12 +5,17 @@ export const ROOM_RESOURCE_AGENT_APPROVAL: "agent_approval";
 export const ROOM_RESOURCE_EXECUTION_DELEGATION: "execution_delegation";
 /** What agents are waiting for changed; consumers re-read the room's wake rules. */
 export const ROOM_RESOURCE_WAKE_RULES: "wake_rules";
+/** A reaction was added or removed; consumers re-read the reactions of the messages they show. */
+export const ROOM_RESOURCE_MESSAGE_PINS: "message_pins";
+export const ROOM_RESOURCE_MESSAGE_REACTIONS: "message_reactions";
 /** Protocol-known references; consumers independently choose what they render. */
 export const ROOM_RESOURCE_INVALIDATION_RESOURCES: readonly [
   "agent_work",
   "agent_approval",
   "execution_delegation",
   "wake_rules",
+  "message_reactions",
+  "message_pins",
 ];
 
 export type RoomResourceInvalidationResource =

package/shared/room-resource-invalidation.mjs

@@ -6,6 +6,10 @@ export const ROOM_RESOURCE_AGENT_WORK = "agent_work";
 export const ROOM_RESOURCE_AGENT_APPROVAL = "agent_approval";
 export const ROOM_RESOURCE_EXECUTION_DELEGATION = "execution_delegation";
 export const ROOM_RESOURCE_WAKE_RULES = "wake_rules";
+// Someone added or removed an emoji reaction. Consumers re-read the reactions
+// of the messages they show; the pointer never says which message changed.
+export const ROOM_RESOURCE_MESSAGE_PINS = "message_pins";
+export const ROOM_RESOURCE_MESSAGE_REACTIONS = "message_reactions";
 // Protocol-known references. Each consumer still decides which surfaces, if
 // any, react to a supported pointer.
 export const ROOM_RESOURCE_INVALIDATION_RESOURCES = [
@@ -13,6 +17,8 @@ export const ROOM_RESOURCE_INVALIDATION_RESOURCES = [
   ROOM_RESOURCE_AGENT_APPROVAL,
   ROOM_RESOURCE_EXECUTION_DELEGATION,
   ROOM_RESOURCE_WAKE_RULES,
+  ROOM_RESOURCE_MESSAGE_REACTIONS,
+  ROOM_RESOURCE_MESSAGE_PINS,
 ];
 
 function exactKeys(value, keys) {

package/shared/room-typing.d.mts

@@ -0,0 +1,16 @@
+export const ROOM_TYPING: 'room_typing_v1';
+export const TYPING: Readonly<{ ttl: number; interval: number; sweep: number; sources: number; people: number; entries: number; name: number }>;
+export interface TypingReport { client_id: string; sequence: number; typing: boolean; ttl_ms: number }
+export interface TypingSignal extends TypingReport { room_id: string; account_id: string; name: string; expires_at: number }
+export function parseTypingReport(value: unknown): TypingReport | null;
+export function parseTypingSignal(value: unknown): TypingSignal | null;
+export function createTypingSender(options: {
+  send: (report: TypingReport) => unknown; clientId: string; now?: () => number;
+  schedule?: (callback: () => void, ms: number) => any; cancel?: (timer: any) => void;
+}): { input(nonempty: boolean): void; stop(): void };
+export function createTypingReceiver(now?: () => number): {
+  receive(raw: unknown, self: string | null): void; clear(): void; label(): string; nextExpiry(): number | null;
+};
+export function createTypingDisplay(update: (label: string) => void, clock?: {
+  now?: () => number; schedule?: (callback: () => void, ms: number) => any; cancel?: (timer: any) => void;
+}): { receive(raw: unknown, self: string | null): void; clear(): void };

package/shared/room-typing.mjs

@@ -0,0 +1,112 @@
+export const ROOM_TYPING = 'room_typing_v1';
+export const TYPING = Object.freeze({ ttl: 5000, interval: 2500, sweep: 1000, sources: 4, people: 512, entries: 10000, name: 80 });
+
+export function parseTypingReport(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const { client_id, sequence, typing, ttl_ms } = value;
+  if (Object.keys(value).sort().join() !== 'client_id,sequence,ttl_ms,typing'
+    || typeof client_id !== 'string' || !/^[a-zA-Z0-9_-]{16,64}$/.test(client_id)
+    || !Number.isSafeInteger(sequence) || sequence < 1 || typeof typing !== 'boolean'
+    || !Number.isInteger(ttl_ms) || ttl_ms < 0 || ttl_ms > TYPING.ttl
+    || typing !== (ttl_ms > 0)) return null;
+  return { client_id, sequence, typing, ttl_ms };
+}
+
+export function parseTypingSignal(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const { room_id, account_id, name, expires_at, ...report } = value;
+  if (!parseTypingReport(report) || ![room_id, account_id, name].every(v => typeof v === 'string' && v.length > 0)
+    || room_id.length > 512 || account_id.length > 128 || name.length > TYPING.name
+    || !Number.isSafeInteger(expires_at)) return null;
+  return value;
+}
+
+/** No drafts enter this controller: input is only a nonempty/empty bit. */
+export function createTypingSender({ send, clientId, now = Date.now, schedule = setTimeout, cancel = clearTimeout }) {
+  let sequence = 0, lastSent = -Infinity, lastInput = 0, active = false, reported = false, dirty = false, timer = null;
+  function report(typing) {
+    lastSent = now();
+    reported = typing;
+    dirty = false;
+    try {
+      void Promise.resolve(send({ client_id: clientId, sequence: ++sequence, typing,
+        ttl_ms: typing ? Math.max(1, TYPING.ttl - (now() - lastInput)) : 0 })).catch(() => {});
+    } catch { /* Reporting cannot interrupt composing, sending, or cleanup. */ }
+  }
+  function stop() {
+    if (timer !== null) cancel(timer);
+    timer = null;
+    if (reported) report(false);
+    active = false;
+  }
+  function tick() {
+    timer = null;
+    if (now() - lastInput >= TYPING.ttl) return stop();
+    if (dirty && now() - lastSent >= TYPING.interval) report(true);
+    timer = schedule(tick, Math.min(TYPING.interval, TYPING.ttl - (now() - lastInput)));
+  }
+  return {
+    input(nonempty) {
+      if (!nonempty) return stop();
+      lastInput = now();
+      dirty = true;
+      if (!active) {
+        active = true;
+        if (now() - lastSent >= TYPING.interval) report(true);
+      }
+      if (timer === null) timer = schedule(tick, TYPING.interval);
+    },
+    stop,
+  };
+}
+
+/** Sequence guards survive stops briefly; no snapshot or replay. */
+export function createTypingReceiver(now = Date.now) {
+  const sources = new Map();
+  return {
+    receive(raw, self) {
+      const value = parseTypingSignal(raw);
+      if (!value || value.account_id === self) return;
+      const key = `${value.account_id}:${value.client_id}`;
+      const previous = sources.get(key);
+      if (previous && previous.sequence >= value.sequence) return;
+      if (!previous && sources.size >= TYPING.people * TYPING.sources) return;
+      sources.set(key, { ...value, until: now() + Math.min(value.ttl_ms, TYPING.ttl), forget: now() + TYPING.ttl });
+    },
+    clear() { sources.clear(); },
+    nextExpiry() {
+      let earliest = Infinity;
+      for (const value of sources.values()) {
+        if (value.typing && value.until > now()) earliest = Math.min(earliest, value.until);
+      }
+      return Number.isFinite(earliest) ? earliest : null;
+    },
+    label() {
+      const people = new Map();
+      for (const [key, value] of sources) {
+        if (value.forget <= now()) sources.delete(key);
+        else if (value.typing && value.until > now()) people.set(value.account_id, value.name);
+      }
+      const names = [...people].sort(([a], [b]) => a.localeCompare(b)).map(([, name]) => name);
+      if (names.length > 2) return 'Several people are typing…';
+      return names.length ? `${names.join(' and ')} ${names.length === 1 ? 'is' : 'are'} typing…` : '';
+    },
+  };
+}
+
+/** A single receiver timeout, and no timer at all when nobody is typing. */
+export function createTypingDisplay(update, { now = Date.now, schedule = setTimeout, cancel = clearTimeout } = {}) {
+  const receiver = createTypingReceiver(now);
+  let timer = null;
+  function refresh() {
+    if (timer !== null) cancel(timer);
+    timer = null;
+    update(receiver.label());
+    const expiry = receiver.nextExpiry();
+    if (expiry !== null) timer = schedule(refresh, Math.max(0, expiry - now()));
+  }
+  return {
+    receive(raw, self) { receiver.receive(raw, self); refresh(); },
+    clear() { receiver.clear(); refresh(); },
+  };
+}