@rlanz/socket 0.0.1-3 → 0.0.1-5

package/README.md

@@ -14,35 +14,78 @@ Register the provider in your AdonisJS application:
 // adonisrc.ts
 export default defineConfig({
   providers: [() => import('@rlanz/socket/provider')],
+  hooks: {
+    init: [() => import('@rlanz/socket/assembler_hook')],
+  },
 })
 ```
 
+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.
+
 ## Configuration
 
 Create a socket config file and tune the WebSocket path or heartbeat.
 
 ```ts
 // config/socket.ts
-import { defineConfig } from '@adonisjs/core/config'
+import { defineConfig } from '@rlanz/socket'
 
 export default defineConfig({
   websocket: {
     path: '/socket',
-    pingInterval: 25_000,
-    pingTimeout: 5_000,
+    allowedOrigins: ['https://app.example.com'],
+    pingInterval: '25s',
+    pingTimeout: '5s',
+    maxBufferedAmount: 16 * 1024 * 1024,
+    maxOutboundPayload: 1024 * 1024,
+    maxSubscriptionsPerSocket: 100,
+    maxChannelNameLength: 255,
   },
 })
 ```
 
 - `websocket.path` defaults to `/socket`.
-- `websocket.pingInterval` sends a WebSocket ping every configured number of milliseconds.
+- 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.
+- `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.
 - If only one heartbeat value is configured, the other one uses the default shown above.
+- `websocket.maxPayload` limits inbound message payloads; it defaults to 1 MiB.
+- `websocket.maxQueuedMessages` limits unresolved non-ping protocol messages per socket; it defaults
+  to `100`.
+- `websocket.maxMessagesPerInterval` limits inbound protocol messages per
+  `websocket.messageRateInterval`; they default to `1000` messages per `1s`.
+- `websocket.maxBufferedAmount` closes slow outbound sockets when the buffered bytes plus the next
+  protocol message would exceed the configured limit; it defaults to 16 MiB.
+- `websocket.maxOutboundPayload` limits every serialized outbound event, ACK, pong, and protocol
+  error; it defaults to 1 MiB.
+- `websocket.maxSubscriptionsPerSocket` limits active channel subscriptions retained by one socket;
+  it defaults to `100`.
+- `websocket.maxChannelNameLength` limits channel names before routing; it defaults to `255`
+  characters.
+
+`websocket.middleware` is different from channel middleware. Use it to prepare request-scoped
+services such as sessions or auth during the initial HTTP upgrade; use `static middlewares` on a
+channel class to authorize or enrich individual channel subscriptions.
+
+AdonisJS CORS middleware does not authorize the Node.js `upgrade` event and browsers do not apply
+Fetch CORS response checks to WebSockets. The origin check therefore runs before upgrade middleware
+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
+detection.
 
 ### Authentication
 
-Authenticate sockets during the HTTP upgrade with `websocket.authenticate`. The hook receives the
-upgrade request, the parsed client auth payload, and an AdonisJS HTTP context.
+Authenticate sockets during the HTTP upgrade with `websocket.authenticate`. The hook receives an
+AdonisJS HTTP context and returns the authenticated user.
 
 Define `websocket.middleware` when your WebSocket upgrade authentication depends on AdonisJS
 middleware such as sessions or auth initialization. These middleware run only for the HTTP upgrade
@@ -54,43 +97,49 @@ channel itself through `static middlewares`.
 
 ```ts
 // config/socket.ts
-import { defineConfig } from '@adonisjs/core/config'
+import { authenticateWithAdonisAuth, defineConfig } from '@rlanz/socket'
 
-export default defineConfig({
+type User = { id: string | number; name: string }
+
+export default defineConfig<User>({
   websocket: {
     middleware: [
       () => import('@adonisjs/session/session_middleware'),
       () => import('@adonisjs/auth/initialize_auth_middleware'),
     ],
 
-    async authenticate({ auth, httpContext }) {
-      await httpContext!.auth.authenticateUsing()
-      const user = httpContext!.auth.getUserOrFail()
-
-      return {
-        user,
-        auth,
-        data: {
-          connectedAt: new Date(),
-        },
-      }
-    },
+    authenticate: authenticateWithAdonisAuth<User>(),
   },
 })
 ```
 
