@wooksjs/event-ws 0.7.8 → 0.7.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wooksjs/event-ws",
-  "version": "0.7.8",
+  "version": "0.7.9",
   "description": "WebSocket adapter for Wooks with path-based message routing, rooms, and broadcasting",
   "keywords": [
     "api",
@@ -24,13 +24,8 @@
     "url": "git+https://github.com/wooksjs/wooksjs.git",
     "directory": "packages/event-ws"
   },
-  "bin": {
-    "wooksjs-event-ws-skill": "./scripts/setup-skills.js"
-  },
   "files": [
-    "dist",
-    "skills",
-    "scripts/setup-skills.js"
+    "dist"
   ],
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -47,18 +42,17 @@
     "@types/ws": "^8.18.1",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "@wooksjs/event-core": "^0.7.8",
-    "wooks": "^0.7.8"
+    "@wooksjs/event-core": "^0.7.9",
+    "wooks": "^0.7.9"
   },
   "peerDependencies": {
     "@prostojs/logger": "^0.4.3",
     "@prostojs/router": "^0.3.3",
     "ws": "^8.0.0",
-    "@wooksjs/event-core": "^0.7.8",
-    "wooks": "^0.7.8"
+    "@wooksjs/event-core": "^0.7.9",
+    "wooks": "^0.7.9"
   },
   "scripts": {
-    "build": "rolldown -c ../../rolldown.config.mjs",
-    "setup-skills": "node ./scripts/setup-skills.js"
+    "build": "rolldown -c ../../rolldown.config.mjs"
   }
 }

package/scripts/setup-skills.js

@@ -1,78 +0,0 @@
-#!/usr/bin/env node
-/* prettier-ignore */
-import fs from 'fs'
-import path from 'path'
-import os from 'os'
-import { fileURLToPath } from 'url'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-
-const SKILL_NAME = 'wooksjs-event-ws'
-const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
-
-if (!fs.existsSync(SKILL_SRC)) {
-  console.error(`No skills found at ${SKILL_SRC}`)
-  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
-  process.exit(1)
-}
-
-const AGENTS = {
-  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
-  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
-  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
-  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
-  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
-}
-
-const args = process.argv.slice(2)
-const isGlobal = args.includes('--global') || args.includes('-g')
-const isPostinstall = args.includes('--postinstall')
-let installed = 0, skipped = 0
-const installedDirs = []
-
-for (const [agentName, cfg] of Object.entries(AGENTS)) {
-  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
-  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
-
-  // In postinstall mode: silently skip agents that aren't set up globally
-  if (isPostinstall || isGlobal) {
-    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
-  }
-
-  const dest = path.join(targetBase, SKILL_NAME)
-  try {
-    fs.mkdirSync(dest, { recursive: true })
-    fs.cpSync(SKILL_SRC, dest, { recursive: true })
-    console.log(`✅  ${agentName}: installed to ${dest}`)
-    installed++
-    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
-  } catch (err) {
-    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
-  }
-}
-
-// Add locally-installed skill dirs to .gitignore
-if (!isGlobal && installedDirs.length > 0) {
-  const gitignorePath = path.join(process.cwd(), '.gitignore')
-  let gitignoreContent = ''
-  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
-  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
-  if (linesToAdd.length > 0) {
-    const hasHeader = gitignoreContent.includes('# AI agent skills')
-    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
-      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
-      + linesToAdd.join('\n') + '\n'
-    fs.appendFileSync(gitignorePath, block)
-    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
-  }
-}
-
-if (installed === 0 && isPostinstall) {
-  // Silence is fine — no agents present, nothing to do
-} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
-  console.log('No agent directories detected. Try --global or run without it for project-local install.')
-} else if (installed === 0) {
-  console.log('Nothing installed. Run without --global to install project-locally.')
-} else {
-  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
-}

package/skills/wooksjs-event-ws/SKILL.md

