Awareness

Import it from @grafloria/engine.

The presence store for one peer: our own state, and everyone else's.

Deliberately transport-free. SyncAdapter wires it to a channel; a test wires it to nothing and drives it directly. It never sees an Op, a Replica or an OpLog, and that is not an accident — it is the containment.

WHY lastSeen IS A WALL CLOCK WHEN THE LOG WENT TO SUCH LENGTHS TO AVOID ONE

Because the question is different. The log asks "did A happen before B?", which a wall clock cannot answer across machines (they disagree, and they run backwards). Expiry asks "has it been 15 seconds since I last heard from Bob?" — measured entirely on MY clock, about MY receipts, comparing my own now() to my own earlier now(). Bob's clock is never consulted, so its wrongness cannot infect anything. Using a Lamport clock for a TIMEOUT would be the actual mistake: it has no relationship to seconds.

ts
Copy
class Awareness

Methods

• constructor(private readonly options: AwarenessOptions)
• get actor(): ActorId
• getLocalState(): AwarenessState — Our own published state, and the sequence a peer will LWW it by.
• get localSeq(): number
• setLocalState(patch: Partial<AwarenessState>): boolean — Merge a patch into our own state and bump the sequence.

Returns false when nothing actually changed — a mouse that has not moved must not burn a sequence number, wake the throttle, or send a message. (A mousemove fires on sub-pixel jitter and on scroll; without this guard an idle user with a resting hand is a 60Hz broadcaster.)

• applyRemote(actor: ActorId, state: AwarenessState | null, seq: number): AwarenessChange | null — Take a peer's published state.

seq is the whole reason a reordered transport does not make a cursor jump backwards: a sample older than the one we already hold is REFUSED, exactly as the LWW gate refuses a superseded op. Same idea, one scope down, and no shared machinery because the lifecycles have nothing in common.

• remove(actor: ActorId): AwarenessChange | null — An explicit bye, or a transport that told us the peer is gone.
• prune(): AwarenessChange | null — Drop peers we have not heard from inside the timeout.

THE GUARANTEE, as opposed to bye, which is merely the optimisation. A crashed tab, a closed laptop, a killed process and a severed cable all send no bye whatsoever, and every one of them must eventually stop showing a cursor.

• getPeers(): PeerPresence[] — Everyone but us.
• getPeer(actor: ActorId): PeerPresence | undefined
• get peerCount(): number
• clearPeers(): AwarenessChange | null — Everyone is gone (we disconnected — we can no longer vouch for anyone).
• onChange(listener: (change: AwarenessChange) => void): () => void