-Return `false`, `null`, or throw to reject the upgrade with `401 Unauthorized`. The returned `user`
-is available as `socket.user`, `data` is stored on `socket.raw.data`, and the HTTP context remains
-available as `socket.raw.httpContext`.
+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.
+
+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
+available through AdonisJS async-local storage. The upgrade pipeline receives the context explicitly
+and does not install it in async-local storage during the handshake either. Copy durable values into
+`socket.user` or `socket.raw.data` instead of keeping response-bound resources alive.
+
+Override `websocket.authenticate` when you need custom behavior:
+
+```ts
+async authenticate({ httpContext }) {
+  await httpContext.auth.authenticateUsing()
+  return httpContext.auth.getUserOrFail()
+}
+```
 
 ### Horizontal Sync
 
-Configure an [`@boringnode/bus`](https://github.com/boringnode/bus) transport to synchronize broadcasts across multiple SocketService instances.
+Configure an [`@boringnode/bus`](https://github.com/boringnode/bus) transport to synchronize broadcasts across multiple application instances.
 
 ```ts
 // config/socket.ts
-import { defineConfig } from '@adonisjs/core/config'
 import { redis } from '@boringnode/bus/transports/redis'
+import { defineConfig } from '@rlanz/socket'
 
 export default defineConfig({
   transport: {
@@ -99,14 +148,14 @@ export default defineConfig({
       port: 6379,
     }),
     channel: 'socket::broadcast',
-    presenceTimeout: 100,
+    presenceTimeout: '100ms',
   },
 })
 ```
 
 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.
 
-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 `100` milliseconds.
+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`.
 
 ### Health Checks
 
@@ -187,9 +236,241 @@ instrumentation.manuallyRegister()
 
 The instrumentation creates spans for socket connect/disconnect, subscribe/unsubscribe, incoming channel messages, and broadcast delivery. It also records counters for active connections, active subscriptions, received channel messages, broadcast operations, and broadcast deliveries.
 
+## Production and scaling
+
+### Process and reverse proxy
+
+The provider attaches its WebSocket `upgrade` handler to the AdonisJS Node HTTP server after that
+server is ready. WebSockets therefore use the same process, listener, event loop, memory, and failure
+domain as HTTP; there is no separate socket process or port. Size each application instance for its
+combined HTTP and long-lived WebSocket workload, and remember that a process failure drops every
+socket connected to that instance.
+
+At the reverse proxy or load balancer:
+
+- route `websocket.path` to the AdonisJS HTTP listener and forward WebSocket upgrade requests using
+  HTTP/1.1 with the `Upgrade` and `Connection: upgrade` headers;
+- terminate TLS there if desired, use `wss://` publicly, preserve a validated public `Host`, and
+  **overwrite** `X-Forwarded-Proto` with the trusted public protocol (`http` or `https`);
+- allow long-lived upgraded connections and set the proxy idle timeout above the configured
+  heartbeat cadence; and
+- restrict direct access to the upstream. Same-origin validation trusts `Host` and the first
+  `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
+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.
+
+### Multiple instances and reconnects
+
+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
+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.
+
+The bundled client reconnects by default with exponential backoff from `250ms` to `5s` and
+re-subscribes desired channels after establishing a new connection, which may be on another
+instance. A reconnect is a new session: pending acknowledgements are rejected, authentication and
+channel middleware run again, and events sent while disconnected are not replayed. The built-in
+backoff has no jitter; stagger deployments or add reconnect staggering in the application when a
+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.
+
+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
+produce incomplete snapshots or duplicate/omitted member transitions. Presence hooks must be
+idempotent and presence must not be used as an authoritative online-user or membership store.
+
+`sendWithAck()` only confirms that the receiving server-side handler completed and returned a
+result. It does not confirm that a broadcast reached any client. Applications that need durable
+notifications, recovery after reconnect, or at-least-once processing must persist events or state
+outside this package and define their own event IDs, cursors, deduplication, acknowledgement, and
+replay protocol.
+
+### Restarts and resource limits
+
+On AdonisJS shutdown, the service becomes unready, stops accepting upgrades, terminates existing
+WebSockets, runs their subscription/disconnect finalizers, and then disconnects the bus. It does
+**not** gracefully drain established sockets or wait for in-flight client acknowledgements. For a
+rolling restart, remove the instance from new HTTP/upgrade traffic first when the platform permits,
+expect connected clients to reconnect, and give the process enough termination grace to finish its
+socket finalizers and bus shutdown before sending a forced kill.
+
+Review the limits under [Configuration](#configuration) against real payloads and fan-out:
+
+- 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;
+- 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
+  disconnected rather than buffered without bound or retried.
+
+There is no built-in total connection limit. Each connection consumes a file descriptor plus
+application, subscription, queue, heartbeat, and `ws` memory. Set process/container memory limits,
+raise and monitor file-descriptor limits where appropriate, cap connections at the edge, and load
+test representative connection counts, message rates, payloads, and broadcast fan-out before
+production.
+
+### Health and monitoring
+
+Expose the application-owned readiness endpoint containing [`SocketHealthCheck`](#health-checks)
+and route new upgrades only to ready instances. The check reports local service startup/shutdown
+state and local connection/channel counts; it does not probe the transport backend, remote
+instances, or end-to-end publish delivery. Monitor those dependencies separately and keep a normal
+process liveness check so readiness failures do not automatically cause restart loops.
+
+Enable the optional [OpenTelemetry instrumentation](#opentelemetry) and alert on connection and
+disconnection changes, active connections/subscriptions, message errors, and broadcast volume and
+local delivery counts. Also collect process event-loop delay, memory, CPU, open file descriptors,
+proxy upgrade/rejection metrics, reconnect rates, logs, and transport health. Broadcast delivery
+counters count immediate sends to local `ws` objects, not application-level receipt.
+
+### Production checklist
+
+- [ ] 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
+      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
+      or presence.
+- [ ] Make clients tolerate reconnect, re-authentication, re-subscription, duplicate handling, and
+      gaps during deploys or failures.
+- [ ] Persist and replay application-critical events outside the socket bus.
+- [ ] Tune payload, rate, queue, subscription, backpressure, connection, memory, and file-descriptor
+      limits using load tests.
+- [ ] Wire readiness, liveness, OpenTelemetry, logs, proxy metrics, and transport monitoring.
+- [ ] Give rolling shutdown enough grace for finalizers and bus disconnect; do not expect socket
+      draining.
+
 ## Channels
 
-Channels are discovered from `app/channels/**/*_channel.{ts,js}`. Export a default class extending `BaseChannel` and define a static `pattern`.
+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`.
+
+```ts
+// app/channels/chat_channel.ts
+import { BaseChannel } from '@rlanz/socket'
+import type { AuthenticatedSocket } from '@rlanz/socket/types'
+
+type User = { id: string; name: string }
+type Message = { id: string; text: string }
+
+type ServerEvents = {
+  'chat:message': Message
+}
+
+export default class ChatChannel extends BaseChannel<User, ServerEvents> {
+  static pattern = 'chat/:roomId'
+
+  protected handlers = {
+    'chat:send': this.sendMessage,
+    'chat:ping': this.ping,
+  }
+
+  async sendMessage(
+    socket: AuthenticatedSocket<User>,
+    payload: { text: string }
+  ): Promise<Message> {
+    const message = { id: crypto.randomUUID(), text: payload.text }
+    this.broadcastExcept(socket.id, 'chat:message', message)
+    return message
+  }
+
+  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:
+
+```ts
+export default class ChatChannel extends BaseChannel<User> {
+  // Server events remain unknown and may be typed by callers when listening.
+}
+```
+
+The Assembler hook generates an explicit `AppSocket` registry. Pass it once to the browser client:
+
+```ts
+import { Socket } from '@rlanz/socket/client'
+import type { AppSocket } from '#generated/socket'
+
+const socket = new Socket<AppSocket>()
+const channel = socket.channel('chat/general')
+
+channel.listen('chat:message', (message) => console.log(message.id))
+channel.send('chat:ping')
+
+const message = await channel.sendWithAck('chat:send', { text: 'Hello' })
+console.log(message.id)
+```
+
+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
+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
+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.
+
+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:
+
+```ts
+// hooks/socket.ts
+import { generateSocketRegistry } from '@rlanz/socket/assembler_hook'
+
+export default generateSocketRegistry({
+  source: 'realtime',
+  glob: ['**/*.ts'],
+  output: '.adonisjs/client/socket.d.ts',
+  importAlias: '#realtime',
+})
+```
+
+```ts
+// adonisrc.ts
+export default defineConfig({
+  providers: [() => import('@rlanz/socket/provider')],
+  hooks: {
+    init: [() => import('./hooks/socket.js')],
+  },
+})
+```
+
+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
@@ -220,14 +501,14 @@ export default class ChatChannel extends BaseChannel<User> {
 Middlewares run before subscription. They may be functions or objects with a `handle` method.
 
 ```ts
-import { BaseChannel } from '@rlanz/socket'
+import { BaseChannel, SocketResponseError } 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 Error('Unauthorized')
+    throw new SocketResponseError('Unauthorized')
   }
 
   await ctx.socket.joinUserRoom(ctx.socket.user.id)
@@ -240,13 +521,18 @@ export default class ChatChannel extends BaseChannel<User> {
 }
 ```
 
+Only `SocketResponseError` messages are intentionally exposed to clients. Unexpected middleware,
+join, and message-handler errors are logged server-side and replaced with a generic protocol error,
+so internal exception details do not leak. Use `SocketResponseError` only for safe, user-facing
+messages.
+
 ### Presence
 
 Enable presence with `static options = { presence: true }` and implement `getPresenceInfo`.
 
 ```ts
 import { BaseChannel } from '@rlanz/socket'
-import type { AuthenticatedSocket, PresenceMember } from '@rlanz/socket/types'
+import type { AuthenticatedSocket, PresenceInfo, PresenceMember } from '@rlanz/socket/types'
 
 type User = { id: string; name: string }
 
@@ -254,10 +540,12 @@ export default class RoomChannel extends BaseChannel<User> {
   static pattern = 'rooms/:roomId'
   static options = { presence: true }
 
-  getPresenceInfo(socket: AuthenticatedSocket<User>): PresenceMember {
+  getPresenceInfo(socket: AuthenticatedSocket<User>): PresenceInfo {
     return {
       id: socket.user!.id,
-      name: socket.user!.name,
+      data: {
+        name: socket.user!.name,
+      },
     }
   }
 
@@ -271,6 +559,28 @@ export default class RoomChannel extends BaseChannel<User> {
 }
 ```
 
+The `id` identifies one member across multiple sockets or browser tabs. The optional `data` object
+defines the channel-specific public fields exposed on that member. Snapshots and member hooks flatten
+these values into `{ id, ...data, joinedAt }`.
+
+Custom presence fields are not normalized or recursively validated. WebSocket and distributed
+transport serialization may transform them, so use JSON-compatible values when local and distributed
+snapshots must have the same shape.
+
+Presence is exposed per user ID: multiple sockets or browser tabs for the same ID remain separate
+broadcast destinations but produce one `users` entry and contribute one to `count`. `onMemberJoin`
+runs for the first locally observed connection and `onMemberLeave` for the last; `onJoin` and
+`onLeave` still run for every socket. Across multiple application instances, member hooks are
+best-effort and must be idempotent because concurrent joins, leaves, timeouts, or partitions can
+duplicate or omit a transition. When two connections provide different metadata, the earliest
+connection is the representative. Distributed snapshots are deduplicated across the responses
+received before `transport.presenceTimeout` and therefore remain a best-effort, non-durable view
+during network partitions.
+
+Presence snapshots are validated for JSON serialization before join hooks run. Hooks can still
+perform arbitrary external side effects and are not database transactions; keep them idempotent so
+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.
@@ -280,18 +590,15 @@ import { BaseChannel } from '@rlanz/socket'
 import type { AuthenticatedSocket } from '@rlanz/socket/types'
 
 type User = { id: string; name: string }
-type Events = {
-  'chat:send': { body: string }
-}
 
-export default class ChatChannel extends BaseChannel<User, Events> {
+export default class ChatChannel extends BaseChannel<User> {
   static pattern = 'chat/:roomId'
 
   protected handlers = {
     'chat:send': this.sendMessage,
   }
 
-  async sendMessage(socket: AuthenticatedSocket<User>, data: Events['chat:send']) {
+  async sendMessage(socket: AuthenticatedSocket<User>, data: { body: string }) {
     this.broadcast('chat:message', {
       user: socket.user,
       body: data.body,
@@ -306,7 +613,10 @@ export default class ChatChannel extends BaseChannel<User, Events> {
 }
 ```
 
-Returning a value from a handler resolves `sendWithAck()` on the client.
+Returning a value from a handler resolves `sendWithAck()` on the client. Handler results and
+presence snapshots must be JSON-serializable. A non-serializable handler result receives an
+immediate negative acknowledgement; a non-serializable initial presence snapshot rolls back the
+subscription instead of leaving client and server state out of sync.
 
 ### Client-to-client events
 
@@ -337,7 +647,6 @@ import { Socket } from '@rlanz/socket/client'
 const socket = new Socket({
   url: 'http://localhost:3333',
   path: '/socket',
-  auth: { token: 'secret' },
   autoReconnect: true,
   reconnectDelay: 250,
   reconnectMaxDelay: 5000,
@@ -393,14 +702,122 @@ 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
+
+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
+generic in every component.
+
+React:
+
+```tsx
+// src/socket.ts
+import { Socket } from '@rlanz/socket/client'
+import { createSocketHooks } from '@rlanz/socket/client/react'
+import type { AppSocket } from '#generated/socket'
+
+export const socket = new Socket<AppSocket>()
+export const { SocketProvider, useChannel, useChannelEvent, useSocketState } =
+  createSocketHooks<AppSocket>()
+
+// app.tsx
+<SocketProvider socket={socket} owned>
+  <Chat />
+</SocketProvider>
+
+function Chat() {
+  const channel = useChannel('chat/general')
+  useChannelEvent('chat/general', 'chat:message', (message) => console.log(message.id))
+
+  return <button onClick={() => channel?.send('chat:send', { text: 'Hello' })}>Send</button>
+}
+```
+
+Vue:
+
+```ts
+// src/socket.ts
+import { Socket } from '@rlanz/socket/client'
+import { createSocketComposables } from '@rlanz/socket/client/vue'
+import type { AppSocket } from '#generated/socket'
+
+export const socket = new Socket<AppSocket>()
+export const { provideSocket, useChannel, useChannelEvent, useSocketState } =
+  createSocketComposables<AppSocket>()
+
+// In the root component setup
+provideSocket(socket, { owned: true })
+
+// In a descendant component setup
+const channel = useChannel('chat/general')
+useChannelEvent('chat/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
+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.
+
 ## Package Exports
 
 ```ts
-import { BaseChannel, ChannelRouter, PresenceManager, SocketService } from '@rlanz/socket'
+import { BaseChannel, ChannelRouter, PresenceManager } from '@rlanz/socket'
 import type { AuthenticatedSocket, SocketConfig } from '@rlanz/socket/types'
 import SocketProvider from '@rlanz/socket/provider'
+import socket from '@rlanz/socket/services/main'
 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 { 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'
 ```
 
@@ -408,7 +825,16 @@ Available exports:
 
 - `@rlanz/socket`
 - `@rlanz/socket/provider`
+- `@rlanz/socket/assembler_hook`
+- `@rlanz/socket/services/main`
 - `@rlanz/socket/decorators`
+- `@rlanz/socket/health_check`
+- `@rlanz/socket/otel`
+- `@rlanz/socket/testing`
 - `@rlanz/socket/types`
+- `@rlanz/socket/types/tracing_channels`
 - `@rlanz/socket/client`
 - `@rlanz/socket/client/types`
+- `@rlanz/socket/client/react`
+- `@rlanz/socket/client/vue`
+- `@rlanz/socket/client/svelte`