Update README to document current v0.4 API

- Remove outdated ServiceHost/ServiceClient/RTCDurableConnection documentation
- Document actual Rondevu, RondevuSignaler, and RondevuAPI classes
- Add pollOffers() combined polling documentation
- Add complete usage examples for offerer and answerer sides
- Document role-based ICE candidate filtering
- Add migration guide from v0.3.x

README.md

@@ -2,9 +2,9 @@
 
 [![npm version](https://img.shields.io/npm/v/@xtr-dev/rondevu-client)](https://www.npmjs.com/package/@xtr-dev/rondevu-client)
 
-🌐 **Simple, high-level WebRTC peer-to-peer connections**
+🌐 **Simple WebRTC signaling client with username-based discovery**
 
-TypeScript/JavaScript client for Rondevu, providing easy-to-use WebRTC connections with automatic signaling, username-based discovery, and built-in reconnection support.
+TypeScript/JavaScript client for Rondevu, providing WebRTC signaling with username claiming, service publishing/discovery, and efficient batch polling.
 
 **Related repositories:**
 - [@xtr-dev/rondevu-client](https://github.com/xtr-dev/rondevu-client) - TypeScript client library ([npm](https://www.npmjs.com/package/@xtr-dev/rondevu-client))
@@ -15,18 +15,15 @@ TypeScript/JavaScript client for Rondevu, providing easy-to-use WebRTC connectio
 
 ## Features
 
-- **High-Level Wrappers**: ServiceHost and ServiceClient eliminate WebRTC boilerplate
+- **Username Claiming**: Secure ownership with Ed25519 signatures
-- **Username-Based Discovery**: Connect to peers by username, not complex offer/answer exchange
+- **Service Publishing**: Publish services with multiple offers for connection pooling
-- **Semver-Compatible Matching**: Requesting chat@1.0.0 matches any compatible 1.x.x version
+- **Service Discovery**: Direct lookup, random discovery, or paginated search
-- **Privacy-First Design**: Services are hidden by default - no enumeration possible
+- **Efficient Batch Polling**: Single endpoint for answers and ICE candidates (50% fewer requests)
-- **Automatic Reconnection**: Built-in retry logic with exponential backoff
+- **Semantic Version Matching**: Compatible version resolution (chat:1.0.0 matches any 1.x.x)
-- **Message Queuing**: Messages sent while disconnected are queued and flushed on reconnect
-- **Cryptographic Username Claiming**: Secure ownership with Ed25519 signatures
-- **Service Publishing**: Package-style naming (chat.app@1.0.0) with multiple simultaneous offers
 - **TypeScript**: Full type safety and autocomplete
-- **Configurable Polling**: Exponential backoff with jitter to reduce server load
+- **Keypair Management**: Generate or reuse Ed25519 keypairs
 
-## Install
+## Installation
 
 ```bash
 npm install @xtr-dev/rondevu-client
@@ -34,376 +31,534 @@ npm install @xtr-dev/rondevu-client
 
 ## Quick Start
 
-### Hosting a Service (Alice)
+### Publishing a Service (Offerer)
 
 ```typescript
-import { RondevuService, ServiceHost } from '@xtr-dev/rondevu-client'
+import { Rondevu } from '@xtr-dev/rondevu-client'
 
-// Step 1: Create and initialize service
+// 1. Initialize and claim username
-const service = new RondevuService({
+const rondevu = new Rondevu({
   apiUrl: 'https://api.ronde.vu',
   username: 'alice'
 })
 
-await service.initialize()  // Generates keypair
+await rondevu.initialize()  // Generates keypair automatically
-await service.claimUsername()  // Claims username with signature
+await rondevu.claimUsername()
 
-// Step 2: Create ServiceHost
+// 2. Create WebRTC offer
-const host = new ServiceHost({
+const pc = new RTCPeerConnection({
-    service: 'chat.app@1.0.0',
+  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
-    rondevuService: service,
-    maxPeers: 5,  // Accept up to 5 connections
-    ttl: 300000   // 5 minutes
 })
 
-// Step 3: Listen for incoming connections
+const dc = pc.createDataChannel('chat')
-host.events.on('connection', (connection) => {
-    console.log('✅ New connection!')
 
-    connection.events.on('message', (msg) => {
+const offer = await pc.createOffer()
-        console.log('📨 Received:', msg)
+await pc.setLocalDescription(offer)
-        connection.sendMessage('Hello from Alice!')
+
+// 3. Publish service
+const service = await rondevu.publishService({
+  serviceFqn: 'chat:1.0.0@alice',
+  offers: [{ sdp: offer.sdp }],
+  ttl: 300000
 })
 
-    connection.events.on('state-change', (state) => {
+const offerId = service.offers[0].offerId
-        console.log('Connection state:', state)
-    })
-})
 
-host.events.on('error', (error) => {
+// 4. Poll for answer and ICE candidates (combined)
-    console.error('Host error:', error)
+let lastPollTimestamp = 0
-})
+const pollInterval = setInterval(async () => {
+  const result = await rondevu.pollOffers(lastPollTimestamp)
 
-// Step 4: Start hosting
+  // Check for answer
-await host.start()
+  if (result.answers.length > 0) {
-console.log('Service is now live! Others can connect to @alice')
+    const answer = result.answers.find(a => a.offerId === offerId)
+    if (answer) {
+      await pc.setRemoteDescription({ type: 'answer', sdp: answer.sdp })
+      lastPollTimestamp = answer.answeredAt
+    }
+  }
 
-// Later: stop hosting
+  // Process ICE candidates
-host.dispose()
+  if (result.iceCandidates[offerId]) {
+    const candidates = result.iceCandidates[offerId]
+      .filter(c => c.role === 'answerer')  // Only answerer's candidates
+
+    for (const item of candidates) {
+      await pc.addIceCandidate(new RTCIceCandidate(item.candidate))
+      lastPollTimestamp = Math.max(lastPollTimestamp, item.createdAt)
+    }
+  }
+}, 1000)
+
+// 5. Send ICE candidates
+pc.onicecandidate = (event) => {
+  if (event.candidate) {
+    rondevu.addOfferIceCandidates(
+      'chat:1.0.0@alice',
+      offerId,
+      [event.candidate.toJSON()]
+    )
+  }
+}
+
+// 6. Handle messages
+dc.onmessage = (event) => {
+  console.log('Received:', event.data)
+}
+
+dc.onopen = () => {
+  dc.send('Hello from Alice!')
+}
 ```
 
-### Connecting to a Service (Bob)
+### Connecting to a Service (Answerer)
 
 ```typescript
-import { RondevuService, ServiceClient } from '@xtr-dev/rondevu-client'
+import { Rondevu } from '@xtr-dev/rondevu-client'
 
-// Step 1: Create and initialize service
+// 1. Initialize
-const service = new RondevuService({
+const rondevu = new Rondevu({
   apiUrl: 'https://api.ronde.vu',
   username: 'bob'
 })
 
-await service.initialize()
+await rondevu.initialize()
-await service.claimUsername()
+await rondevu.claimUsername()
 
-// Step 2: Create ServiceClient
+// 2. Get service offer
-const client = new ServiceClient({
+const serviceData = await rondevu.getService('chat:1.0.0@alice')
-    username: 'alice',  // Connect to Alice
+
-    serviceFqn: 'chat.app@1.0.0',
+// 3. Create peer connection
-    rondevuService: service,
+const pc = new RTCPeerConnection({
-    autoReconnect: true,
+  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
-    maxReconnectAttempts: 5
 })
 
-// Step 3: Listen for connection events
+// 4. Set remote offer and create answer
-client.events.on('connected', (connection) => {
+await pc.setRemoteDescription({ type: 'offer', sdp: serviceData.sdp })
-    console.log('✅ Connected to Alice!')
 
-    connection.events.on('message', (msg) => {
+const answer = await pc.createAnswer()
-        console.log('📨 Received:', msg)
+await pc.setLocalDescription(answer)
-    })
 
-    // Send a message
+// 5. Send answer
-    connection.sendMessage('Hello from Bob!')
+await rondevu.postOfferAnswer(
-})
+  serviceData.serviceFqn,
+  serviceData.offerId,
+  answer.sdp
+)
 
-client.events.on('disconnected', () => {
+// 6. Send ICE candidates
-    console.log('🔌 Disconnected')
+pc.onicecandidate = (event) => {
-})
+  if (event.candidate) {
+    rondevu.addOfferIceCandidates(
+      serviceData.serviceFqn,
+      serviceData.offerId,
+      [event.candidate.toJSON()]
+    )
+  }
+}
 
-client.events.on('reconnecting', ({ attempt, maxAttempts }) => {
+// 7. Poll for ICE candidates
-    console.log(`🔄 Reconnecting (${attempt}/${maxAttempts})...`)
+let lastIceTimestamp = 0
-})
+const iceInterval = setInterval(async () => {
+  const result = await rondevu.getOfferIceCandidates(
+    serviceData.serviceFqn,
+    serviceData.offerId,
+    lastIceTimestamp
+  )
 
-client.events.on('error', (error) => {
+  for (const item of result.candidates) {
-    console.error('❌ Error:', error)
+    if (item.candidate) {
-})
+      await pc.addIceCandidate(new RTCIceCandidate(item.candidate))
+      lastIceTimestamp = item.createdAt
+    }
+  }
+}, 1000)
 
-// Step 4: Connect
+// 8. Handle data channel
-await client.connect()
+pc.ondatachannel = (event) => {
+  const dc = event.channel
 
-// Later: disconnect
+  dc.onmessage = (event) => {
-client.dispose()
+    console.log('Received:', event.data)
+  }
+
+  dc.onopen = () => {
+    dc.send('Hello from Bob!')
+  }
+}
 ```
 
-## Core Concepts
-
-### RondevuService
-
-Handles authentication and username management:
-- Generates Ed25519 keypair for signing
-- Claims usernames with cryptographic proof
-- Provides API client for signaling server
-
-### ServiceHost
-
-High-level wrapper for hosting a WebRTC service:
-- Automatically creates and publishes offers
-- Handles incoming connections
-- Manages ICE candidate exchange
-- Supports multiple simultaneous peers
-
-### ServiceClient
-
-High-level wrapper for connecting to services:
-- Discovers services by username
-- Handles offer/answer exchange automatically
-- Built-in auto-reconnection with exponential backoff
-- Event-driven API
-
-### RTCDurableConnection
-
-Low-level connection wrapper (used internally):
-- Manages WebRTC PeerConnection lifecycle
-- Handles ICE candidate polling
-- Provides message queue for reliability
-- State management and events
-
 ## API Reference
 
-### RondevuService
+### Rondevu Class
+
+Main class for all Rondevu operations.
 
 ```typescript
-const service = new RondevuService({
+import { Rondevu } from '@xtr-dev/rondevu-client'
+
+const rondevu = new Rondevu({
   apiUrl: string,           // Signaling server URL
   username: string,         // Your username
-    keypair?: Keypair         // Optional: reuse existing keypair
+  keypair?: Keypair,        // Optional: reuse existing keypair
+  credentials?: Credentials // Optional: reuse existing credentials
+})
+```
+
+#### Initialization
+
+```typescript
+// Initialize (generates keypair and credentials if not provided)
+await rondevu.initialize(): Promise<void>
+```
+
+#### Username Management
+
+```typescript
+// Claim username with Ed25519 signature
+await rondevu.claimUsername(): Promise<void>
+
+// Check if username is claimed (checks server)
+await rondevu.isUsernameClaimed(): Promise<boolean>
+
+// Get username
+rondevu.getUsername(): string
+
+// Get public key
+rondevu.getPublicKey(): string | null
+
+// Get keypair (for backup/storage)
+rondevu.getKeypair(): Keypair | null
+```
+
+#### Service Publishing
+
+```typescript
+// Publish service with offers
+await rondevu.publishService({
+  serviceFqn: string,  // e.g., 'chat:1.0.0@alice'
+  offers: Array<{ sdp: string }>,
+  ttl?: number         // Optional: milliseconds (default: 300000)
+}): Promise<Service>
+```
+
+#### Service Discovery
+
+```typescript
+// Direct lookup by FQN (with username)
+await rondevu.getService('chat:1.0.0@alice'): Promise<ServiceOffer>
+
+// Random discovery (without username)
+await rondevu.discoverService('chat:1.0.0'): Promise<ServiceOffer>
+
+// Paginated discovery (returns multiple offers)
+await rondevu.discoverServices(
+  'chat:1.0.0',  // serviceVersion
+  10,            // limit
+  0              // offset
+): Promise<{ services: ServiceOffer[], count: number, limit: number, offset: number }>
+```
+
+#### WebRTC Signaling
+
+```typescript
+// Post answer SDP
+await rondevu.postOfferAnswer(
+  serviceFqn: string,
+  offerId: string,
+  sdp: string
+): Promise<{ success: boolean, offerId: string }>
+
+// Get answer SDP (offerer polls this - deprecated, use pollOffers instead)
+await rondevu.getOfferAnswer(
+  serviceFqn: string,
+  offerId: string
+): Promise<{ sdp: string, offerId: string, answererId: string, answeredAt: number } | null>
+
+// Combined polling for answers and ICE candidates (RECOMMENDED for offerers)
+await rondevu.pollOffers(since?: number): Promise<{
+  answers: Array<{
+    offerId: string
+    serviceId?: string
+    answererId: string
+    sdp: string
+    answeredAt: number
+  }>
+  iceCandidates: Record<string, Array<{
+    candidate: any
+    role: 'offerer' | 'answerer'
+    peerId: string
+    createdAt: number
+  }>>
+}>
+
+// Add ICE candidates
+await rondevu.addOfferIceCandidates(
+  serviceFqn: string,
+  offerId: string,
+  candidates: RTCIceCandidateInit[]
+): Promise<{ count: number, offerId: string }>
+
+// Get ICE candidates (with polling support)
+await rondevu.getOfferIceCandidates(
+  serviceFqn: string,
+  offerId: string,
+  since: number = 0
+): Promise<{ candidates: IceCandidate[], offerId: string }>
+```
+
+### RondevuSignaler Class
+
+Higher-level signaling abstraction with automatic polling and event listeners.
+
+```typescript
+import { RondevuSignaler } from '@xtr-dev/rondevu-client'
+
+const signaler = new RondevuSignaler(
+  rondevu: Rondevu,
+  service: string,      // Service FQN without username (e.g., 'chat:1.0.0')
+  host?: string,        // Optional: target username for answerer
+  pollingConfig?: {
+    initialInterval?: number      // Default: 500ms
+    maxInterval?: number           // Default: 5000ms
+    backoffMultiplier?: number     // Default: 1.5
+    maxRetries?: number            // Default: 50
+    jitter?: boolean               // Default: true
+  }
+)
+```
+
+#### Offerer Side
+
+```typescript
+// Set offer (automatically starts polling for answer and ICE)
+await signaler.setOffer(offer: RTCSessionDescriptionInit): Promise<void>
+
+// Listen for answer
+const unbind = signaler.addAnswerListener((answer) => {
+  console.log('Received answer:', answer)
 })
 
-// Initialize service (generates keypair if not provided)
+// Listen for ICE candidates
-await service.initialize(): Promise<void>
+signaler.addListener((candidate) => {
-
+  console.log('Received ICE candidate:', candidate)
-// Claim username with cryptographic signature
-await service.claimUsername(): Promise<void>
-
-// Check if username is claimed
-service.isUsernameClaimed(): boolean
-
-// Get current username
-service.getUsername(): string
-
-// Get keypair
-service.getKeypair(): Keypair
-
-// Get API client
-service.getAPI(): RondevuAPI
-```
-
-### ServiceHost
-
-```typescript
-const host = new ServiceHost({
-    service: string,              // Service FQN (e.g., 'chat.app@1.0.0')
-    rondevuService: RondevuService,
-    maxPeers?: number,            // Default: 5
-    ttl?: number,                 // Default: 300000 (5 minutes)
-    isPublic?: boolean,           // Default: true
-    rtcConfiguration?: RTCConfiguration
 })
 
-// Start hosting
+// Send ICE candidate
-await host.start(): Promise<void>
+await signaler.addIceCandidate(candidate: RTCIceCandidate): Promise<void>
-
-// Stop hosting and cleanup
-host.dispose(): void
-
-// Get all active connections
-host.getConnections(): RTCDurableConnection[]
-
-// Events
-host.events.on('connection', (conn: RTCDurableConnection) => {})
-host.events.on('error', (error: Error) => {})
 ```
 
-### ServiceClient
+#### Answerer Side
 
 ```typescript
-const client = new ServiceClient({
+// Listen for offer (automatically searches for service)
-    username: string,             // Host username to connect to
+const unbind = signaler.addOfferListener((offer) => {
-    serviceFqn: string,          // Service FQN (e.g., 'chat.app@1.0.0')
+  console.log('Received offer:', offer)
-    rondevuService: RondevuService,
-    autoReconnect?: boolean,     // Default: true
-    maxReconnectAttempts?: number, // Default: 5
-    rtcConfiguration?: RTCConfiguration
 })
 
-// Connect to service
+// Set answer (automatically starts polling for ICE)
-await client.connect(): Promise<RTCDurableConnection>
+await signaler.setAnswer(answer: RTCSessionDescriptionInit): Promise<void>
 
-// Disconnect and cleanup
+// Send ICE candidate
-client.dispose(): void
+await signaler.addIceCandidate(candidate: RTCIceCandidate): Promise<void>
 
-// Get current connection
+// Listen for ICE candidates
-client.getConnection(): RTCDurableConnection | null
+signaler.addListener((candidate) => {
-
+  console.log('Received ICE candidate:', candidate)
-// Events
+})
-client.events.on('connected', (conn: RTCDurableConnection) => {})
-client.events.on('disconnected', () => {})
-client.events.on('reconnecting', (info: { attempt: number, maxAttempts: number }) => {})
-client.events.on('error', (error: Error) => {})
 ```
 
-### RTCDurableConnection
+#### Cleanup
 
 ```typescript
-// Connection state
+// Stop all polling and cleanup
-connection.state: 'connected' | 'connecting' | 'disconnected'
+signaler.dispose(): void
-
-// Send message (returns true if sent, false if queued)
-await connection.sendMessage(message: string): Promise<boolean>
-
-// Queue message for sending when connected
-await connection.queueMessage(message: string, options?: QueueMessageOptions): Promise<void>
-
-// Disconnect
-connection.disconnect(): void
-
-// Events
-connection.events.on('message', (msg: string) => {})
-connection.events.on('state-change', (state: ConnectionStates) => {})
 ```
 
-## Configuration
+### RondevuAPI Class
 
-### Polling Configuration
+Low-level HTTP API client (used internally by Rondevu class).
-
-The signaling uses configurable polling with exponential backoff:
 
 ```typescript
-// Default polling config
+import { RondevuAPI } from '@xtr-dev/rondevu-client'
-{
+
-    initialInterval: 500,      // Start at 500ms
+const api = new RondevuAPI(
-    maxInterval: 5000,         // Max 5 seconds
+  baseUrl: string,
-    backoffMultiplier: 1.5,    // Increase by 1.5x each time
+  credentials?: Credentials
-    maxRetries: 50,            // Max 50 attempts
+)
-    jitter: true               // Add random 0-100ms to prevent thundering herd
+
+// Set credentials
+api.setCredentials(credentials: Credentials): void
+
+// Register peer
+await api.register(): Promise<Credentials>
+
+// Check username
+await api.checkUsername(username: string): Promise<{
+  available: boolean
+  publicKey?: string
+  claimedAt?: number
+  expiresAt?: number
+}>
+
+// Claim username
+await api.claimUsername(
+  username: string,
+  publicKey: string,
+  signature: string,
+  message: string
+): Promise<{ success: boolean, username: string }>
+
+// ... (all other HTTP endpoints)
+```
+
+#### Cryptographic Helpers
+
+```typescript
+// Generate Ed25519 keypair
+const keypair = await RondevuAPI.generateKeypair(): Promise<Keypair>
+
+// Sign message
+const signature = await RondevuAPI.signMessage(
+  message: string,
+  privateKey: string
+): Promise<string>
+
+// Verify signature
+const valid = await RondevuAPI.verifySignature(
+  message: string,
+  signature: string,
+  publicKey: string
+): Promise<boolean>
+```
+
+## Types
+
+```typescript
+interface Keypair {
+  publicKey: string   // Base64-encoded Ed25519 public key
+  privateKey: string  // Base64-encoded Ed25519 private key
+}
+
+interface Credentials {
+  peerId: string
+  secret: string
+}
+
+interface Service {
+  serviceId: string
+  offers: ServiceOffer[]
+  username: string
+  serviceFqn: string
+  createdAt: number
+  expiresAt: number
+}
+
+interface ServiceOffer {
+  offerId: string
+  sdp: string
+  createdAt: number
+  expiresAt: number
+}
+
+interface IceCandidate {
+  candidate: RTCIceCandidateInit
+  createdAt: number
+}
+
+interface PollingConfig {
+  initialInterval?: number     // Default: 500ms
+  maxInterval?: number          // Default: 5000ms
+  backoffMultiplier?: number    // Default: 1.5
+  maxRetries?: number           // Default: 50
+  jitter?: boolean              // Default: true
 }
 ```
 
-This is handled automatically - no configuration needed.
+## Advanced Usage
-
-### WebRTC Configuration
-
-Provide custom STUN/TURN servers:
-
-```typescript
-const host = new ServiceHost({
-    service: 'chat.app@1.0.0',
-    rondevuService: service,
-    rtcConfiguration: {
-        iceServers: [
-            { urls: 'stun:stun.l.google.com:19302' },
-            {
-                urls: 'turn:turn.example.com:3478',
-                username: 'user',
-                credential: 'pass'
-            }
-        ]
-    }
-})
-```
-
-## Username Rules
-
-- **Format**: Lowercase alphanumeric + dash (`a-z`, `0-9`, `-`)
-- **Length**: 3-32 characters
-- **Pattern**: `^[a-z0-9][a-z0-9-]*[a-z0-9]$`
-- **Validity**: 365 days from claim/last use
-- **Ownership**: Secured by Ed25519 public key signature
-
-## Examples
-
-### Chat Application
-
-See [demo/demo.js](./demo/demo.js) for a complete working example.
 
 ### Persistent Keypair
 
 ```typescript
 // Save keypair to localStorage
-const service = new RondevuService({
+const rondevu = new Rondevu({
   apiUrl: 'https://api.ronde.vu',
   username: 'alice'
 })
 
-await service.initialize()
+await rondevu.initialize()
-await service.claimUsername()
+await rondevu.claimUsername()
 
 // Save for later
-localStorage.setItem('rondevu-keypair', JSON.stringify(service.getKeypair()))
+localStorage.setItem('rondevu-keypair', JSON.stringify(rondevu.getKeypair()))
-localStorage.setItem('rondevu-username', service.getUsername())
 
 // Load on next session
 const savedKeypair = JSON.parse(localStorage.getItem('rondevu-keypair'))
-const savedUsername = localStorage.getItem('rondevu-username')
 
-const service2 = new RondevuService({
+const rondevu2 = new Rondevu({
   apiUrl: 'https://api.ronde.vu',
-    username: savedUsername,
+  username: 'alice',
   keypair: savedKeypair
 })
 
-await service2.initialize()  // Reuses keypair
+await rondevu2.initialize()  // Reuses keypair
 ```
 
-### Message Queue Example
+### Service Discovery
 
 ```typescript
-// Messages are automatically queued if not connected yet
+// Get a random available service
-client.events.on('connected', (connection) => {
+const service = await rondevu.discoverService('chat:1.0.0')
-    // Send immediately
+console.log('Discovered:', service.username)
-    connection.sendMessage('Hello!')
-})
 
-// Or queue for later
+// Get multiple services (paginated)
-await client.connect()
+const result = await rondevu.discoverServices('chat:1.0.0', 10, 0)
-const conn = client.getConnection()
+console.log(`Found ${result.count} services:`)
-await conn.queueMessage('This will be sent when connected', {
+result.services.forEach(s => console.log(`  - ${s.username}`))
-    expiresAt: Date.now() + 60000  // Expire after 1 minute
-})
 ```
 
-## Migration from v0.9.x
+### Multiple Concurrent Offers
-
-v0.11.0+ introduces high-level wrappers, RESTful API changes, and semver-compatible discovery:
-
-**API Changes:**
-- Server endpoints restructured (`/usernames/*` → `/users/*`)
-- Added `ServiceHost` and `ServiceClient` wrappers
-- Message queue fully implemented
-- Configurable polling with exponential backoff
-- Removed deprecated `cleanup()` methods (use `dispose()`)
-- **v0.11.0+**: Services use `offers` array instead of single `sdp`
-- **v0.11.0+**: Semver-compatible service discovery (chat@1.0.0 matches 1.x.x)
-- **v0.11.0+**: All services are hidden - no listing endpoint
-- **v0.11.0+**: Services support multiple simultaneous offers for connection pooling
-
-**Migration Guide:**
 
 ```typescript
-// Before (v0.9.x) - Manual WebRTC setup
+// Publish service with multiple offers for connection pooling
-const signaler = new RondevuSignaler(service, 'chat@1.0.0')
+const offers = []
-const context = new WebRTCContext()
+const connections = []
-const pc = context.createPeerConnection()
-// ... 50+ lines of boilerplate
 
-// After (v0.11.0) - ServiceHost wrapper
+for (let i = 0; i < 5; i++) {
-const host = new ServiceHost({
+  const pc = new RTCPeerConnection(rtcConfig)
-    service: 'chat@1.0.0',
+  const dc = pc.createDataChannel('chat')
-    rondevuService: service
+  const offer = await pc.createOffer()
+  await pc.setLocalDescription(offer)
+
+  offers.push({ sdp: offer.sdp })
+  connections.push({ pc, dc })
+}
+
+const service = await rondevu.publishService({
+  serviceFqn: 'chat:1.0.0@alice',
+  offers,
+  ttl: 300000
 })
-await host.start()
+
-// Done!
+// Each offer can be answered independently
+console.log(`Published ${service.offers.length} offers`)
+```
+
+### Custom Polling Configuration
+
+```typescript
+const signaler = new RondevuSignaler(
+  rondevu,
+  'chat:1.0.0',
+  'alice',
+  {
+    initialInterval: 1000,    // Start at 1 second
+    maxInterval: 10000,       // Max 10 seconds
+    backoffMultiplier: 2,     // Double each time
+    maxRetries: 30,           // Stop after 30 retries
+    jitter: true              // Add randomness
+  }
+)
 ```
 
 ## Platform Support
@@ -419,38 +574,66 @@ npm install wrtc
 ```
 
 ```typescript
-import { WebRTCContext } from '@xtr-dev/rondevu-client'
 import { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } from 'wrtc'
 
-// Configure WebRTC context
+// Use wrtc implementations
-const context = new WebRTCContext({
+const pc = new RTCPeerConnection()
-    RTCPeerConnection,
-    RTCSessionDescription,
-    RTCIceCandidate
-} as any)
 ```
 
-## TypeScript
+## Username Rules
 
-All types are exported:
+- **Format**: Lowercase alphanumeric + dash (`a-z`, `0-9`, `-`)
+- **Length**: 3-32 characters
+- **Pattern**: `^[a-z0-9][a-z0-9-]*[a-z0-9]$`
+- **Validity**: 365 days from claim/last use
+- **Ownership**: Secured by Ed25519 public key signature
+
+## Service FQN Format
+
+- **Format**: `service:version@username`
+- **Service**: Lowercase alphanumeric + dash (e.g., `chat`, `video-call`)
+- **Version**: Semantic versioning (e.g., `1.0.0`, `2.1.3`)
+- **Username**: Claimed username
+- **Example**: `chat:1.0.0@alice`
+
+## Examples
+
+See the [demo](https://github.com/xtr-dev/rondevu-demo) for a complete working example with React UI.
+
+## Migration from v0.3.x
+
+v0.4.0 removes high-level abstractions and uses manual WebRTC setup:
+
+**Removed:**
+- `ServiceHost` class (use manual WebRTC + `publishService()`)
+- `ServiceClient` class (use manual WebRTC + `getService()`)
+- `RTCDurableConnection` class (use native WebRTC APIs)
+- `RondevuService` class (merged into `Rondevu`)
+
+**Added:**
+- `pollOffers()` - Combined polling for answers and ICE candidates
+- `RondevuSignaler` - Simplified signaling with automatic polling
+
+**Migration Example:**
 
 ```typescript
-import type {
+// Before (v0.3.x) - ServiceHost
-    RondevuServiceOptions,
+const host = new ServiceHost({
-    ServiceHostOptions,
+  service: 'chat@1.0.0',
-    ServiceHostEvents,
+  rondevuService: service
-    ServiceClientOptions,
+})
-    ServiceClientEvents,
+await host.start()
-    ConnectionInterface,
+
-    ConnectionEvents,
+// After (v0.4.0) - Manual setup
-    ConnectionStates,
+const pc = new RTCPeerConnection()
-    Message,
+const dc = pc.createDataChannel('chat')
-    QueueMessageOptions,
+const offer = await pc.createOffer()
-    Signaler,
+await pc.setLocalDescription(offer)
-    PollingConfig,
+
-    Credentials,
+await rondevu.publishService({
-    Keypair
+  serviceFqn: 'chat:1.0.0@alice',
-} from '@xtr-dev/rondevu-client'
+  offers: [{ sdp: offer.sdp }]
+})
 ```
 
 ## License