@neta-art/cohub 4.8.0 → 4.9.0

package/docs/work-runtime-guide.md

@@ -985,6 +985,98 @@ Before publishing your Work, verify each item:
 
 ---
 
+## Realtime rooms in a Work
+
+Realtime rooms are available through `client.work.realtime` and use the Work
+runtime identity automatically. They do not require a viewer scope or an
+additional consent dialog.
+
+```js
+const room = await client.work.realtime.createRoom({
+  code: "TEAM-ALPHA",
+  maxParticipants: 64,
+  expiresInSeconds: 2 * 60 * 60,
+});
+
+const stop = room.subscribe("shared.state.updated", (event) => {
+  console.log(event.sequence, event.data);
+});
+
+await room.publish("shared.state.updated", { value: 42 });
+await room.leave();
+stop();
+```
+
+A Work can join an existing room with `client.work.realtime.joinRoom({ code })`.
+Room codes are scoped to the Work and are case-insensitive. They identify a
+room but are not credentials; the runtime Work session and the short-lived
+room admission ticket provide authorization.
+
+`expiresInSeconds` is an absolute lifetime measured from server-side creation.
+Activity never extends it, and the maximum lifetime is 24 hours. The room is
+logically expired at `expiresAt`; connected clients receive a closed state and
+new publishes or joins fail.
+
+Each Work can hold up to 512 active rooms at once. Expired rooms free their slot
+automatically, and `createRoom` fails with HTTP 429 and `ROOM_QUOTA_EXCEEDED`
+when the limit is reached.
+
+Events are generic JSON payloads. The SDK does not define business event names,
+and the Work should define its own event map in TypeScript. Events are ordered
+and acknowledged while a connection is live. Events missed during a disconnect
+are not replayed, so applications should publish a current state snapshot after
+rejoining when needed. Payloads are transient and are not stored in the Work.
+
+### High-frequency events
+
+`publish` waits for a server ack, so a loop that awaits every call is capped at
+roughly `1000 / rtt` events per second. For input frames and other high-rate
+traffic use `send`, which skips the ack:
+
+```js
+// 30 input frames per second, no per-event round trip
+room.send("input.frame", { frame, pad });
+
+room.onSendError((error) => console.warn("dropped frame", error.message));
+room.onStateChange((state) => { if (state !== "joined") pauseSimulation(); });
+```
+
+Ordering is still guaranteed by the server. Failures (rate limit, membership lost)
+arrive through `onSendError` for the room that failed, and calls while the room is
+not joined are dropped rather than queued. An invalid event name, an oversized
+payload, or data JSON cannot encode (`undefined`, a function, a symbol) is rejected
+locally before reaching the server. Use `publish` when a specific event must be
+confirmed, and `send` for the steady stream.
+
+### Seats and participant identity
+
+By default every connection is its own participant, so a viewer who opens the
+Work in two tabs appears twice. This suits presence-style features such as
+multiple cursors. Each member also carries an opaque `userKey` that is stable per
+room and viewer, so an application can group or de-duplicate participants without
+seeing the underlying account.
+
+A room created with `seatPerUser: true` instead gives each viewer at most one
+seat:
+
+```js
+const room = await client.work.realtime.createRoom({
+  maxParticipants: 2,
+  seatPerUser: true,
+});
+```
+
+Joining then takes over the seat the viewer already holds instead of consuming
+another one. This matters for small fixed-size rooms: after an unclean disconnect
+(a killed tab, a dropped network, a sleeping laptop) the previous seat stays
+leased for up to a minute, and in a two-seat room that would otherwise block the
+viewer from rejoining. A clean close releases the seat immediately either way.
+
+On takeover the server keeps the existing participant id, so peers see no churn,
+and `room.participantId` reflects the server value rather than the id issued at
+admission. The superseded connection is closed with reason `superseded` and emits
+no leave event, because the participant is still present.
+
 ## 8. Publishing a Work (API/SDK)
 
 Before creating a Work through the API, ensure the owner has a username and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Cohub SDK for spaces, sessions, boards, and realtime agent collaboration.",
   "license": "Apache-2.0",
   "private": false,