presence-announcer.ts

presence-announcer.tsapps/web/src/lib/presence-announcer.tsraw ← lib4,845 B← Back to the app
1/**
2 * PresenceAnnouncer (TASK-0093, spec R5) — the polite live-region text for
3 * the page's presence: join/leave + "editing" state, **rate-limited to
4 * ≤ 1 announcement per second** and only on STATE CHANGE.
5 *
6 * Why: a peer typing fires cursor frames at ~8/s (the 120 ms emitter
7 * throttle); a screen reader must not be flooded. The announcer collapses
8 * the high-frequency stream to state transitions ("Ana is editing this
9 * page" / "Ana stopped editing" / "Ana joined" / "Ana left") and emits at
10 * most once per `minIntervalMs` (1000 ms).
11 *
12 * State model: a peer is "editing" while it has a non-null cursor AND is
13 * viewing. The peer set is derived from the store's roster (others only —
14 * the local user is never announced).
15 *
16 * Pure + injectable clock (AGENTS rule 25 — deterministic; rule 23 —
17 * domain logic independent from the UI). The hook (use-presence-announcer)
18 * owns the DOM live region and feeds this class.
19 */
20import type { Presence } from "./types";
21 
22export interface PresenceAnnouncement {
23  text: string;
24  at: number;
25}
26 
27export interface PresenceAnnouncerOptions {
28  readonly now?: () => number;
29  /** Minimum spacing between announcements (default 1000 ms = ≤ 1/s). */
30  readonly minIntervalMs?: number;
31}
32 
33interface PeerState {
34  editing: boolean;
35  name: string;
36}
37 
38/** Rank = priority (lower wins when several changes land in one update):
39 *  join(0) > editing-start(1) > editing-stop(2) > leave(3). */
40const RANK_JOIN = 0;
41const RANK_EDIT_START = 1;
42const RANK_EDIT_STOP = 2;
43const RANK_LEAVE = 3;
44 
45export class PresenceAnnouncer {
46  private readonly now: () => number;
47  private readonly minIntervalMs: number;
48  /** userId → last tracked state (undefined = never seen). */
49  private readonly last = new Map<string, PeerState>();
50  private lastEmitAt = Number.NEGATIVE_INFINITY;
51  /** The queued announcement (the last change landed within the window). */
52  private pending: string | null = null;
53 
54  constructor(opts: PresenceAnnouncerOptions = {}) {
55    this.now = opts.now ?? (() => Date.now());
56    this.minIntervalMs = opts.minIntervalMs ?? 1000;
57  }
58 
59  /**
60   * Feed the current roster (the page's OTHER peers — the local user
61   * already excluded). Returns the announcement to post NOW (or null):
62   *
63   *  - the highest-priority state change in this update (join >
64   *    editing-start > editing-stop > leave) is picked deterministically;
65   *  - if one was already posted within `minIntervalMs`, the change is
66   *    QUEUED and flushed by a later update (or `flush()`);
67   *  - the state map always advances (a queued change is not re-detected).
68   */
69  update(roster: readonly Presence[]): PresenceAnnouncement | null {
70    const seen = new Set<string>();
71    // The changes in this update (the lowest rank wins; a collection — a
72    // single `let` re-assigned inside the `consider` closure defeats the
73    // null-narrowing under noUncheckedIndexedAccess).
74    const changes: { text: string; rank: number }[] = [];
75    const consider = (text: string, rank: number): void => {
76      for (const c of changes) {
77        if (rank >= c.rank) return; // an equal-or-lower-priority change already recorded
78      }
79      changes.push({ text, rank });
80    };
81 
82    for (const p of roster) {
83      seen.add(p.userId);
84      const editing = p.cursor !== null && (p.viewing ?? true);
85      const prev = this.last.get(p.userId);
86      if (prev === undefined) {
87        consider(`${p.name} joined`, RANK_JOIN);
88      } else if (prev.editing !== editing) {
89        consider(
90          editing ? `${p.name} is editing this page` : `${p.name} stopped editing`,
91          editing ? RANK_EDIT_START : RANK_EDIT_STOP,
92        );
93      }
94      this.last.set(p.userId, { editing, name: p.name });
95    }
96 
97    // Leaves: peers that were tracked but are no longer in the roster.
98    for (const [userId, state] of this.last) {
99      if (seen.has(userId)) continue;
100      this.last.delete(userId);
101      consider(`${state.name} left`, RANK_LEAVE);
102    }
103 
104    if (changes.length === 0) return null;
105    const top = changes.reduce((a, b) => (b.rank < a.rank ? b : a));
106 
107    const at = this.now();
108    if (at - this.lastEmitAt < this.minIntervalMs) {
109      if (this.pending === null) this.pending = top.text; // highest-priority wins
110      return null;
111    }
112    this.pending = null;
113    this.lastEmitAt = at;
114    return { text: top.text, at };
115  }
116 
117  /** Flush a queued announcement (idle tick / unmount). */
118  flush(): PresenceAnnouncement | null {
119    const text = this.pending;
120    this.pending = null;
121    if (text === null) return null;
122    this.lastEmitAt = this.now();
123    return { text, at: this.now() };
124  }
125 
126  /** Reset (page switch — the state map is per-page). */
127  reset(): void {
128    this.last.clear();
129    this.pending = null;
130    this.lastEmitAt = Number.NEGATIVE_INFINITY;
131  }
132}
133