@@ -1,50 +0,0 @@
----
-name: wooksjs-event-ws
-description: Use this skill when working with @wooksjs/event-ws — to create a WebSocket server with createWsApp() or WooksWs, register message handlers with onMessage(), handle connections with onConnect()/onDisconnect(), use composables like useWsConnection(), useWsMessage(), useWsRooms(), useWsServer(), manage rooms and broadcasting with WsRoomManager and WsBroadcastTransport, integrate with event-http via upgrade(), throw WsError for error replies, or test handlers with prepareTestWsConnectionContext()/prepareTestWsMessageContext(). Covers the wire protocol (WsClientMessage, WsReplyMessage, WsPushMessage), standalone and HTTP-integrated modes, heartbeat, and custom serializers.
----
-
-# @wooksjs/event-ws
-
-WebSocket adapter for Wooks with path-based message routing, rooms, broadcasting, and composable context — runs standalone or integrated with `@wooksjs/event-http`.
-
-## How to use this skill
-
-Read the domain file that matches the task. Do not load all files — only what you need.
-
-| Domain                | File                             | Load when...                                                                                                   |
-| --------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| Core concepts & setup | [core.md](core.md)               | Creating a WS server, understanding the wire protocol, configuring options, standalone vs HTTP-integrated mode |
-| Composables           | [composables.md](composables.md) | Using `useWsConnection`, `useWsMessage`, `useWsRooms`, `useWsServer`, or `currentConnection` inside handlers   |
-| Rooms & broadcasting  | [rooms.md](rooms.md)             | Managing rooms, broadcasting to groups, cross-instance pub/sub with `WsBroadcastTransport`                     |
-| Testing               | [testing.md](testing.md)         | Unit-testing WS handlers with `prepareTestWsConnectionContext` and `prepareTestWsMessageContext`               |
-
-## Quick reference
-
-```ts
-import {
-  // factory
-  createWsApp,
-  WooksWs,
-  // composables
-  useWsConnection,
-  useWsMessage,
-  useWsRooms,
-  useWsServer,
-  currentConnection,
-  // context factories
-  createWsConnectionContext,
-  createWsMessageContext,
-  // kinds & types
-  wsConnectionKind,
-  wsMessageKind,
-  WsError,
-  WsConnection,
-  WsRoomManager,
-  // testing
-  prepareTestWsConnectionContext,
-  prepareTestWsMessageContext,
-  // re-exports from event-core
-  useRouteParams,
-  useLogger,
-} from '@wooksjs/event-ws'
-```

package/skills/wooksjs-event-ws/composables.md

