@rlanz/socket 0.0.1-5 → 0.0.1-7

package/README.md

@@ -8,12 +8,24 @@ WebSocket integration for AdonisJS, powered by [`ws`](https://github.com/websock
 yarn add @rlanz/socket
 ```
 
-Register the provider in your AdonisJS application:
+Configure the package in your AdonisJS application:
+
+```sh
+node ace configure @rlanz/socket
+```
+
+This registers the provider for the `web` environment only, so Ace commands do not boot the
+WebSocket integration, and installs the Assembler hook:
 
 ```ts
 // adonisrc.ts
 export default defineConfig({
-  providers: [() => import('@rlanz/socket/provider')],
+  providers: [
+    {
+      file: () => import('@rlanz/socket/provider'),
+      environment: ['web'],
+    },
+  ],
   hooks: {
     init: [() => import('@rlanz/socket/assembler_hook')],
   },
@@ -21,10 +33,11 @@ export default defineConfig({
 ```
 
 The Assembler hook generates both the application registry used for end-to-end client types and the
-server manifest consumed by the provider. They come from the same channel file list, so runtime
-routing cannot drift from the generated client contract. Keep the standard AdonisJS package import
-mapping `#generated/*` pointed at `./.adonisjs/server/*.js`; the provider loads
-`#generated/socket_channels` through that convention.
+server manifest consumed by the provider from the same channel file list. The client registry is a
+typed subset: channels whose inheritance, pattern, or handlers cannot be represented statically are
+still registered at runtime but are omitted from generated client types with a diagnostic. Keep the
+standard AdonisJS package import mapping `#generated/*` pointed at `./.adonisjs/server/*.js`; the
+provider loads `#generated/socket_channels` through that convention.
 
 ## Configuration
 
@@ -37,7 +50,9 @@ import { defineConfig } from '@rlanz/socket'
 export default defineConfig({
   websocket: {
     path: '/socket',
-    allowedOrigins: ['https://app.example.com'],
+    origin: (origin, ctx) => {
+      return ['https://app.example.com', 'https://admin.example.com'].includes(origin)
+    },
     pingInterval: '25s',
     pingTimeout: '5s',
     maxBufferedAmount: 16 * 1024 * 1024,
@@ -49,9 +64,12 @@ export default defineConfig({
 ```
 
 - `websocket.path` defaults to `/socket`.
-- Browser upgrades are restricted to the request's own origin by default. Use
-  `websocket.allowedOrigins` to add exact `http://` or `https://` origins. Clients that do not send
-  an `Origin` header remain supported.
+- Browser upgrades are restricted to the request's own origin by default. `websocket.origin`
+  accepts the same values as AdonisJS CORS `origin`: a boolean, a string (including `'*'` or a
+  comma-separated list), an array of strings, or `(origin, httpContext) => value`. Matching is
+  case-sensitive and, like `@adonisjs/cors`, comma-separated entries are not whitespace-trimmed. A
+  configured policy replaces the same-origin default. Clients without an `Origin` header remain
+  supported.
 - `websocket.middleware` runs AdonisJS HTTP middleware for the WebSocket upgrade request.
 - `websocket.pingInterval` sends a WebSocket ping every configured duration.
 - `websocket.pingTimeout` closes connections that do not answer in time.
@@ -79,7 +97,7 @@ Fetch CORS response checks to WebSockets. The origin check therefore runs before
 and authentication, which protects cookie- or session-authenticated sockets from cross-site
 WebSocket hijacking. A reverse proxy must preserve the public `Host` and overwrite
 `X-Forwarded-Proto` with the trusted public protocol. If it rewrites either value, add the public
-origin explicitly to `websocket.allowedOrigins` instead of relying on implicit same-origin
+origin explicitly with `websocket.origin` instead of relying on implicit same-origin
 detection.
 
 ### Authentication
@@ -101,7 +119,7 @@ import { authenticateWithAdonisAuth, defineConfig } from '@rlanz/socket'
 
 type User = { id: string | number; name: string }
 
-export default defineConfig<User>({
+export default defineConfig({
   websocket: {
     middleware: [
       () => import('@adonisjs/session/session_middleware'),
@@ -114,8 +132,10 @@ export default defineConfig<User>({
 ```
 
 Return `false`, `null`, or throw to reject the upgrade with `401 Unauthorized`. The returned user is
-available as `socket.user`. Every connected socket retains the initial Adonis HTTP context at
-`socket.raw.httpContext`; use `socket.raw.data` for mutable socket-lifetime state.
+available as `socket.user`.
+
+Every connected socket retains the initial Adonis HTTP context at `socket.raw.httpContext`; use
+`socket.raw.data` for mutable socket-lifetime state.
 
 The retained HTTP context describes the initial upgrade handshake. After the `101` response, it is
 not an active HTTP request: do not write through `httpContext.response` or expect it to remain
@@ -136,6 +156,12 @@ async authenticate({ httpContext }) {
 
 Configure an [`@boringnode/bus`](https://github.com/boringnode/bus) transport to synchronize broadcasts across multiple application instances.
 
+Install the peer dependency required by the selected transport. For Redis:
+
+```sh
+yarn add ioredis
+```
+
 ```ts
 // config/socket.ts
 import { redis } from '@boringnode/bus/transports/redis'
@@ -149,14 +175,22 @@ export default defineConfig({
     }),
     channel: 'socket::broadcast',
     presenceTimeout: '100ms',
+    retryQueue: {
+      maxSize: 1000,
+    },
   },
 })
 ```
 
-When configured, `socket.to(channel).emit(...)`, `socket.to(channel).except(socketId).emit(...)`, `socket.toUser(userId).emit(...)`, and `socket.broadcast(...)` are delivered locally and published to the bus so other instances can deliver them to their own connected sockets.
+When configured, `socket.to(channel).emit(...)`, `socket.to(channel).except(socketId).emit(...)`, and `socket.broadcast(...)` are delivered locally and published to the bus so other instances can deliver them to their own connected sockets.
 
 The default bus channel is `socket::broadcast`. Presence channels also use the bus to build distributed snapshots during subscribe, duplicate subscribe, join, and leave updates. `presenceTimeout` controls how long an instance waits for other instances to answer a presence snapshot request; it defaults to `100ms`.
 
+Failed publications enter an in-memory retry queue. It is enabled by default, deduplicates identical
+messages, and retains at most `1000` entries; when full, the oldest entry is discarded. Configure
+`transport.retryQueue` to change the limit, retry interval, deduplication, or to disable retries.
+Setting `maxSize: null` explicitly opts into an unbounded queue.
+
 ### Health Checks
 
 Register `SocketHealthCheck` inside your AdonisJS readiness checks to report whether the WebSocket service is ready to accept traffic.
@@ -203,22 +237,19 @@ test.group('Notifications', (group) => {
 
 The fake supports explicit resource management as well, so `using fake = socket.fake()` automatically restores the real socket service when the test scope exits.
 
-Assertion helpers cover global broadcasts, channel events, user events, counts, and negative assertions.
+Five assertion helpers cover global broadcasts, channel events, counts, and negative assertions.
 
 ```ts
 fake.assertBroadcasted('maintenance', { data: { active: true } })
-fake.assertNotBroadcasted('maintenance')
+fake.assertNotBroadcasted('deploy:started')
 
 fake.assertEmittedTo('chat/general', 'chat:message', {
   data: (data) => data.text === 'Hello',
 })
 fake.assertNotEmittedTo('chat/general', 'chat:typing')
 
-fake.assertEmittedToUser(1, 'notification', { data: { unread: 3 } })
-fake.assertNotEmittedToUser(1, 'notification')
-
-fake.assertEmittedCount(2, { target: 'channel', channel: 'chat/general' })
-fake.assertNothingEmitted()
+fake.assertCount(2, { target: 'channel', channel: 'chat/general' })
+fake.assertCount(0)
 ```
 
 ### OpenTelemetry
@@ -258,7 +289,7 @@ At the reverse proxy or load balancer:
   `X-Forwarded-Proto` value, so client-supplied versions of those headers must not reach the app.
 
 Browser origins are not authorized by AdonisJS CORS middleware. Configure exact public origins in
-[`websocket.allowedOrigins`](#configuration) when the browser origin differs from the public socket
+[`websocket.origin`](#configuration) when the browser origin differs from the public socket
 origin or when the proxy rewrites `Host`. Clients without an `Origin` header are accepted, so use
 upgrade authentication for non-browser clients rather than treating the origin check as
 authentication.
@@ -267,7 +298,7 @@ authentication.
 
 A load balancer may route each new upgrade to any ready instance and must keep that upgraded TCP
 connection attached to that instance. The package neither implements nor guarantees sticky
-sessions. Without a [transport](#horizontal-sync), subscriptions, user rooms, broadcasts, and
+sessions. Without a [transport](#horizontal-sync), subscriptions, broadcasts, and
 presence are local to one instance; affinity is not a replacement for configuring the transport.
 All instances in one logical deployment must use a compatible shared transport and the same bus
 channel.
@@ -282,10 +313,11 @@ large fleet could reconnect simultaneously.
 ### Transport, presence, and delivery semantics
 
 Local broadcasts are sent to currently connected local recipients and are also published to the
-configured `@boringnode/bus` transport. Publication is fire-and-forget from the socket API. This
-package does not persist bus messages, wait for remote delivery, acknowledge recipients, or replay
-missed events; the guarantees of a particular transport do not turn socket delivery into a durable
-application queue.
+configured `@boringnode/bus` transport. Publication is fire-and-forget from the socket API. Failed
+publications may be retried from the bounded, in-memory retry queue after the transport reconnects,
+so stale events remain possible. The package does not persist bus messages, wait for remote
+delivery, acknowledge recipients, or recover events after a process restart; the guarantees of a
+particular transport do not turn socket delivery into a durable application queue.
 
 Distributed presence is also best-effort and non-durable. A snapshot contains the replies received
 before `transport.presenceTimeout`; partitions, slow instances, concurrent changes, and restarts can
@@ -311,7 +343,7 @@ Review the limits under [Configuration](#configuration) against real payloads an
 
 - enable heartbeat explicitly; it is disabled when neither `pingInterval` nor `pingTimeout` is set;
 - tune inbound/outbound payload sizes, the per-socket fixed-window message rate, serialized message
-  queue depth, subscriptions per socket, and channel-name length;
+  queue depth, subscriptions per socket, channel-name length, and the transport retry queue;
 - treat rate and queue limits as per-connection safeguards, not perimeter abuse prevention; enforce
   aggregate connection and request limits at the proxy or application boundary; and
 - tune `maxBufferedAmount` for available memory. Slow consumers and oversized outbound frames are
@@ -341,7 +373,7 @@ counters count immediate sends to local `ws` objects, not application-level rece
 
 - [ ] Proxy upgrades on the configured path with HTTP/1.1 `Upgrade`/`Connection` headers.
 - [ ] Terminate TLS safely; preserve a validated public `Host` and overwrite `X-Forwarded-Proto`.
-- [ ] Configure exact `allowedOrigins` and upgrade authentication; protect the upstream from direct
+- [ ] Configure an exact `origin` policy and upgrade authentication; protect the upstream from direct
       access.
 - [ ] Set proxy idle timeouts and explicitly configure/test heartbeat behavior.
 - [ ] Configure a shared transport and bus channel for every instance that must exchange broadcasts
@@ -359,11 +391,13 @@ counters count immediate sends to local `ws` objects, not application-level rece
 
 Channels are discovered from `app/channels/**/*_channel.{ts,js}`. Export a default class extending
 `BaseChannel`. Client-to-server payloads and acknowledgements are inferred from public handler
-methods. The optional second generic declares server-to-client events and defaults to `unknown`.
+methods. The optional second generic declares server-to-client events. When omitted, the channel
+cannot broadcast server events.
 
 ```ts
 // app/channels/chat_channel.ts
 import { BaseChannel } from '@rlanz/socket'
+import { onMessage } from '@rlanz/socket/decorators'
 import type { AuthenticatedSocket } from '@rlanz/socket/types'
 
 type User = { id: string; name: string }
@@ -376,11 +410,7 @@ type ServerEvents = {
 export default class ChatChannel extends BaseChannel<User, ServerEvents> {
   static pattern = 'chat/:roomId'
 
-  protected handlers = {
-    'chat:send': this.sendMessage,
-    'chat:ping': this.ping,
-  }
-
+  @onMessage('chat:send')
   async sendMessage(
     socket: AuthenticatedSocket<User>,
     payload: { text: string }
@@ -390,22 +420,35 @@ export default class ChatChannel extends BaseChannel<User, ServerEvents> {
     return message
   }
 
+  @onMessage('chat:ping')
   ping(_socket: AuthenticatedSocket<User>, _payload: undefined): void {}
 }
 ```
 
-The event name comes from `handlers` or `@onMessage('event')`, the handler's second parameter becomes
-the client payload, and `Awaited<ReturnType<handler>>` becomes its acknowledgement. No duplicate
-client event map is required. `ServerEvents` remains explicit because generation does not scan
-`broadcast()` calls; it checks `broadcast()` and `broadcastExcept()`. Omitting it preserves the broad
-legacy broadcast API:
+Channel instances are resolved through the AdonisJS container for every new subscription, so
+constructor injection works as it does for other AdonisJS classes:
 
 ```ts
-export default class ChatChannel extends BaseChannel<User> {
-  // Server events remain unknown and may be typed by callers when listening.
+import { inject } from '@adonisjs/core'
+import { BaseChannel } from '@rlanz/socket'
+import MessageService from '#services/message_service'
+
+@inject()
+export default class ChatChannel extends BaseChannel {
+  static pattern = 'chat/:roomId'
+
+  constructor(private messages: MessageService) {
+    super()
+  }
 }
 ```
 
+The event name comes from `@onMessage('event')`, the handler's second parameter becomes the client
+payload, and `Awaited<ReturnType<handler>>` becomes its acknowledgement. No duplicate client event
+map is required. `ServerEvents` remains explicit because generation does not scan
+`broadcast()` calls; it checks `broadcast()` and `broadcastExcept()`. Omitting it makes both methods
+reject every event at compile time.
+
 The Assembler hook generates an explicit `AppSocket` registry. Pass it once to the browser client:
 
 ```ts
@@ -413,7 +456,7 @@ import { Socket } from '@rlanz/socket/client'
 import type { AppSocket } from '#generated/socket'
 
 const socket = new Socket<AppSocket>()
-const channel = socket.channel('chat/general')
+const channel = socket.channel('chat/:roomId', { roomId: 'general' })
 
 channel.listen('chat:message', (message) => console.log(message.id))
 channel.send('chat:ping')
@@ -422,39 +465,66 @@ const message = await channel.sendWithAck('chat:send', { text: 'Hello' })
 console.log(message.id)
 ```
 
+The generated registry is a map keyed by each declared channel pattern. The client selects that
+pattern explicitly and constructs the concrete name from typed parameters, so its types never need
+to reproduce runtime route ordering or specificity. Every registry entry carries its generated
+parameter shape; static channels use `undefined`, while dynamic channels expose their required,
+optional, or wildcard parameters.
+
+Client code can also extract event payloads without constructing a channel first:
+
+```ts
+import type { ChannelBroadcastPayload, ChannelClientEventPayload } from '@rlanz/socket/client'
+import type { AppSocket } from '#generated/socket'
+
+type IncomingMessage = ChannelBroadcastPayload<AppSocket, 'chat/:roomId', 'chat:message'>
+type OutgoingMessage = ChannelClientEventPayload<AppSocket, 'chat/:roomId', 'chat:send'>
+```
+
 The scanner recognizes default-exported classes that directly extend `BaseChannel`, direct
-string-literal `static pattern` values, and handlers declared as `'event': this.publicMethod`. It also
-recognizes `@onMessage('event')` imported from `@rlanz/socket/decorators`. Handler methods must be
+string-literal `static pattern` values, and `@onMessage('event')` imported from
+`@rlanz/socket/decorators`. Handler methods must be
 named, public instance methods so the generated registry can reference their parameter and return
-types. Abstract channels, inline/computed handlers, private/protected/static methods, rest parameters,
-and required parameters after the payload fail generation with a diagnostic. A handler may accept no
+types. Abstract channels, private/protected/static handlers, rest parameters, and required parameters
+after the payload fail generation with a diagnostic. A handler may accept no
 parameters, only the socket, a required payload, or an optional payload. Intermediate channel
-inheritance is deliberately omitted from generated contracts and makes the client registry
-uncertain; runtime channel inheritance remains valid.
+inheritance is deliberately omitted from generated contracts; runtime channel inheritance remains
+valid.
+
+Generated patterns support literal segments, required parameters, one final optional parameter, and
+one final wildcard. Dynamic patterns always receive a parameter object; pass `{}` to omit a final
+optional parameter. Wildcards use the explicit `wildcard` parameter and may contain slashes. Static
+channels need no parameter object. An untyped `new Socket()` continues to accept raw concrete channel
+names.
 
 The default Assembler hook discovers `app/channels/**/*_channel.{ts,js}` and generates both
 `.adonisjs/client/socket.ts` and `.adonisjs/server/socket_channels.ts`. Configure the frontend
 project to resolve an alias such as `#generated/socket` to the client file; this frontend mapping is
-separate from the AdonisJS server `#generated/*` mapping. Generated channel imports are relative by
-default, so an `importAlias` is optional. To customize discovery, replace the package hook in
-`adonisrc.ts` with a local hook:
+separate from the AdonisJS server `#generated/*` mapping. Channels are discovered in `app/channels`
+by default. Any source inside `app` is supported, and generated imports use the corresponding
+AdonisJS `#app` alias without TypeScript extensions. To customize discovery or client output, replace
+the package hook in `adonisrc.ts` with a local hook:
 
 ```ts
 // hooks/socket.ts
 import { generateSocketRegistry } from '@rlanz/socket/assembler_hook'
 
 export default generateSocketRegistry({
-  source: 'realtime',
+  source: './app/realtime',
   glob: ['**/*.ts'],
   output: '.adonisjs/client/socket.d.ts',
-  importAlias: '#realtime',
 })
 ```
 
 ```ts
 // adonisrc.ts
 export default defineConfig({
-  providers: [() => import('@rlanz/socket/provider')],
+  providers: [
+    {
+      file: () => import('@rlanz/socket/provider'),
+      environment: ['web'],
+    },
+  ],
   hooks: {
     init: [() => import('./hooks/socket.js')],
   },
@@ -462,56 +532,24 @@ export default defineConfig({
 ```
 
 Generated matching supports literals, required parameters, a final optional parameter, and a final
-wildcard. Dynamic or unsupported patterns are omitted and mark the registry uncertain, causing
-`Socket<AppSocket>` to fall back conservatively to untyped channels. Plain dynamic channel names and
-ambiguous matches also remain untyped; unmatched concrete literals are rejected when the registry is
-certain. Generation provides compile-time types only and does not validate runtime payloads.
-Whispers intentionally remain caller-generic because they are peer-to-peer. Runtime channel files
-always come from the generated server manifest; the former `channels.patterns` runtime setting is no
-longer supported and is rejected to prevent a second discovery source.
-
-Legacy untyped channels remain supported without the generated generic:
-
-```ts
-// app/channels/chat_channel.ts
-import { BaseChannel } from '@rlanz/socket'
-import type { AuthenticatedSocket } from '@rlanz/socket/types'
-
-type User = { id: string; name: string }
-
-export default class ChatChannel extends BaseChannel<User> {
-  static pattern = 'chat/:roomId'
-
-  async onJoin(socket: AuthenticatedSocket<User>, roomId: string) {
-    this.broadcast('chat:system', {
-      message: `${socket.user?.name ?? 'Someone'} joined ${roomId}`,
-    })
-  }
-
-  async onLeave(socket: AuthenticatedSocket<User>, roomId: string) {
-    this.broadcastExcept(socket.id, 'chat:system', {
-      message: `${socket.user?.name ?? 'Someone'} left ${roomId}`,
-    })
-  }
-}
-```
+wildcard. Dynamic or unsupported patterns are omitted. Plain dynamic channel names, ambiguous
+matches, and unmatched literals are rejected at compile time; the browser client must receive the
+generated registry as `Socket<AppSocket>`. Generation provides compile-time types only and does not
+validate runtime payloads. Whispers intentionally remain caller-generic because they are
+peer-to-peer. Runtime channel files always come from the generated server manifest.
 
 ### Middleware
 
 Middlewares run before subscription. They may be functions or objects with a `handle` method.
 
 ```ts
-import { BaseChannel, SocketResponseError } from '@rlanz/socket'
+import { BaseChannel } from '@rlanz/socket'
 import type { MiddlewareContext } from '@rlanz/socket/types'
 
 type User = { id: string; name: string }
 
 async function auth(ctx: MiddlewareContext<User>, next: () => Promise<void>) {
-  if (!ctx.socket.user) {
-    throw new SocketResponseError('Unauthorized')
-  }
-
-  await ctx.socket.joinUserRoom(ctx.socket.user.id)
+  ctx.socket.getUserOrFail()
   await next()
 }
 
@@ -535,16 +573,22 @@ import { BaseChannel } from '@rlanz/socket'
 import type { AuthenticatedSocket, PresenceInfo, PresenceMember } from '@rlanz/socket/types'
 
 type User = { id: string; name: string }
+type ServerEvents = {
+  'room:member_joined': PresenceMember
+  'room:member_left': PresenceMember
+}
 
-export default class RoomChannel extends BaseChannel<User> {
+export default class RoomChannel extends BaseChannel<User, ServerEvents> {
   static pattern = 'rooms/:roomId'
   static options = { presence: true }
 
   getPresenceInfo(socket: AuthenticatedSocket<User>): PresenceInfo {
+    const user = socket.getUserOrFail()
+
     return {
-      id: socket.user!.id,
+      id: user.id,
       data: {
-        name: socket.user!.name,
+        name: user.name,
       },
     }
   }
@@ -583,21 +627,23 @@ an exception from a later hook can be retried safely.
 
 ## Channel Messages
 
-Incoming client messages are handled through the `handlers` map, the `@onMessage` decorator, or the `onMessage` fallback.
+Incoming client messages are handled through the `@onMessage` decorator.
+Unknown events receive a negative acknowledgement.
 
 ```ts
 import { BaseChannel } from '@rlanz/socket'
+import { onMessage } from '@rlanz/socket/decorators'
 import type { AuthenticatedSocket } from '@rlanz/socket/types'
 
 type User = { id: string; name: string }
+type ServerEvents = {
+  'chat:message': { user: User | undefined; body: string }
+}
 
-export default class ChatChannel extends BaseChannel<User> {
+export default class ChatChannel extends BaseChannel<User, ServerEvents> {
   static pattern = 'chat/:roomId'
 
-  protected handlers = {
-    'chat:send': this.sendMessage,
-  }
-
+  @onMessage('chat:send')
   async sendMessage(socket: AuthenticatedSocket<User>, data: { body: string }) {
     this.broadcast('chat:message', {
       user: socket.user,
@@ -606,10 +652,6 @@ export default class ChatChannel extends BaseChannel<User> {
 
     return { delivered: true }
   }
-
-  async onMessage(socket: AuthenticatedSocket<User>, event: string, data: unknown) {
-    console.log('Unhandled channel message', event, data)
-  }
 }
 ```
 
@@ -643,8 +685,9 @@ Import the browser client from `@rlanz/socket/client`.
 
 ```ts
 import { Socket } from '@rlanz/socket/client'
+import type { AppSocket } from '#generated/socket'
 
-const socket = new Socket({
+const socket = new Socket<AppSocket>({
   url: 'http://localhost:3333',
   path: '/socket',
   autoReconnect: true,
@@ -666,7 +709,7 @@ await socket.connect()
 ### Subscribe, Listen, Send
 
 ```ts
-const channel = socket.channel('chat/general')
+const channel = socket.channel('chat/:roomId', { roomId: 'general' })
 
 channel
   .here((users) => console.log('present users', users))
@@ -692,7 +735,7 @@ console.log(ack)
 channel.stopListening('chat:message')
 channel.stopListeningForWhisper('typing')
 await channel.unsubscribe()
-await socket.leave('chat/general')
+await socket.leave(channel.name)
 socket.disconnect()
 ```
 
@@ -702,7 +745,7 @@ The client reconnects automatically by default. `reconnectDelay` is the initial
 milliseconds, and each failed retry doubles the delay until `reconnectMaxDelay` is reached.
 Set `autoReconnect: false` to disable reconnect attempts.
 
-### React, Vue, and Svelte
+### React and Vue
 
 Framework adapters keep the generated `AppSocket` type at one application-level factory. Channel
 names, client methods, server events, and payloads then remain inferred without repeating the
@@ -726,8 +769,13 @@ export const { SocketProvider, useChannel, useChannelEvent, useSocketState } =
 </SocketProvider>
 
 function Chat() {
-  const channel = useChannel('chat/general')
-  useChannelEvent('chat/general', 'chat:message', (message) => console.log(message.id))
+  const channel = useChannel('chat/:roomId', { roomId: 'general' })
+  useChannelEvent(
+    'chat/:roomId',
+    { roomId: 'general' },
+    'chat:message',
+    (message) => console.log(message.id)
+  )
 
   return <button onClick={() => channel?.send('chat:send', { text: 'Hello' })}>Send</button>
 }
@@ -749,63 +797,31 @@ export const { provideSocket, useChannel, useChannelEvent, useSocketState } =
 provideSocket(socket, { owned: true })
 
 // In a descendant component setup
-const channel = useChannel('chat/general')
-useChannelEvent('chat/general', 'chat:message', (message) => console.log(message.id))
+const channel = useChannel('chat/:roomId', { roomId: 'general' })
+useChannelEvent('chat/:roomId', { roomId: 'general' }, 'chat:message', (message) =>
+  console.log(message.id)
+)
 
 function send() {
   channel.value?.send('chat:send', { text: 'Hello' })
 }
 ```
 
-Svelte:
-
-```ts
-// src/socket.ts
-import { Socket } from '@rlanz/socket/client'
-import { createSocketContext } from '@rlanz/socket/client/svelte'
-import type { AppSocket } from '#generated/socket'
-
-export const socket = new Socket<AppSocket>()
-export const { setSocket, useSocketState, channel, onChannelEvent } =
-  createSocketContext<AppSocket>()
-```
-
-```svelte
-<!-- In the root component -->
-<script lang="ts">
-  import { setSocket, socket } from './socket'
-
-  setSocket(socket, { owned: true })
-</script>
-```
-
-```svelte
-<!-- In a descendant component -->
-<script lang="ts">
-  import { channel, onChannelEvent } from './socket'
-
-  const chat = channel('chat/general')
-  onChannelEvent('chat/general', 'chat:message', (message) => console.log(message.id))
-</script>
-
-<button on:click={() => $chat?.send('chat:send', { text: 'Hello' })}>Send</button>
-```
-
 Adapters acquire and share channel subscriptions, attach listeners before subscribing, and release
-them when the component, scope, or store consumer is disposed. React returns `null` until its passive
-effect acquires the channel; Vue exposes a nullable shallow ref and Svelte exposes a nullable readable
-store. Multiple consumers of the same channel share one subscription, including across development
+them when the component or scope is disposed. React returns `null` until its passive effect acquires
+the channel; Vue exposes a nullable shallow ref. Multiple consumers of the same channel share one
+subscription, including across development
 remounts, without removing listeners registered through the direct client API.
 
 Sockets are borrowed by default: the adapter neither connects nor disconnects them. Pass `owned` to
-`SocketProvider`, `{ owned: true }` to `provideSocket`, or `{ owned: true }` to `setSocket` only when
-that framework root exclusively owns the socket lifecycle. Otherwise call `socket.connect()` and
-`socket.disconnect()` in application-owned lifecycle code.
+`SocketProvider` or `{ owned: true }` to `provideSocket` only when that framework root exclusively
+owns the socket lifecycle. Otherwise call `socket.connect()` and `socket.disconnect()` in
+application-owned lifecycle code.
 
 ## Package Exports
 
 ```ts
-import { BaseChannel, ChannelRouter, PresenceManager } from '@rlanz/socket'
+import { BaseChannel, SocketResponseError, defineConfig } from '@rlanz/socket'
 import type { AuthenticatedSocket, SocketConfig } from '@rlanz/socket/types'
 import SocketProvider from '@rlanz/socket/provider'
 import socket from '@rlanz/socket/services/main'
@@ -813,11 +829,10 @@ import { onMessage } from '@rlanz/socket/decorators'
 import { SocketHealthCheck } from '@rlanz/socket/health_check'
 import { SocketInstrumentation } from '@rlanz/socket/otel'
 import { SocketFake } from '@rlanz/socket/testing'
-import { Socket, Channel } from '@rlanz/socket/client'
+import { Socket } from '@rlanz/socket/client'
 import { generateSocketRegistry } from '@rlanz/socket/assembler_hook'
 import { createSocketHooks } from '@rlanz/socket/client/react'
 import { createSocketComposables } from '@rlanz/socket/client/vue'
-import { createSocketContext } from '@rlanz/socket/client/svelte'
 import type { SocketOptions, PresenceData } from '@rlanz/socket/client/types'
 ```
 
@@ -837,4 +852,3 @@ Available exports:
 - `@rlanz/socket/client/types`
 - `@rlanz/socket/client/react`
 - `@rlanz/socket/client/vue`
-- `@rlanz/socket/client/svelte`