# @wrnexus/realtime

Typed rooms, secure message envelopes, browser room helpers, presence utilities, and complete realtime UI blocks for WRNexusJS.

## Server rooms

```ts
import { defineRoom } from "@wrnexus/realtime";

export default defineRoom("support", {
  async authorize(context) {
    return Boolean(context.user);
  },
  message(client, message) {
    client.broadcast(message);
  },
});
```

The package re-exports the hardened realtime registry from `@wrnexus/core`, including authentication, origin checks, quotas, message-size limits, schema validation hooks, and room authorization.

## Messages and browser helpers

```ts
import {
  createRealtimeMessage,
  createPresenceEvent,
  createTypingEvent,
  connectRoom,
  sendRoomMessage,
} from "@wrnexus/realtime";

const room = connectRoom("support", { query: { ticket: "T-100" } });
sendRoomMessage(
  room,
  createRealtimeMessage({
    type: "message",
    room: "support",
    data: { text: "Hello" },
  }),
);
```

Message IDs use Web Crypto. A runtime without secure randomness must provide an explicit message ID.

## Components

Enable `realtimePlugin()` and use:

- `<RealtimeRoom />`
- `<RealtimeMessageBubble />`
- `<MessageComposer />`
- `<RoomStatus />`
- `<RoomMeta />`
- `<PresenceList />`
- `<TypingIndicator />`

These package-owned blocks compose existing `@wrnexus/ui` components such as `Card`, `Alert`, `Avatar`, `Badge`, `Button`, `Input`, and `ChatBubble`.

Incoming messages can be bounded and constrained:

```ts
const message = parseRealtimeMessage(rawMessage, {
  maxBytes: 64 * 1024,
  maxDepth: 12,
  allowedTypes: ["message", "typing", "presence"],
  room: "support",
});
```

The parser rejects oversized payloads, circular/unsupported values, unsafe object keys, invalid message types, invalid room names, and room mismatches.

## Replay, acknowledgements, SSE, and monitoring

`createRealtimeHistory()` keeps a bounded sequenced log per room. Clients acknowledge a
sequence and `resume(room, clientId)` returns only missed events. A snapshot exposes room,
message, acknowledgement, and sequence counts for monitoring without exposing payloads.

```ts
const history = createRealtimeHistory({ limitPerRoom: 100 });
const entry = history.publish("support", message);
history.acknowledge("support", clientId, entry.sequence);
const missed = history.resume("support", clientId);
```

`realtimeSseResponse(stream, signal)` converts the same sequenced envelope into standards-based
Server-Sent Events with event IDs, event types, JSON data, cancellation, and no-cache headers.