@@ -1,157 +0,0 @@
-# Composables — @wooksjs/event-ws
-
-> Composable functions for accessing WebSocket connection, message, room, and server state inside handlers.
-
-## Concepts
-
-All composables follow the Wooks `defineWook` pattern — they read from the current `EventContext` via `AsyncLocalStorage`. They are only valid inside handler functions registered with `onMessage`, `onConnect`, or `onDisconnect`.
-
-The WS adapter creates two context levels:
-
-- **Connection context** — available in `onConnect`, `onDisconnect`, and `onMessage` (via parent chain)
-- **Message context** — only available in `onMessage` handlers
-
-## API Reference
-
-### `useWsConnection(ctx?)`
-
-Access the current WebSocket connection. Works in both connection and message contexts.
-
-Returns:
-
-```ts
-{
-  id: string                    // unique connection ID (UUID)
-  send(event, path, data?, params?): void  // push a message to this client
-  close(code?, reason?): void   // close the connection
-  context: EventContext          // the connection EventContext
-}
-```
-
-```ts
-ws.onMessage('message', '/chat/:room', () => {
-  const { id, send } = useWsConnection()
-  send('ack', '/chat/lobby', { received: true })
-})
-```
-
-### `useWsMessage<T>(ctx?)`
-
-Access the current WebSocket message data. **Only available in message context** (inside `onMessage` handlers).
-
-Returns:
-
-```ts
-{
-  data: T // parsed message data (generic typed)
-  raw: Buffer | string // raw message before parsing
-  id: string | number | undefined // correlation ID
-  path: string // message path
-  event: string // message event type
-}
-```
-
-```ts
-ws.onMessage('message', '/chat/:room', () => {
-  const { data, id, path } = useWsMessage<{ text: string }>()
-  console.log(data.text) // typed as string
-})
-```
-
-### `useWsRooms(ctx?)`
-
-Room management for the current connection. **Only available in message context.** Defaults to the current message path as the room name.
-
-Returns:
-
-```ts
-{
-  join(room?): void              // join a room (default: current message path)
-  leave(room?): void             // leave a room (default: current message path)
-  broadcast(event, data?, options?): void  // broadcast to a room
-  rooms(): string[]              // list rooms this connection has joined
-}
-```
-
-`WsBroadcastOptions`:
-
-```ts
-{
-  room?: string          // target room (default: current message path)
-  excludeSelf?: boolean  // exclude sender (default: true)
-}
-```
-
-```ts
-ws.onMessage('subscribe', '/chat/rooms/:roomId', () => {
-  const { join } = useWsRooms()
-  join() // joins the room matching the current path
-})
-
-ws.onMessage('message', '/chat/rooms/:roomId', () => {
-  const { data } = useWsMessage<{ text: string }>()
-  const { broadcast } = useWsRooms()
-  broadcast('message', data) // sends to all in room except sender
-})
-```
-
-### `useWsServer()`
-
-Server-wide operations. Available in any context (not scoped to a specific connection). Reads directly from adapter state, not from `EventContext`.
-
-Returns:
-
-```ts
-{
-  connections(): Map<string, WsConnection>         // all active connections
-  broadcast(event, path, data?, params?): void     // broadcast to ALL connections
-  getConnection(id: string): WsConnection | undefined
-  roomConnections(room: string): Set<WsConnection> // connections in a room
-}
-```
-
-```ts
-ws.onMessage('rpc', '/admin/broadcast', () => {
-  const { data } = useWsMessage<{ text: string }>()
-  const { broadcast } = useWsServer()
-  broadcast('announcement', '/system', data)
-})
-```
-
-### `currentConnection(ctx?)`
-
-Returns the connection `EventContext` regardless of whether you're in a connection or message handler.
-
-- In `onConnect`/`onDisconnect`: returns `current()` directly
-- In `onMessage`: returns `current().parent` (the connection context)
-
-```ts
-const connCtx = currentConnection()
-```
-
-### Re-exports from `@wooksjs/event-core`
-
-These are re-exported for convenience:
-
-- `useRouteParams(ctx?)` — access path params from the Wooks router
-- `useLogger(ctx?)` — access the scoped logger
-
-```ts
-ws.onMessage('rpc', '/users/:id', () => {
-  const { params } = useRouteParams()
-  return { userId: params.id }
-})
-```
-
-## Best Practices
-
-- Always type `useWsMessage<T>()` with your expected payload type for type safety
-- Use `useWsRooms()` without arguments to default to the current message path as the room — this is the most common pattern
-- Prefer `useWsServer().broadcast()` for server-wide announcements, `useWsRooms().broadcast()` for room-scoped messages
-- The `context` property from `useWsConnection()` gives access to the raw `EventContext` for advanced use (e.g., reading custom context keys set during `onConnect`)
-
-## Gotchas
-
-- `useWsMessage()` and `useWsRooms()` throw if called outside a message context (e.g., inside `onConnect`)
-- `useWsServer()` is not a `defineWook` — it reads from module-level adapter state, so it works anywhere but requires the adapter to be initialized
-- `useWsConnection().send()` silently drops messages if the socket is not in OPEN state (readyState !== 1)

package/skills/wooksjs-event-ws/core.md

