awareness.ts · Source

awareness.tspackages/collaboration/src/awareness.tsraw ← src9,023 B← Back to the app
1/**
2 * @factory/collaboration — the client-side awareness (presence) store
3 * (TASK-0093; the canvas's Zustand store is a thin projection of this —
4 * the package owns the state machine, the store owns the rendering).
5 *
6 * Rules implemented here (the R1–R5 contract of TASK-0093):
7 *   R1 — the presence state is `userId → PresenceMeta` (display name,
8 *        deterministic color from `@factory/shared/presence` — the
9 *        20-color palette, shared so server/client agree). The color is
10 *        NEVER the only identifier (the name label is mandatory — the
11 *        a11y rule: "color is never the only identifier").
12 *   R3 — cursor validity: a frame's cursor is applied only when the
13 *        referenced block is in the doc (the doc exposes
14 *        `hasBlock(blockId)`); a stale cursor (its block was removed by
15 *        the CRDT) is dropped silently (no error, no stale render).
16 *   R5 — viewing is null on blur (an unfocused tab sends
17 *        `viewing: false` — the avatar dims; the cursor stays valid).
18 *   Prune — a peer silent for `pruneAfterMs` (the server's 90 s; the
19 *        client prunes its own view earlier for a snappy UI — 60 s,
20 *        recorded) is removed; a re-`hello` roster re-broadcasts the
21 *        full set (a joiner gets everyone < 500 ms — the server's job,
22 *        the store just absorbs the roster).
23 *
24 * The self peer is tracked under `selfId` but excluded from
25 * {@link AwarenessStore.peers} (the bar shows "N others" — the a11y
26 * contract: the bar is absent when 0 others).
27 *
28 * Deterministic (no `Date.now()` inside state transitions — the clock is
29 * injected; rule 25).
30 */
31 
32import { presenceColor } from "@factory/shared/presence";
33 
34import type { PeerInfo, PresenceIdentity } from "./types.js";
35 
36export interface AwarenessSelf {
37  readonly userId: string;
38  readonly name: string;
39  readonly color: string;
40}
41 
42export interface AwarenessOptions {
43  /** The self identity (absence = presence disabled, all no-ops). */
44  readonly self?: PresenceIdentity;
45  /** The doc's block-set probe (cursor validity, R3). */
46  readonly hasBlock?: (blockId: string) => boolean;
47  /** The peer silence limit before pruning (default 60 s; the server's
48   *  own prune is 90 s — the client's is earlier for a snappy UI). */
49  readonly pruneAfterMs?: number;
50  readonly now?: () => number;
51  /** Peer roster/changes (the Zustand store subscribes). */
52  readonly onPeersChange?: (peers: readonly PeerInfo[]) => void;
53}
54 
55const DEFAULT_PRUNE_MS = 60_000;
56 
57/**
58 * The awareness state machine. Frame intake is via {@link AwarenessStore.applyPresence}
59 * (the provider routes the `awareness` binary frames through the
60 * y-protocols awareness update, then extracts the per-peer state into
61 * here — the extraction lives on the canvas where the y-protocols binding
62 * is; this store is pure state + validity rules + the self cursor API).
63 */
64export class AwarenessStore {
65  private readonly self: AwarenessSelf | null;
66  private readonly peerMap = new Map<string, PeerInfo>();
67  // `| undefined` (not `?`): exactOptionalPropertyTypes — the constructor
68  // may legitimately assign `undefined` (option absent = feature off).
69  private readonly hasBlock: ((blockId: string) => boolean) | undefined;
70  private readonly pruneAfterMs: number;
71  private readonly now: () => number;
72  private readonly onPeersChange: ((peers: readonly PeerInfo[]) => void) | undefined;
73  private selfCursor: { blockId: string; offset: number } | null = null;
74  private selfViewing = true;
75 
76  constructor(opts: AwarenessOptions = {}) {
77    this.self = opts.self
78      ? {
79          userId: opts.self.userId,
80          name: opts.self.name,
81          color: presenceColor(opts.self.userId),
82        }
83      : null;
84    this.hasBlock = opts.hasBlock;
85    this.pruneAfterMs = opts.pruneAfterMs ?? DEFAULT_PRUNE_MS;
86    this.now = opts.now ?? (() => Date.now());
87    this.onPeersChange = opts.onPeersChange;
88  }
89 
90  /** The self identity (null when presence is disabled). */
91  get selfPeer(): AwarenessSelf | null {
92    return this.self;
93  }
94 
95  /** The peer roster (self excluded — the "N others" bar input). */
96  get peers(): readonly PeerInfo[] {
97    return [...this.peerMap.values()];
98  }
99 
100  /**
101   * Absorb a roster (the `hello` roomPeers + the join re-broadcast). The
102   * roster carries users only (id/name/color — no cursors; cursors ride
103   * the awareness frames). Existing cursor state for a peer is kept when
104   * the peer is still in the roster.
105   */
106  applyRoster(roster: readonly { user: { id: string; name: string; color: string } }[]): void {
107    const seen = new Set<string>();
108    const now = this.now();
109    for (const entry of roster) {
110      const id = entry.user.id;
111      seen.add(id);
112      if (this.self !== null && id === this.self.userId) continue;
113      const existing = this.peerMap.get(id);
114      const peer: PeerInfo = {
115        userId: id,
116        name: entry.user.name,
117        // The roster color wins only when present; the shared hash is the
118        // fallback (server-stamped truth, TASK-0093 decision recorded).
119        color: entry.user.color !== "" ? entry.user.color : presenceColor(id),
120        cursor: existing?.cursor ?? null,
121        selection: existing?.selection ?? null,
122        viewing: existing?.viewing ?? true,
123        lastSeen: existing?.lastSeen ?? now,
124      };
125      this.peerMap.set(id, peer);
126    }
127    // Peers no longer in the roster left the room.
128    for (const id of [...this.peerMap.keys()]) {
129      if (!seen.has(id)) this.peerMap.delete(id);
130    }
131    this.emit();
132  }
133 
134  /**
135   * Apply one peer's awareness state (a y-protocols awareness frame
136   * decoded to its per-peer fields). Stale-cursor rule (R3): the cursor
137   * is applied only when the block still exists in the doc — a removed
138   * block drops the cursor silently.
139   */
140  applyPresence(
141    userId: string,
142    state: {
143      user?: { id?: string; name?: string; color?: string };
144      cursor?: { blockId: string; offset: number } | null;
145      selection?: string | null;
146      viewing?: boolean;
147    },
148  ): void {
149    if (this.self === null) return;
150    // Anti-impersonation (mirrors the server's per-frame id check): the
151    // frame's user.id must equal the frame's owner.
152    if (state.user?.id !== undefined && state.user.id !== userId) return;
153    if (userId === this.self.userId) return; // self rides the local state
154 
155    let cursor: PeerInfo["cursor"] = null;
156    if (state.cursor !== null && state.cursor !== undefined) {
157      const valid = this.hasBlock === undefined || this.hasBlock(state.cursor.blockId);
158      if (valid) cursor = { ...state.cursor };
159    }
160    const existing = this.peerMap.get(userId);
161    const peer: PeerInfo = {
162      userId,
163      name: state.user?.name ?? existing?.name ?? `User ${userId.slice(0, 6)}`,
164      color: state.user?.color ?? existing?.color ?? presenceColor(userId),
165      cursor,
166      selection: state.selection ?? null,
167      viewing: state.viewing ?? existing?.viewing ?? true,
168      lastSeen: this.now(),
169    };
170    this.peerMap.set(userId, peer);
171    this.emit();
172  }
173 
174  /** Remove a peer explicitly (a leave frame / roster drop). */
175  removePeer(userId: string): void {
176    if (this.peerMap.delete(userId)) this.emit();
177  }
178 
179  /**
180   * Drop peers silent for longer than `pruneAfterMs` (the client-side
181   * 60 s; the server's 90 s prune is the backstop — the re-join roster
182   * heals any over-prune). Returns the pruned ids.
183   */
184  pruneSilent(): readonly string[] {
185    const cutoff = this.now() - this.pruneAfterMs;
186    const pruned: string[] = [];
187    for (const [id, peer] of this.peerMap) {
188      if (peer.lastSeen < cutoff) {
189        this.peerMap.delete(id);
190        pruned.push(id);
191      }
192    }
193    if (pruned.length > 0) this.emit();
194    return pruned;
195  }
196 
197  /** The self cursor (the canvas updates it on selection change). */
198  setSelfCursor(cursor: { blockId: string; offset: number } | null): void {
199    if (this.self === null || cursor === null) {
200      this.selfCursor = cursor;
201      return;
202    }
203    // Self-cursor validity too: a stale block is dropped (no network
204    // frame is sent for an invalid cursor).
205    if (this.hasBlock !== undefined && !this.hasBlock(cursor.blockId)) {
206      this.selfCursor = null;
207      return;
208    }
209    this.selfCursor = { ...cursor };
210  }
211 
212  /** R5: the tab blurred — viewing goes null (the avatar dims). */
213  setSelfViewing(viewing: boolean): void {
214    this.selfViewing = viewing;
215  }
216 
217  /** The self awareness payload (what the provider broadcasts). */
218  selfState(): {
219    name?: string | undefined;
220    color?: string | undefined;
221    cursor: { blockId: string; offset: number } | null;
222    selection: string | null;
223  } {
224    return {
225      name: this.self?.name,
226      color: this.self?.color,
227      cursor: this.selfCursor,
228      selection: null,
229    };
230  }
231 
232  get selfViewingState(): boolean {
233    return this.selfViewing;
234  }
235 
236  private emit(): void {
237    this.onPeersChange?.([...this.peerMap.values()]);
238  }
239}
240