# unibus playground

An all-in-one, web-based sandbox for the **unibus** message bus. One command
brings up the entire stack embedded — no NATS to install, no services to wire —
and a browser UI lets you exercise the bus visually: create peers, create and
join rooms (cleartext or end-to-end encrypted), invite, publish, watch messages
arrive live, and kick members (forward secrecy).

This is a **playground** (see `.claude/rules/playgrounds.md`): it lives inside
the `unibus` app, reuses the parent Go module (no separate `go.mod`), is not
indexed, and keeps all runtime state under `playground/local_files/` (ephemeral,
safe to delete).

## Run

From the `unibus` app directory:

```bash
cd /home/enmanuel/fn_registry/projects/message_bus/apps/unibus
go run ./playground
```

Then open **http://localhost:7700** in your browser.

Stop with `Ctrl-C` — the server tears down the web UI, every bus client, the
control plane, and the embedded NATS cleanly (no orphaned processes).

## Architecture

The browser never speaks NATS. The Go server is the actual bus peer:

```
browser ──fetch/SSE──▶ playground server (:7700)
                            │  holds one unibus client per named peer
                            ├──HTTP──▶ membership control plane (127.0.0.1:8480)
                            └──NATS──▶ embedded NATS + JetStream (:4260)
```

- **:7700** — web UI (the only browser-facing port).
- **127.0.0.1:8480** — membership control plane (rooms, members, sealed keys,
  rekey, blobs). Internal only.
- **:4260** — embedded NATS + JetStream (the data plane). Internal only.

Each named peer gets its own long-term identity, persisted to
`playground/local_files/<name>.id`, so a peer keeps the same endpoint across
restarts. When a peer creates or joins a room, the server subscribes on its
behalf and streams every received frame to that peer's open browser tabs over
Server-Sent Events.

The playground only orchestrates the public unibus client API
(`CreateRoom`, `Join`, `Subscribe`, `Publish`, `Invite`, `Kick`); it never
reimplements bus or crypto logic.

## Try it: 2 peers + encryption + kick

1. Open **two browser tabs** on http://localhost:7700.
2. Tab A: type `alice`, click **Connect**.
3. Tab B: type `bob`, click **Connect**.
4. Tab A (alice): type a subject like `room.general`, tick **🔒 encrypted
   (E2E)**, click **Create room**. Copy the resulting `room_id`.
5. Tab A (alice): in the Action panel, pick `bob` as the target peer (use the
   ↻ button to refresh the peer list if needed) and click **Invite to this
   room**.
6. Tab B (bob): paste the `room_id` into the join field and click **Join**.
7. Type messages in **both** tabs and hit Send — each message appears live in
   both tabs, tagged with subject, sender, time, and 🔒 (encrypted) or `clear`.
8. Tab A (alice): click **Kick from this room** with `bob` selected. The room
   key rotates to a new epoch. New messages alice sends are no longer visible to
   bob — **forward secrecy**: bob no longer holds the current key.

Cleartext rooms (leave the checkbox unticked) behave like plain NATS fan-out:
fast, ephemeral, unsigned. Encrypted rooms are the Matrix-like mode: E2E
encrypted, persisted, and per-message signed.

## State / cleanup

All writable state lives under `playground/local_files/`:

- `<name>.id` — per-peer identity (private keys; treat like an SSH key).
- `play.db` — membership store (rooms, members, sealed keys).
- `blobs/` — media blob store.
- `js/` — embedded JetStream store.

Delete the whole `playground/local_files/` directory to reset to a clean slate.
It is gitignored and never distributed.