@@ -1,229 +0,0 @@
-# Core concepts & setup — @wooksjs/event-ws
-
-> WebSocket adapter for Wooks: creates a WS server, routes messages by event+path, manages connections, and supports standalone or HTTP-integrated modes.
-
-## Concepts
-
-`@wooksjs/event-ws` follows the Wooks adapter pattern. It creates two nested context layers via dedicated context factories:
-
-1. **Connection context** (`ws:connection` kind) — long-lived, one per connected client. Created via `createWsConnectionContext(options, seeds, fn)`, seeded with `id` and `ws` socket.
-2. **Message context** (`ws:message` kind) — short-lived, one per incoming message. Created via `createWsMessageContext(options, seeds, fn)` with `parent` set to the connection context.
-
-Messages follow a JSON wire protocol with `event` + `path` for routing and an optional `id` for request-response correlation.
-
-### Wire protocol
-
-**Client → Server (`WsClientMessage`):**
-
-```ts
-interface WsClientMessage {
-  event: string // router method (e.g. "message", "rpc", "subscribe")
-  path: string // route path (e.g. "/chat/rooms/lobby")
-  data?: unknown // payload
-  id?: string | number // correlation ID — triggers a reply
-}
-```
-
-**Server → Client reply (`WsReplyMessage`):**
-
-```ts
-interface WsReplyMessage {
-  id: string | number // matches the client's id
-  data?: unknown // handler return value
-  error?: { code: number; message: string }
-}
-```
-
-**Server → Client push (`WsPushMessage`):**
-
-```ts
-interface WsPushMessage {
-  event: string
-  path: string
-  params?: Record<string, string>
-  data?: unknown
-}
-```
-
-## Installation / Setup
-
-```bash
-pnpm add @wooksjs/event-ws wooks @wooksjs/event-core ws
-```
-
-`ws` is a peer dependency (the default WebSocket server implementation). You can substitute it with a custom `WsServerAdapter`.
-
-## API Reference
-
-### `createWsApp(wooksOrOpts?, opts?)`
-
-Factory that creates a `WooksWs` instance.
-
-- `wooksOrOpts` — a `Wooks` or `WooksAdapterBase` instance (HTTP integration), or `TWooksWsOptions` (standalone)
-- `opts` — `TWooksWsOptions` when the first arg is a Wooks instance
-
-Returns: `WooksWs`
-
-### `TWooksWsOptions`
-
-```ts
-interface TWooksWsOptions {
-  heartbeatInterval?: number // ping interval in ms (default: 30000, 0 = disabled)
-  heartbeatTimeout?: number // pong timeout in ms (default: 5000)
-  messageParser?: (raw: Buffer | string) => WsClientMessage
-  messageSerializer?: (msg: WsReplyMessage | WsPushMessage) => string | Buffer
-  logger?: TConsoleBase
-  maxMessageSize?: number // bytes (default: 1MB), oversized messages are dropped
-  wsServerAdapter?: WsServerAdapter // custom WS engine (default: wraps `ws`)
-  broadcastTransport?: WsBroadcastTransport // for multi-instance
-}
-```
-
-### `WooksWs` class
-
-Extends `WooksAdapterBase`, implements `WooksUpgradeHandler`.
-
-#### `ws.onMessage(event, path, handler)`
-
-Register a routed message handler. Uses the Wooks router — supports path params.
-
-```ts
-ws.onMessage('message', '/chat/rooms/:roomId', () => {
-  const { data } = useWsMessage<{ text: string }>()
-  const { params } = useRouteParams()
-  // ...
-})
-```
-
-#### `ws.onConnect(handler)`
-
-Register a handler that runs when a new WebSocket connection is established. Runs inside the connection context. Throwing or rejecting closes the connection.
-
-```ts
-ws.onConnect(() => {
-  const { id } = useWsConnection()
-  console.log('Connected:', id)
-})
-```
-
-#### `ws.onDisconnect(handler)`
-
-Register a handler that runs when a connection closes.
-
-#### `ws.upgrade()`
-
-Complete the WebSocket handshake from inside an HTTP UPGRADE route handler. Reads `req`/`socket`/`head` from the current HTTP context. The HTTP context becomes the parent of the WS connection context.
-
-#### `ws.handleUpgrade(req, socket, head)`
-
-Fallback for when no UPGRADE route matches (called by the HTTP adapter automatically).
-
-#### `ws.listen(port, hostname?)`
-
-Start a standalone server (without `event-http`). Returns a `Promise<void>`.
-
-#### `ws.close()`
-
-Stop the server, close all connections, clean up heartbeat.
-
-#### `ws.getServer()`
-
-Returns the underlying `http.Server` (standalone mode only).
-
-### `WsError`
-
-Error class with a numeric `code` following HTTP conventions. Throwing `WsError` in a handler sends an error reply to the client.
-
-```ts
-throw new WsError(403, 'Forbidden')
-```
-
-### `WsSocket` interface
-
-Minimal WebSocket instance interface — compatible with `ws`, uWebSockets.js, and Bun.
-
-### `WsServerAdapter` interface
-
-Factory for creating a custom WebSocket server:
-
-```ts
-interface WsServerAdapter {
-  create(): WsServerInstance
-}
-```
-
-## Common Patterns
-
-### Pattern: HTTP-integrated mode (recommended)
-
-```ts
-import { createHttpApp } from '@wooksjs/event-http'
-import { createWsApp } from '@wooksjs/event-ws'
-
-const http = createHttpApp()
-const ws = createWsApp(http) // auto-registers upgrade contract
-
-http.upgrade('/ws', () => ws.upgrade())
-
-ws.onMessage('message', '/chat/rooms/:roomId', () => {
-  const { data } = useWsMessage<{ text: string }>()
-  return { ok: true }
-})
-
-http.listen(3000)
-```
-
-### Pattern: Standalone mode
-
-```ts
-import { createWsApp } from '@wooksjs/event-ws'
-
-const ws = createWsApp({ heartbeatInterval: 30_000 })
-
-ws.onMessage('rpc', '/users/:id', () => {
-  const { data } = useWsMessage()
-  const { params } = useRouteParams()
-  return { userId: params.id }
-})
-
-ws.listen(3000)
-```
-
-### Pattern: Connection authentication
-
-```ts
-ws.onConnect(() => {
-  // Access HTTP context if using HTTP-integrated mode
-  // Throw to reject the connection
-  const token = getTokenFromSomewhere()
-  if (!isValid(token)) {
-    throw new WsError(401, 'Unauthorized')
-  }
-})
-```
-
-### Pattern: Custom serializer (e.g. MessagePack)
-
-```ts
-import { encode, decode } from '@msgpack/msgpack'
-
-const ws = createWsApp({
-  messageParser: (raw) => decode(raw as Buffer) as WsClientMessage,
-  messageSerializer: (msg) => Buffer.from(encode(msg)),
-})
-```
-
-## Best Practices
-
-- Use HTTP-integrated mode for production — it shares the HTTP server and handles UPGRADE routing cleanly
-- Set `maxMessageSize` appropriate for your use case to prevent memory abuse
-- Use `WsError` with HTTP-style codes for structured error replies
-- Keep `onConnect` handlers fast — they block connection acceptance
-- Heartbeat is enabled by default (30s); set to 0 only for short-lived connections
-
-## Gotchas
-
-- Handler return values are only sent as replies when the client message included an `id` field. Fire-and-forget messages (no `id`) get no reply even if the handler returns a value.
-- The `ws` package is a peer dependency — you must install it explicitly.
-- `useWsRooms()` and `useWsMessage()` are only available in message context (inside `onMessage` handlers), not in `onConnect`/`onDisconnect`.
-- When a connection context has an HTTP parent (integrated mode), composables from `@wooksjs/event-http` can read HTTP headers/cookies via the parent chain.

