bool.room — the ephemeral lane (presence + events)

[HomemadeToast57]

The second lane the SDK has needed since a prod build tried to ship live cursors through the database (one gateway invocation + one Postgres write per mouse move, cursors updating ~1/sec — "this was awful"). bool.room carries data that flies between the people currently in the app and is never stored; bool.entities remains the home of everything that must survive a reload.

The surface

type Presence = { cursor: { x: number; y: number } };

const others = bool.room.useOthers<Presence>();   // peers only — never you
const setMe  = bool.room.useSetMe<Presence>();    // merged, throttled, cleared on unmount

<div onPointerMove={(e) => setMe({ cursor: { x: e.clientX, y: e.clientY } })}>
  {others.map((o) => o.presence.cursor && <Cursor key={o.id} color={o.color} {...o.presence.cursor} />)}

bool.room.broadcast("reaction", { emoji: "🎉" });                        // echoes to you same-tick
bool.room.useEventListener("reaction", ({ from, data }) => burst(data)); // lifecycle handled inside
bool.room.useStatus();  // "connecting" | "live" | "unauthorized" | "unavailable"
bool.room.self;         // { id, color }

Why it's shaped this way (the review's findings, encoded)

This design went through a three-agent review (ecosystem research with sources, an AI-authoring failure-mode critique, and a naming/extensibility memo — full record lands in the platform's docs/2026-07-ephemeral-broadcast.md). Every choice below traces to a named failure:

Choice	The failure it kills
room, not live	"live" already means the durable lane — LiveEntityStore/LiveQueryOptions are public exports of this SDK, and the prompt's headline durable rule is "Live data … comes from useQuery". One word on both sides of the durable/ephemeral split is how chat messages end up in the lane that loses them on reload. room is also the industry noun (Liveblocks, InstantDB, Socket.IO, Colyseus, PartyKit) and gives per-board scoping a rename-free future: bool.room("board-1").
Presence rides track(), not events	Cursors built on fire-and-forget events leave ghosts nothing can clean up — no disconnect signal exists for app code. track() hydrates late joiners and auto-clears on disconnect.
presence: Partial<P>	The ghost-cursor crash: reading .cursor.x from a peer who joined but hasn't moved. Under the template's strict TS, the unguarded read fails the build — invisible-to-the-builder, certain-for-users crashes become compile errors.
useSetMe is a hook	A module-level setter can't know when its component unmounts, so a cursor freezes on everyone's screen after an in-app route change. The hook clears exactly the keys its component wrote.
Setter is imperative, from the raw handler	Any hook-argument/declarative shape forces pointer positions into React state → a re-render per mousemove across the board subtree.
Throttle inside the SDK (~25ms trailing)	A prompt rule asking the model to throttle is forgettable; hand-rolled debounces make peers see you only after you stop moving. Trailing edge guarantees the final position lands. The supabase-js event budget is raised to match — its default 10/s limiter would silently freeze cursors.
broadcast echoes locally, synchronously	Echo-off forces "burst locally AND send" (two paths, one forgettable); echo-via-server makes your own reaction wait a round trip. Local-first echo: one path, zero self-latency, one tab behaves like ten. Wire copies are filtered by sender id.
useEventListener owns the lifecycle	on() inside useEffect is three chances to fail (cleanup → StrictMode double-fire, deps, stale closure). Latest-ref semantics inside; nothing to hold wrong.
Colors derive from ids	Random-color-at-render strobes; transmitting colors is wasted bytes. Same hash on every client → everyone agrees, nothing sent.
No index signature	Hallucinated Liveblocks members (useMyPresence, useStorage, RoomProvider) become tsc errors instead of undefined is not a function in front of a user.
Own lifecycle machine (doorbell's gen/backoff/refresh pattern)	A presence-only app has zero entity subscribers, so the room can't piggyback the doorbell's ref-count. Same mint desk, same honesty rules: a refused wristband reports unauthorized and retries — never fakes liveness.

Testing

189 pass (16 new store tests + 4 react-layer). The store runs over a fake multi-peer wire: presence sync with self-exclusion and presence_ref stripping, the ghost-cursor empty-presence case, throttle collapse under a 60fps burst with the final-position guarantee, pre-join presence replay, per-key unmount clearing, same-tick echo, echo-once under a server that echoes anyway, cross-store event delivery with sender ids, oversized-payload throw, mint-refusal honesty, and ref-count teardown.

Platform dependency

Needs the platform half (PR on codehs/bool): topics.room from the wristband desk and the send policy scoped to the :room topic — disjoint from the doorbell topics by design, so a client can never forge a {table, op, row} message into anyone's entity state. On older platforms the room reports unavailable; nothing else in the SDK changes.

Publishing 0.4.0-next.0 to the next dist-tag from this branch so the platform preview can test against it before either PR merges — the same canary-first flow every battery has used.

[HomemadeToast57]

Status — ON HOLD (closed temporarily, branch preserved)

Pausing by Jack's call. This branch is the complete SDK side of the realtime arc, 0.4.0-next.0 through next.7, all published to the next dist-tag (latest remains 0.3.3 — production apps untouched).

Where it ended up

• RealtimeSession (session.ts): the one connection machine — mint/refresh/backoff/wake/identity-guarded teardown, every scar from the 2026-07-29 fires written once, one regression test per scar. Doorbell (280→118 lines) and room (~530) are pure consumers with zero connection code.
• bool.room callable: default room unchanged; bool.room("game:4") scopes with the identical surface. Rejected on the record (room.ts header): providers, join/leave ceremony, selectors, heavy hook names.
• Transport: membership on presence, state on broadcast (~me, full-state, fire-and-forget), 60Hz with room-size degradation, frame-coalesced emits, stable peer identities, UTF-8 byte guard, reserved ~ namespace.
• 216 tests, tsc clean at close.

Verified before closing

• Real-infra probes (scoped-room isolation, drop recovery, sustained 3×40Hz)
• Two real browsers: Xo Duel gameplay end-to-end on next.7
• Backward compat: 0.3.3 (this repo's main) verified doing full entity realtime against the new platform + policy v4

To resume

Reopen and merge (pairs with codehs/bool#600). At launch: publish 0.4.0 stable (same bits as next.7) so the platform can flip its seed range to ^0.4.0. Queued: $eq accepting arrays as jsonb equality (needs real-PostgREST verification first).

🤖 Generated with Claude Code