Presence

Import these from @grafloria/renderer.

Functions

actorColor

Deterministic per-actor colour.

Deterministic MATTERS: the colour must be the same on every peer's screen, or "the blue cursor is Ana" is true for you and false for me. Derived from the actor id, so no coordination, no allocation table, and no message on the wire to agree.

ts
Copy
function actorColor(actor: string): string

actorInitials

ts
Copy
function actorInitials(name: string): string

bindPresence

Mount a presence overlay on a diagram and feed it from a sync session.

ts
Copy
const diagram = createDiagram(el, { nodes, edges });
const session = createSyncSession(diagram.getModel(), transport, { actor: userId });
session.join();
bindPresence(diagram, session, { name: 'Ana' });

ts
Copy
function bindPresence(
  instance: DiagramInstance,
  source: PresenceSource,
  options: BindPresenceOptions = {}
): PresenceBinding

contrastingTextColor

Black or white — whichever is actually READABLE on background.

FOUND BY AXE, IN THE a11y GATE, AFTER THE UNIT TESTS WERE ALL GREEN

The name badge was white text on the peer's colour. For a blue or purple actor that is fine. For a green or yellow one — hsl(124, 72%, 52%) — it is white on light green, a contrast ratio of about 2:1, and a user with low vision simply cannot read whose cursor it is. It is a coin flip decided by a hash of the actor id, which is the worst kind of accessibility bug: it works on your machine, for your account, every time you test it.

The unit tests could not have caught this. They assert aria-hidden="true", which is about ASSISTIVE TECH — and this is not an AT problem at all. It is a problem for someone looking straight at the screen with their eyes. Only the real axe audit over a real page with real badges on it could find it, which is the entire argument for that gate existing.

(Note that aria-hidden does NOT excuse it, and axe is right to say so: hiding text from a screen reader does not hide it from a sighted user with poor contrast sensitivity.)

THE MATH. Pick whichever of pure black and pure white contrasts better. The two curves cross at a background luminance of ~0.179, where BOTH give 4.58:1 — above the 4.5:1 WCAG AA threshold for normal text. So this choice is guaranteed to pass for EVERY hue, not merely for the ones I happened to look at.

ts
Copy
function contrastingTextColor(background: string): string

Classes

PresenceOverlay

The presence layer.

Owns one <div> inside the diagram root, and nothing else. It does not know about the SVGRenderer, the VNodePatcher, the RenderScheduler or the model, and it must not: the moment it can reach the render loop, someone will make it call into it.

ts
Copy
class PresenceOverlay

Properties

Methods

• constructor(private readonly options: PresenceOverlayOptions)
• get element(): HTMLElement — For the tests and the a11y audit — the DOM this owns, and nothing more.
• get peerCount(): number
• setPeers(peers: readonly PresencePeer[]): void — Publish the full peer set. Idempotent, and a peer that is gone is REMOVED — presence has no tombstones and no history; the current picture is the entire truth.
• remove(actor: string): void
• clear(): void
• dispose(): void

Constants

PRESENCE_LAYER_CLASS

ts
Copy
const PRESENCE_LAYER_CLASS: "grafloria-presence-layer"

Interfaces

BindPresenceOptions

ts
Copy
interface BindPresenceOptions

Properties

PresenceBinding

ts
Copy
interface PresenceBinding

Properties

Members

• dispose(): void

PresenceOverlayOptions

ts
Copy
interface PresenceOverlayOptions

Properties

PresencePeer

One peer, as far as the overlay is concerned. Ephemeral by construction.

ts
Copy
interface PresencePeer

Properties

PresenceSource

What presence needs from a sync session — STRUCTURAL, not the concrete SyncAdapter.

The renderer therefore gains no hard dependency on the sync layer, a host can drive presence from its own backend (a Firebase channel, a Phoenix presence, a server-sent event stream) without adopting our transport at all, and a test can hand it a fake. The real SyncAdapter satisfies it exactly, which is what presence-reachability.spec.ts proves.

ts
Copy
interface PresenceSource

Properties

Members

• setAwareness(patch: Record<string, unknown>): void

Types

BoundsLookup

World-space box of an entity, so the overlay can outline a remote selection.

ts
Copy
type BoundsLookup = (entityId: string) => { x: number; y: number; width: number; height: number } | null;