package/skills/wooksjs-event-ws/rooms.md

@@ -1,139 +0,0 @@
-# Rooms & broadcasting — @wooksjs/event-ws
-
-> Room-based connection grouping, local and cross-instance broadcasting, and the broadcast transport interface.
-
-## Concepts
-
-Rooms are named groups of connections. A connection can join multiple rooms. Broadcasting sends a push message to all connections in a room, optionally excluding the sender.
-
-The room system has two layers:
-
-1. **Local** — `WsRoomManager` tracks `Map<string, Set<WsConnection>>` in memory
-2. **Distributed** — optional `WsBroadcastTransport` for cross-instance pub/sub (e.g., Redis)
-
-When a message is broadcast:
-
-1. Local connections in the room receive it directly
-2. If a transport is configured, the message is published to `ws:room:{roomName}` for other instances
-3. Other instances receive it via the transport subscription and forward to their local connections
-
-## API Reference
-
-### `WsRoomManager`
-
-Internal class that manages room → connections mapping. Not typically used directly — use `useWsRooms()` composable instead.
-
-```ts
-class WsRoomManager {
-  join(connection: WsConnection, room: string): void
-  leave(connection: WsConnection, room: string): void
-  leaveAll(connection: WsConnection): void // called automatically on disconnect
-  connections(room: string): Set<WsConnection>
-  broadcast(room, event, path, data?, params?, exclude?): void
-}
-```
-
-### `WsBroadcastTransport` interface
-
-Pluggable transport for cross-instance broadcasting:
-
-```ts
-interface WsBroadcastTransport {
-  publish(channel: string, payload: string): void | Promise<void>
-  subscribe(channel: string, handler: (payload: string) => void): void | Promise<void>
-  unsubscribe(channel: string): void | Promise<void>
-}
-```
-
-Channels follow the pattern `ws:room:{roomName}`. The payload is a JSON-stringified object containing `{ event, path, data, params, excludeId }`.
-
-### `useWsRooms()` composable
-
-See [composables.md](composables.md) for full API. The composable provides `join()`, `leave()`, `broadcast()`, and `rooms()` scoped to the current connection and message path.
-
-## Common Patterns
-
-### Pattern: Chat rooms
-
-```ts
-ws.onMessage('subscribe', '/chat/rooms/:roomId', () => {
-  const { join } = useWsRooms()
-  join() // joins room = "/chat/rooms/:roomId" (resolved path)
-  return { subscribed: true }
-})
-
-ws.onMessage('unsubscribe', '/chat/rooms/:roomId', () => {
-  const { leave } = useWsRooms()
-  leave()
-  return { unsubscribed: true }
-})
-
-ws.onMessage('message', '/chat/rooms/:roomId', () => {
-  const { data } = useWsMessage<{ text: string }>()
-  const { broadcast } = useWsRooms()
-  broadcast('message', data) // excludes sender by default
-  return { sent: true }
-})
-```
-
-### Pattern: Redis broadcast transport
-
-```ts
-import Redis from 'ioredis'
-
-const pub = new Redis()
-const sub = new Redis()
-const handlers = new Map<string, (payload: string) => void>()
-
-const redisTransport: WsBroadcastTransport = {
-  publish(channel, payload) {
-    pub.publish(channel, payload)
-  },
-  subscribe(channel, handler) {
-    handlers.set(channel, handler)
-    sub.subscribe(channel)
-  },
-  unsubscribe(channel) {
-    handlers.delete(channel)
-    sub.unsubscribe(channel)
-  },
-}
-
-sub.on('message', (channel, payload) => {
-  handlers.get(channel)?.(payload)
-})
-
-const ws = createWsApp({ broadcastTransport: redisTransport })
-```
-
-### Pattern: Server-wide broadcast (no rooms)
-
-```ts
-const { broadcast } = useWsServer()
-broadcast('announcement', '/system/alert', { message: 'Server restarting' })
-```
-
-### Pattern: Broadcast to a specific room from outside message context
-
-```ts
-// From a different handler (e.g., HTTP endpoint)
-const { roomConnections } = useWsServer()
-const connections = roomConnections('/chat/rooms/lobby')
-for (const conn of connections) {
-  conn.send('notification', '/chat/rooms/lobby', { text: 'New event!' })
-}
-```
-
-## Best Practices
-
-- Room names default to the message path — this is the most natural mapping (subscribe to `/chat/rooms/lobby` → join room `/chat/rooms/lobby`)
-- Use `excludeSelf: true` (default) for chat-style broadcasts where the sender already has their own confirmation
-- Implement `WsBroadcastTransport` for horizontal scaling — without it, broadcasts only reach connections on the same instance
-- Connections are automatically removed from all rooms on disconnect (`leaveAll` is called internally)
-
-## Gotchas
-
-- The transport channel format is `ws:room:{roomName}` — make sure your Redis/NATS key patterns don't conflict
-- Transport messages include `excludeId` to prevent echo on the originating instance, but the exclude only works by connection ID — if the same user has multiple connections, other connections will still receive the broadcast
-- Empty rooms are automatically cleaned up (removed from the internal Map)
-- `useWsRooms()` is only available in message context — you cannot join/leave rooms from `onConnect`/`onDisconnect`

