Updates

applications-collab/hyper-p2p-collab-room/docs/api.md

@@ -1,23 +1,102 @@
-# hyper-p2p-collab-room API
+# API: hyper-p2p-collab-room
 
-**Status:** scaffold · **Protocol:** `collab-room/v1`
+**Protocol:** `collab-room/v1`
 
-## Class `HyperP2PCollabRoom`
+**Export:** `HyperP2PCollabRoom`
 
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
 
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
 
-### `getStats()`
+## Constructor
 
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
+const mod = new HyperP2PCollabRoom(opts)
+```
 
-### `ready()`
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `topic` | varies | null | topic |
+| `keyPair` | KeyPair | random Ed25519 | keyPair |
 
-Resolves immediately (no-op).
+## Methods
 
-## Wire (planned)
+### `createRoom(roomId, meta = {})`
 
-| Message | Direction | Notes |
-|---------|-----------|-------|
-| TBD | gossip | Defined in implementation pass |
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `join(roomId, meta = {})`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `leave(roomId)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `broadcast(roomId, event)`
+
+- **Returns:** `value`
+- **Throws:**
+  - `Error: event object required`
+  - `Error: room not found`
+
+### `getMembers(roomId)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `getEvents(roomId, limit = 50)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `getStats(—)`
+
+- **Returns:** `object`
+- **Throws:** — (none documented in method body)
+
+### `ready(—)`
+
+- **Returns:** `Promise`
+- **Throws:** — (none documented in method body)
+
+### `close(—)`
+
+- **Returns:** `Promise<void>`
+- **Throws:** — (none documented in method body)
+
+## Events
+
+| Event | Payload |
+|-------|---------|
+| `broadcast` | roomId, event, remote |
+| `closed` | no payload |
+| `join` | payload object |
+| `leave` | peer |
+| `peer-joined` | roomId, member |
+| `peer-left` | roomId, peer |
+| `room-created` | payload object |
+
+## getStats()
+
+Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
+Library-only modules may include `mode: 'local'`.
+
+## Errors
+
+Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
+
+## P2P
+
+When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `collab-room/v1`.
+
+## Testing
+
+```bash
+npm install && npm test
+```
+
+Integration: [`../../../real_tests/integration/collab-room-two-node.js`](../../../real_tests/integration/collab-room-two-node.js)

applications-collab/hyper-p2p-collab-room/docs/architecture.md

@@ -1,15 +1,45 @@
-# hyper-p2p-collab-room architecture
+# Architecture: hyper-p2p-collab-room
 
-**Tier:** scaffold · **Category:** `applications-collab`
+**Category:** General
 
-## Role
+```mermaid
+flowchart LR
+  App[Application] --> Mod[HyperP2PCollabRoom]
+  Mod --> Mux[Protomux collab-room/v1]
+  Mux --> Swarm[Hyperswarm]
+```
 
-Collaboration room primitive.
+## Sequence (P2P)
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant Mod as Module
+  participant SW as Hyperswarm
+  participant Peer
+  App->>Mod: ready(topic)
+  Mod->>SW: join(topic)
+  SW->>Peer: connection
+  Mod->>Peer: gossip / Protomux
+  Peer-->>Mod: onmessage
+  Mod-->>App: emit(event)
+```
+
+## Wire messages
+
+| type | fields | direction | behavior |
+|------|--------|-----------|----------|
+| `broadcast` | event, roomId | gossip | Handled in onmessage / gossipSend |
+| `join` | event, member, peer, roomId, type | gossip | Handled in onmessage / gossipSend |
+| `leave` | event, peer, roomId, type | gossip | Handled in onmessage / gossipSend |
+
+## State model
+
+- In-memory `Map` / `Set` structures for hot path
+- Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
+- `close()` tears down swarm, timers, and clears ephemeral state
 
 ## Composition
 
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 
-## Holepunch boundary
-
-Inspiration: n/a