feat(websocket): Add TypedRouter WebSocket integration, connection registry, peer tagging and broadcast APIs

ts/core/smartserve.interfaces.ts

@@ -3,6 +3,8 @@
  * Uses Web Standards API (Request/Response) for cross-platform compatibility
  */
 
+import type { TypedRouter } from '@api.global/typedrequest';
+
 // =============================================================================
 // HTTP Types
 // =============================================================================
@@ -168,18 +170,55 @@ export interface IWebSocketPeer {
   context: IRequestContext;
   /** Custom per-peer data storage */
   data: Map<string, unknown>;
+  /** Tags for connection filtering/grouping */
+  tags: Set<string>;
 }
 
 /**
  * WebSocket event hooks
  */
 export interface IWebSocketHooks {
+  /** Called when WebSocket connection opens */
   onOpen?: (peer: IWebSocketPeer) => void | Promise<void>;
+  /** Called when message received. Mutually exclusive with typedRouter. */
   onMessage?: (peer: IWebSocketPeer, message: IWebSocketMessage) => void | Promise<void>;
+  /** Called when WebSocket connection closes */
   onClose?: (peer: IWebSocketPeer, code: number, reason: string) => void | Promise<void>;
+  /** Called on WebSocket error */
   onError?: (peer: IWebSocketPeer, error: Error) => void | Promise<void>;
+  /** Called when ping received */
   onPing?: (peer: IWebSocketPeer, data: Uint8Array) => void | Promise<void>;
+  /** Called when pong received */
   onPong?: (peer: IWebSocketPeer, data: Uint8Array) => void | Promise<void>;
+
+  /**
+   * TypedRouter for type-safe RPC over WebSocket.
+   * Mutually exclusive with onMessage - cannot use both.
+   * When set, enables connection registry and broadcast methods.
+   */
+  typedRouter?: TypedRouter;
+
+  /**
+   * Called when connection is established and registered.
+   * Only available when typedRouter is configured.
+   * Use this to tag connections for filtering.
+   */
+  onConnectionOpen?: (peer: IWebSocketPeer) => void | Promise<void>;
+
+  /**
+   * Called when connection is closed and unregistered.
+   * Only available when typedRouter is configured.
+   */
+  onConnectionClose?: (peer: IWebSocketPeer) => void | Promise<void>;
+}
+
+/**
+ * Internal callbacks for adapter-to-SmartServe communication
+ * @internal
+ */
+export interface IWebSocketConnectionCallbacks {
+  onRegister: (peer: IWebSocketPeer) => void;
+  onUnregister: (peerId: string) => void;
 }
 
 // =============================================================================