package/skills/wooksjs-event-ws/testing.md

@@ -1,150 +0,0 @@
-# Testing — @wooksjs/event-ws
-
-> Test helpers for creating mock WS contexts and running handler code outside a real server.
-
-## Concepts
-
-`@wooksjs/event-ws` provides test utilities that create fully initialized `EventContext` instances with mock WebSocket sockets. These let you unit-test composables and handler logic without starting a server or establishing real connections.
-
-Two context types match the two context layers:
-
-1. **Connection context** — for testing `onConnect`/`onDisconnect` handlers
-2. **Message context** — for testing `onMessage` handlers (includes a parent connection context)
-
-Each helper returns a **runner function** `<T>(cb: (...a: any[]) => T) => T` that executes a callback inside the scoped context.
-
-## API Reference
-
-### `prepareTestWsConnectionContext(options?)`
-
-Creates a connection context with a mock `WsSocket`.
-
-Options:
-
-```ts
-interface TTestWsConnectionContext {
-  id?: string // default: 'test-conn-id'
-  params?: Record<string, string | string[]> // pre-set route params
-  parentCtx?: EventContext // optional parent (e.g., HTTP context)
-}
-```
-
-Returns: `<T>(cb: (...a: any[]) => T) => T`
-
-```ts
-import { prepareTestWsConnectionContext } from '@wooksjs/event-ws'
-
-const runInCtx = prepareTestWsConnectionContext({ id: 'conn-1' })
-
-runInCtx(() => {
-  const { id } = useWsConnection()
-  expect(id).toBe('conn-1')
-})
-```
-
-### `prepareTestWsMessageContext(options)`
-
-Creates a message context with a parent connection context. Both contexts are fully seeded.
-
-Options:
-
-```ts
-interface TTestWsMessageContext extends TTestWsConnectionContext {
-  event: string // required
-  path: string // required
-  data?: unknown
-  messageId?: string | number
-  rawMessage?: Buffer | string // default: JSON.stringify of the message
-}
-```
-
-Returns: `<T>(cb: (...a: any[]) => T) => T`
-
-```ts
-import { prepareTestWsMessageContext } from '@wooksjs/event-ws'
-
-const runInCtx = prepareTestWsMessageContext({
-  event: 'message',
-  path: '/chat/lobby',
-  data: { text: 'hello' },
-  messageId: 42,
-})
-
-runInCtx(() => {
-  const { data, id, path } = useWsMessage<{ text: string }>()
-  expect(data.text).toBe('hello')
-  expect(id).toBe(42)
-  expect(path).toBe('/chat/lobby')
-})
-```
-
-## Common Patterns
-
-### Pattern: Testing composables with adapter state
-
-When testing composables that access adapter state (`useWsConnection`, `useWsRooms`), you must set up the adapter state first:
-
-```ts
-import { setAdapterState } from '@wooksjs/event-ws/composables/state' // internal
-import { WsRoomManager, WsConnection } from '@wooksjs/event-ws'
-
-const connections = new Map<string, WsConnection>()
-const roomManager = new WsRoomManager()
-setAdapterState({
-  connections,
-  roomManager,
-  serializer: JSON.stringify,
-  wooks: {} as any,
-})
-```
-
-Note: `setAdapterState` is an internal function — import it from the source in tests.
-
-### Pattern: Testing with HTTP parent context
-
-```ts
-import { EventContext } from '@wooksjs/event-core'
-
-const httpCtx = new EventContext({ logger: console as any })
-// Seed httpCtx with HTTP-specific data if needed
-
-const runInCtx = prepareTestWsMessageContext({
-  event: 'test',
-  path: '/test',
-  parentCtx: httpCtx,
-})
-
-runInCtx(() => {
-  const connCtx = currentConnection()
-  expect(connCtx.parent).toBe(httpCtx)
-})
-```
-
-### Pattern: Testing route params
-
-```ts
-const runInCtx = prepareTestWsMessageContext({
-  event: 'message',
-  path: '/chat/rooms/lobby',
-  params: { roomId: 'lobby' },
-  data: { text: 'hi' },
-})
-
-runInCtx(() => {
-  const { params } = useRouteParams()
-  expect(params.roomId).toBe('lobby')
-})
-```
-
-## Best Practices
-
-- Always use the test helpers rather than manually constructing `EventContext` — they ensure proper kind seeding
-- Set up adapter state before testing composables that depend on it (`useWsConnection`, `useWsRooms`, `useWsServer`)
-- Use `parentCtx` to simulate HTTP-integrated mode when testing composables that traverse the parent chain
-- The mock `WsSocket` has no-op methods — if you need to assert on sent messages, create a custom mock and use `WsConnection` directly
-
-## Gotchas
-
-- The mock socket's `readyState` is set to `1` (OPEN) by default — `send()` calls will pass the guard check
-- `prepareTestWsMessageContext` requires `event` and `path` — they are not optional
-- Test contexts use `console` as the logger — override in `TTestWsConnectionContext` is not directly supported; wrap with a custom `EventContext` if needed