@fluxstack/live 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,145 @@
+# @fluxstack/live
+
+Framework-agnostic core for real-time server-client state synchronization.
+
+Live Components turn server-side classes into reactive state that syncs automatically with connected clients over WebSocket. Write your logic once on the server, and clients receive state updates in real-time.
+
+## Installation
+
+```bash
+bun add @fluxstack/live
+```
+
+## Quick Start
+
+```typescript
+import { LiveServer, LiveComponent } from '@fluxstack/live'
+
+// 1. Define a component
+class Counter extends LiveComponent<{ count: number }> {
+  static componentName = 'Counter'
+  static defaultState = { count: 0 }
+  static publicActions = ['increment', 'decrement'] as const
+
+  increment() {
+    this.count++
+  }
+
+  decrement() {
+    this.count--
+  }
+}
+
+// 2. Create server with your transport adapter
+import { ElysiaTransport } from '@fluxstack/live-elysia'
+
+const server = new LiveServer({
+  transport: new ElysiaTransport(app),
+  componentsPath: './src/components',
+})
+
+await server.start()
+```
+
+## Features
+
+- **LiveComponent** — Base class with reactive state proxy, auto-sync, and lifecycle hooks
+- **LiveServer** — Orchestrator that wires transport, components, auth, rooms, and cluster
+- **ComponentRegistry** — Auto-discovers components from a directory or manual registration
+- **Rooms** — Built-in room system with typed events and cross-instance pub/sub
+- **Auth** — Per-component and per-action authorization (`static auth`, `static actionAuth`)
+- **State Signing** — HMAC-SHA256 state signing with hybrid nonce replay protection
+- **Rate Limiting** — Token bucket rate limiter per connection
+- **Security** — Payload sanitization against prototype pollution, message size limits
+- **Binary Delta** — Efficient binary state diffs for high-frequency updates
+- **File Upload** — Chunked file upload over WebSocket
+- **Cluster** — `IClusterAdapter` interface for horizontal scaling (singleton coordination, action forwarding, state mirroring)
+- **Monitoring** — Performance monitor with per-component metrics
+
+## Transport Adapters
+
+This package is framework-agnostic. Use it with any transport adapter:
+
+| Adapter | Package |
+|---------|---------|
+| Elysia | `@fluxstack/live-elysia` |
+| Express | `@fluxstack/live-express` |
+| Fastify | `@fluxstack/live-fastify` |
+
+## LiveComponent
+
+```typescript
+import { LiveComponent } from '@fluxstack/live'
+
+export class TodoList extends LiveComponent<typeof TodoList.defaultState> {
+  static componentName = 'TodoList'
+  static singleton = true
+  static publicActions = ['addTodo', 'toggleTodo'] as const
+  static defaultState = {
+    todos: [] as { id: string; text: string; done: boolean }[]
+  }
+
+  declare todos: typeof TodoList.defaultState['todos']
+
+  addTodo(payload: { text: string }) {
+    this.todos = [...this.todos, { id: crypto.randomUUID(), text: payload.text, done: false }]
+  }
+
+  toggleTodo(payload: { id: string }) {
+    this.todos = this.todos.map(t =>
+      t.id === payload.id ? { ...t, done: !t.done } : t
+    )
+  }
+}
+```
+
+### Lifecycle Hooks
+
+```typescript
+class MyComponent extends LiveComponent<State> {
+  protected onConnect() { }           // WebSocket connected
+  protected async onMount() { }       // Component fully mounted (async)
+  protected onRehydrate(prev) { }     // State restored from client
+  protected onStateChange(changes) { } // After state mutation
+  protected onRoomJoin(roomId) { }    // Joined a room
+  protected onRoomLeave(roomId) { }   // Left a room
+  protected onAction(action, payload) { } // Before action (return false to cancel)
+  protected onDisconnect() { }        // Connection lost
+  protected onDestroy() { }           // Before cleanup (sync)
+}
+```
+
+## LiveServer Options
+
+```typescript
+new LiveServer({
+  transport,                         // Required: transport adapter
+  componentsPath: './components',    // Auto-discover components
+  wsPath: '/api/live/ws',            // WebSocket endpoint (default)
+  debug: false,                      // Debug mode
+  cluster: clusterAdapter,           // IClusterAdapter for horizontal scaling
+  roomPubSub: roomAdapter,           // IRoomPubSubAdapter for cross-instance rooms
+  allowedOrigins: ['https://...'],   // CSRF protection
+  rateLimitMaxTokens: 100,           // Rate limiter max tokens
+  rateLimitRefillRate: 10,           // Tokens refilled per second
+  httpPrefix: '/api/live',           // HTTP monitoring routes
+})
+```
+
+## Horizontal Scaling
+
+```typescript
+import { RedisClusterAdapter, RedisRoomAdapter } from '@fluxstack/live-redis'
+
+const server = new LiveServer({
+  transport,
+  cluster: new RedisClusterAdapter({ redis }),
+  roomPubSub: new RedisRoomAdapter({ redis }),
+})
+```
+
+See `@fluxstack/live-redis` for details.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -144,6 +144,10 @@ interface LiveWSData {
     userId?: string;
     /** Auth context for the connection */
     authContext?: LiveAuthContext;
+    /** Rooms joined by this connection (for per-connection limits) */
+    rooms?: Set<string>;
+    /** Origin header from the WebSocket upgrade request (set by transport adapter) */
+    origin?: string;
 }
 /** @deprecated Use GenericWebSocket instead */
 type FluxStackWebSocket = GenericWebSocket;
@@ -233,6 +237,8 @@ declare function createTypedRoomEventBus<TRoomEvents extends Record<string, Reco
 };
 declare class RoomEventBus {
     private subscriptions;
+    /** Reverse index: componentId -> Set of subscription keys for O(1) unsubscribeAll */
+    private componentIndex;
     private getKey;
     on(roomType: string, roomId: string, event: string, componentId: string, handler: EventHandler): () => void;
     emit(roomType: string, roomId: string, event: string, data: any, excludeComponentId?: string): number;
@@ -246,11 +252,62 @@ declare class RoomEventBus {
     };
 }
 
+/**
+ * Adapter for room state storage.
+ *
+ * All methods return Promises to support async backends (Redis, DB, etc.).
+ * The InMemoryRoomAdapter resolves immediately for zero-overhead in single-instance mode.
+ */
+interface IRoomStorageAdapter {
+    /** Create or get a room. Returns current state and whether it was newly created. */
+    getOrCreateRoom(roomId: string, initialState?: any): Promise<{
+        state: any;
+        created: boolean;
+    }>;
+    /** Get the state of a room. Returns empty object if room doesn't exist. */
+    getState(roomId: string): Promise<any>;
+    /** Update room state (merge partial updates). */
+    updateState(roomId: string, updates: any): Promise<void>;
+    /** Check if a room exists. */
+    hasRoom(roomId: string): Promise<boolean>;
+    /** Delete a room. Returns true if the room existed. */
+    deleteRoom(roomId: string): Promise<boolean>;
+    /** Get storage statistics. */
+    getStats(): Promise<{
+        totalRooms: number;
+        rooms: Record<string, any>;
+    }>;
+}
+/**
+ * Adapter for cross-instance pub/sub (horizontal scaling).
+ *
+ * When running multiple server instances, this adapter propagates room events
+ * between instances. In single-instance mode (InMemoryRoomAdapter), all pub/sub
+ * operations are no-ops since events are already local.
+ */
+interface IRoomPubSubAdapter {
+    /** Publish an event to all server instances subscribed to this room. */
+    publish(roomId: string, event: string, data: any): Promise<void>;
+    /** Subscribe to events for a room (from other server instances). */
+    subscribe(roomId: string, handler: (event: string, data: any) => void): Promise<() => void>;
+    /** Publish a membership change (join/leave) to other instances. */
+    publishMembership(roomId: string, action: 'join' | 'leave', componentId: string): Promise<void>;
+    /** Publish a state change to other instances. */
+    publishStateChange(roomId: string, updates: any): Promise<void>;
+}
+
 declare class LiveRoomManager {
     private roomEvents;
+    private pubsub?;
     private rooms;
     private componentRooms;
-    constructor(roomEvents: RoomEventBus);
+    /**
+     * @param roomEvents - Local server-side event bus
+     * @param pubsub - Optional cross-instance pub/sub adapter (e.g. Redis).
+     *                 When provided, room events/state/membership are propagated
+     *                 to other server instances in the background.
+     */
+    constructor(roomEvents: RoomEventBus, pubsub?: IRoomPubSubAdapter | undefined);
     /**
      * Component joins a room
      */
@@ -262,7 +319,9 @@ declare class LiveRoomManager {
      */
     leaveRoom(componentId: string, roomId: string): void;
     /**
-     * Component disconnects - leave all rooms
+     * Component disconnects - leave all rooms.
+     * Batches removals: removes member from all rooms first,
+     * then sends leave notifications in bulk.
      */
     cleanupComponent(componentId: string): void;
     /**
@@ -270,7 +329,8 @@ declare class LiveRoomManager {
      */
     emitToRoom(roomId: string, event: string, data: any, excludeComponentId?: string): number;
     /**
-     * Update room state
+     * Update room state.
+     * Mutates state in-place with Object.assign to avoid full-object spread.
      */
     setRoomState(roomId: string, updates: any, excludeComponentId?: string): void;
     /**
@@ -278,7 +338,8 @@ declare class LiveRoomManager {
      */
     getRoomState<TState = any>(roomId: string): TState;
     /**
-     * Broadcast to all members in a room
+     * Broadcast to all members in a room.
+     * Serializes the message ONCE and sends the same string to all members.
      */
     private broadcastToRoom;
     /**
@@ -446,33 +507,49 @@ interface StateSignatureConfig {
     compressionEnabled?: boolean;
     /** Enable encryption */
     encryptionEnabled?: boolean;
-    /** Enable anti-replay nonces */
+    /** Enable anti-replay nonces (hybrid: stateless HMAC + replay detection) */
     nonceEnabled?: boolean;
-    /** Maximum state age in ms */
+    /** Maximum state age in ms. Default: 1800000 (30 minutes) */
     maxStateAge?: number;
     /** Enable state backups */
     backupEnabled?: boolean;
     /** Max state backups to keep */
     maxBackups?: number;
+    /** Nonce TTL in ms. Nonces older than this are rejected. Default: 10000 (10 seconds) */
+    nonceTTL?: number;
 }
 declare class StateSignatureManager {
     private secret;
     private previousSecrets;
     private rotationTimer?;
-    private usedNonces;
-    private nonceCleanupTimer?;
     private stateBackups;
     private config;
+    private encryptionSalt;
+    private cachedEncryptionKey;
+    /** Replay detection: nonce → timestamp when it was first seen. Cleaned every 60s. */
+    private usedNonces;
+    private nonceCleanupTimer?;
     constructor(config?: StateSignatureConfig);
+    /**
+     * Generate a hybrid nonce: `timestamp:random:HMAC(timestamp:random, secret)`
+     * Self-validating via HMAC, unique via random bytes, replay-tracked via Map.
+     */
+    private generateNonce;
+    /**
+     * Validate a hybrid nonce: check format, HMAC, and TTL.
+     */
+    private validateNonce;
     signState(componentId: string, state: Record<string, unknown>, version: number, options?: {
         compress?: boolean;
         backup?: boolean;
-    }): Promise<SignedState>;
-    validateState(signedState: SignedState): Promise<{
+    }): SignedState;
+    validateState(signedState: SignedState, options?: {
+        skipNonce?: boolean;
+    }): {
         valid: boolean;
         error?: string;
-    }>;
-    extractData(signedState: SignedState): Promise<Record<string, unknown>>;
+    };
+    extractData(signedState: SignedState): Record<string, unknown>;
     getBackups(componentId: string): SignedState[];
     getLatestBackup(componentId: string): SignedState | null;
     private backupState;
@@ -481,6 +558,7 @@ declare class StateSignatureManager {
     private timingSafeEqual;
     private deriveEncryptionKey;
     private setupKeyRotation;
+    /** Remove nonces older than nonceTTL + 10s from the replay detection map. */
     private cleanupNonces;
     shutdown(): void;
 }
@@ -847,6 +925,8 @@ declare class WebSocketConnectionManager extends EventEmitter {
     private connections;
     private connectionMetrics;
     private connectionPools;
+    /** Reverse index: connectionId -> Set of poolIds for O(1) cleanup */
+    private connectionPoolIndex;
     private messageQueues;
     private healthCheckTimer?;
     private heartbeatTimer?;
@@ -910,8 +990,9 @@ declare function setLiveComponentContext(ctx: LiveComponentContext): void;
  */
 declare function getLiveComponentContext(): LiveComponentContext;
 
-/** @internal Symbol key for singleton emit override */
+/** Symbol key for singleton emit override */
 declare const EMIT_OVERRIDE_KEY: unique symbol;
+
 declare abstract class LiveComponent<TState = ComponentState, TPrivate extends Record<string, any> = Record<string, any>> {
     /** Component name for registry lookup - must be defined in subclasses */
     static componentName: string;
@@ -933,6 +1014,35 @@ declare abstract class LiveComponent<TState = ComponentState, TPrivate extends R
      * Per-action auth configuration.
      */
     static actionAuth?: LiveActionAuthMap;
+    /**
+     * Zod schemas for action payload validation.
+     * When defined, payloads are validated before the action method is called.
+     *
+     * @example
+     * static actionSchemas = {
+     *   sendMessage: z.object({ text: z.string().max(500) }),
+     *   updatePosition: z.object({ x: z.number(), y: z.number() }),
+     * }
+     */
+    static actionSchemas?: Record<string, {
+        safeParse: (data: unknown) => {
+            success: boolean;
+            error?: any;
+            data?: any;
+        };
+    }>;
+    /**
+     * Rate limit for action execution.
+     * Prevents clients from spamming expensive operations.
+     *
+     * @example
+     * static actionRateLimit = { maxCalls: 10, windowMs: 1000, perAction: true }
+     */
+    static actionRateLimit?: {
+        maxCalls: number;
+        windowMs: number;
+        perAction?: boolean;
+    };
     /**
      * Data that survives HMR reloads.
      */
@@ -943,7 +1053,6 @@ declare abstract class LiveComponent<TState = ComponentState, TPrivate extends R
      */
     static singleton?: boolean;
     readonly id: string;
-    private _state;
     state: TState;
     protected ws: GenericWebSocket;
     room?: string;
@@ -951,27 +1060,30 @@ declare abstract class LiveComponent<TState = ComponentState, TPrivate extends R
     broadcastToRoom: (message: BroadcastMessage) => void;
     private _privateState;
     private _authContext;
-    private roomEventUnsubscribers;
-    private joinedRooms;
+    private _authContextSet;
     protected roomType: string;
-    private roomHandles;
-    private _inStateChange;
     [EMIT_OVERRIDE_KEY]: ((type: string, payload: any) => void) | null;
+    private _stateManager;
+    private _messaging;
+    private _actionSecurity;
+    private _roomProxyManager;
+    static publicActions?: readonly string[];
     constructor(initialState: Partial<TState>, ws: GenericWebSocket, options?: {
         room?: string;
         userId?: string;
     });
-    private createDirectStateAccessors;
-    private createStateProxy;
     get $private(): TPrivate;
     get $room(): ServerRoomProxy;
     /**
-     * List of room IDs this component is participating in
+     * List of room IDs this component is participating in.
+     * Cached — invalidated on join/leave.
      */
     get $rooms(): string[];
     get $auth(): LiveAuthContext;
-    /** @internal */
+    /** @internal - Immutable after first set to prevent privilege escalation */
     setAuthContext(context: LiveAuthContext): void;
+    /** @internal - Reset auth context (for registry use in reconnection) */
+    _resetAuthContext(): void;
     get $persistent(): Record<string, any>;
     protected onConnect(): void;
     protected onMount(): void | Promise<void>;
@@ -985,29 +1097,117 @@ declare abstract class LiveComponent<TState = ComponentState, TPrivate extends R
     protected onClientJoin(connectionId: string, connectionCount: number): void;
     protected onClientLeave(connectionId: string, connectionCount: number): void;
     setState(updates: Partial<TState> | ((prev: TState) => Partial<TState>)): void;
+    /**
+     * Send a binary-encoded state delta directly over WebSocket.
+     * Updates internal state (same as setState) then sends the encoder's output
+     * as a binary frame: [0x01][idLen:u8][id_bytes:utf8][payload_bytes].
+     * Bypasses the JSON batcher — ideal for high-frequency updates.
+     */
+    sendBinaryDelta(delta: Partial<TState>, encoder: (delta: Partial<TState>) => Uint8Array): void;
     setValue<K extends keyof TState>(payload: {
         key: K;
         value: TState[K];
-    }): Promise<{
+    }): {
         success: true;
         key: K;
         value: TState[K];
-    }>;
-    static publicActions?: readonly string[];
-    private static readonly BLOCKED_ACTIONS;
+    };
     executeAction(action: string, payload: any): Promise<any>;
     protected emit(type: string, payload: any): void;
     protected broadcast(type: string, payload: any, excludeCurrentUser?: boolean): void;
     protected emitRoomEvent(event: string, data: any, notifySelf?: boolean): number;
     protected onRoomEvent<T = any>(event: string, handler: (data: T) => void): void;
     protected emitRoomEventWithState(event: string, data: any, stateUpdates: Partial<TState>): number;
-    protected subscribeToRoom(roomId: string): Promise<void>;
-    protected unsubscribeFromRoom(): Promise<void>;
+    protected subscribeToRoom(roomId: string): void;
+    protected unsubscribeFromRoom(): void;
     private generateId;
     destroy(): void;
     getSerializableState(): TState;
 }
 
+/**
+ * Adapter for cross-instance component synchronization.
+ *
+ * In single-instance mode, no cluster adapter is needed.
+ * For horizontal scaling, provide a RedisClusterAdapter (or custom implementation).
+ */
+interface IClusterAdapter {
+    /** Unique identifier for this server instance. */
+    readonly instanceId: string;
+    /** Save component state to the shared store. */
+    saveState(componentId: string, componentName: string, state: any): Promise<void>;
+    /** Load component state from the shared store. */
+    loadState(componentId: string): Promise<ClusterComponentState | null>;
+    /** Remove component state from the shared store. */
+    deleteState(componentId: string): Promise<void>;
+    /** Publish a state delta to all server instances. */
+    publishDelta(componentId: string, componentName: string, delta: any): Promise<void>;
+    /** Register handler for incoming state deltas from other instances. */
+    onDelta(handler: ClusterDeltaHandler): void;
+    /** Attempt to claim ownership of a singleton (atomic).
+     *  Returns { claimed: true, recoveredState? } on success, { claimed: false } otherwise.
+     *  When claiming after a failover, recoveredState contains the previous owner's last state. */
+    claimSingleton(componentName: string, componentId: string): Promise<ClusterSingletonClaim>;
+    /** Get the current owner of a singleton. Returns null if not claimed. */
+    getSingletonOwner(componentName: string): Promise<ClusterSingletonOwner | null>;
+    /** Release ownership of a singleton (when last client disconnects). */
+    releaseSingleton(componentName: string): Promise<void>;
+    /** Verify this instance still owns a singleton (split-brain protection). */
+    verifySingletonOwnership(componentName: string): Promise<boolean>;
+    /** Register callback for when this instance loses ownership of a singleton (detected during heartbeat). */
+    onOwnershipLost(handler: (componentName: string) => void): void;
+    /** Save singleton state keyed by componentName (survives owner crash + claim expiry). */
+    saveSingletonState(componentName: string, state: any): Promise<void>;
+    /** Load the last known singleton state by componentName (for failover recovery). */
+    loadSingletonState(componentName: string): Promise<any | null>;
+    /** Forward an action to the owner server instance. Returns the action result. */
+    forwardAction(request: ClusterActionRequest): Promise<ClusterActionResponse>;
+    /** Register handler for incoming forwarded actions from other instances. */
+    onActionForward(handler: (req: ClusterActionRequest) => Promise<ClusterActionResponse>): void;
+    /** Start the adapter (subscribe to channels, start heartbeats, etc.). */
+    start(): Promise<void>;
+    /** Graceful shutdown (unsubscribe, clear intervals, disconnect). */
+    shutdown(): Promise<void>;
+}
+/** State stored in the shared store for a component. */
+interface ClusterComponentState {
+    componentName: string;
+    state: any;
+    instanceId: string;
+    updatedAt: number;
+}
+/** Information about the owner of a singleton. */
+interface ClusterSingletonOwner {
+    instanceId: string;
+    componentId: string;
+}
+/** Request to forward an action to another server instance. */
+interface ClusterActionRequest {
+    sourceInstanceId: string;
+    targetInstanceId: string;
+    componentId: string;
+    componentName: string;
+    action: string;
+    payload: any;
+    requestId: string;
+}
+/** Result of a singleton claim attempt. */
+interface ClusterSingletonClaim {
+    /** Whether the claim was successful. */
+    claimed: boolean;
+    /** If claimed and previous state exists (failover recovery), the recovered state. */
+    recoveredState?: any;
+}
+/** Response from a forwarded action. */
+interface ClusterActionResponse {
+    success: boolean;
+    result?: any;
+    error?: string;
+    requestId: string;
+}
+/** Handler for incoming state deltas from other instances. */
+type ClusterDeltaHandler = (componentId: string, componentName: string, delta: any, sourceInstanceId: string) => void;
+
 interface ComponentMetadata {
     id: string;
     name: string;
@@ -1041,6 +1241,7 @@ interface ComponentRegistryDeps {
     debugger: LiveDebugger;
     stateSignature: StateSignatureManager;
     performanceMonitor: PerformanceMonitor;
+    cluster?: IClusterAdapter;
 }
 declare class ComponentRegistry {
     private components;
@@ -1051,11 +1252,15 @@ declare class ComponentRegistry {
     private autoDiscoveredComponents;
     private healthCheckInterval?;
     private singletons;
+    private remoteSingletons;
+    private cluster?;
     private authManager;
     private debugger;
     private stateSignature;
     private performanceMonitor;
     constructor(deps: ComponentRegistryDeps);
+    /** Set up handlers for incoming cluster messages (deltas, forwarded actions). */
+    private setupClusterHandlers;
     private setupHealthMonitoring;
     registerComponent<TState>(definition: ComponentDefinition<TState>): void;
     registerComponentClass(name: string, componentClass: new (initialState: any, ws: GenericWebSocket, options?: {
@@ -1085,8 +1290,10 @@ declare class ComponentRegistry {
     private ensureWsData;
     private isSingletonComponent;
     private removeSingletonConnection;
-    unmountComponent(componentId: string, ws?: GenericWebSocket): Promise<void>;
+    unmountComponent(componentId: string, ws?: GenericWebSocket): void;
     private getSingletonName;
+    /** Find a remote singleton entry by componentId. */
+    private findRemoteSingleton;
     executeAction(componentId: string, action: string, payload: any): Promise<any>;
     updateProperty(componentId: string, property: string, value: any): void;
     subscribeToRoom(componentId: string, roomId: string): void;
@@ -1110,6 +1317,13 @@ declare class ComponentRegistry {
                 connections: number;
             };
         };
+        remoteSingletons: {
+            [k: string]: {
+                componentId: string;
+                ownerInstanceId: string;
+                connections: number;
+            };
+        };
         roomDetails: {
             [k: string]: number;
         };
@@ -1176,6 +1390,19 @@ interface LiveServerOptions {
     componentsPath?: string;
     /** HTTP monitoring routes prefix. Set to false to disable. Defaults to '/api/live' */
     httpPrefix?: string | false;
+    /** Allowed origins for WebSocket connections (CSRF protection).
+     *  When set, connections from unlisted origins are rejected.
+     *  Example: ['https://myapp.com', 'http://localhost:3000'] */
+    allowedOrigins?: string[];
+    /** Optional cross-instance pub/sub adapter for horizontal scaling (e.g. Redis).
+     *  When provided, room events, state changes, and membership are propagated
+     *  across server instances. Without this, rooms are local to the current instance. */
+    roomPubSub?: IRoomPubSubAdapter;
+    /** Optional cluster adapter for cross-instance component synchronization.
+     *  When provided, singleton components are coordinated across instances,
+     *  component state is mirrored to a shared store (Redis), and actions on
+     *  remote singletons are forwarded to the owner instance. */
+    cluster?: IClusterAdapter;
 }
 declare class LiveServer {
     readonly roomEvents: RoomEventBus;
@@ -1211,6 +1438,27 @@ declare class LiveServer {
     private buildHttpRoutes;
 }
 
+interface PendingMessage {
+    type: string;
+    componentId: string;
+    payload: any;
+    timestamp: number;
+    userId?: string;
+    room?: string;
+    [key: string]: any;
+}
+/**
+ * Queue a message to be sent on the next microtask flush.
+ * Messages are batched per-WS and sent as a JSON array.
+ */
+declare function queueWsMessage(ws: GenericWebSocket, message: PendingMessage): void;
+/**
+ * Send a message immediately (bypass batching).
+ * Used for ACTION_RESPONSE and other request-response patterns
+ * where the client is awaiting an immediate response.
+ */
+declare function sendImmediate(ws: GenericWebSocket, data: string): void;
+
 /**
  * Encode a binary chunk message for transmission.
  * @param header - JSON metadata about the chunk
@@ -1314,6 +1562,26 @@ declare class RoomStateManager {
     };
 }
 
+declare class InMemoryRoomAdapter implements IRoomStorageAdapter, IRoomPubSubAdapter {
+    private rooms;
+    getOrCreateRoom(roomId: string, initialState?: any): Promise<{
+        state: any;
+        created: boolean;
+    }>;
+    getState(roomId: string): Promise<any>;
+    updateState(roomId: string, updates: any): Promise<void>;
+    hasRoom(roomId: string): Promise<boolean>;
+    deleteRoom(roomId: string): Promise<boolean>;
+    getStats(): Promise<{
+        totalRooms: number;
+        rooms: Record<string, any>;
+    }>;
+    publish(_roomId: string, _event: string, _data: any): Promise<void>;
+    subscribe(_roomId: string, _handler: (event: string, data: any) => void): Promise<() => void>;
+    publishMembership(_roomId: string, _action: 'join' | 'leave', _componentId: string): Promise<void>;
+    publishStateChange(_roomId: string, _updates: any): Promise<void>;
+}
+
 type LiveLogCategory = 'lifecycle' | 'messages' | 'state' | 'performance' | 'rooms' | 'websocket';
 type LiveLogConfig = boolean | readonly LiveLogCategory[];
 /**
@@ -1397,4 +1665,4 @@ interface UseTypedLiveComponentReturn<T extends LiveComponent<any>> {
     };
 }
 
-export { ANONYMOUS_CONTEXT, type ActionNames, type ActionPayload, type ActionReturn, type ActiveUpload, AnonymousContext, AuthenticatedContext, type BinaryChunkHeader, type BroadcastMessage, type ComponentDefinition, type ComponentMetadata, type ComponentMetrics, type ComponentPerformanceMetrics, ComponentRegistry, type ComponentSnapshot, type ComponentState, type ConnectionConfig, type ConnectionHealth, type ConnectionMetrics, ConnectionRateLimiter, DEFAULT_CHUNK_SIZE, DEFAULT_WS_PATH, type DebugEvent, type DebugEventType, type DebugSnapshot, type DebugWsMessage, type EventHandler, type ExtractActions, type FileChunkData, type FileUploadChunkMessage, type FileUploadCompleteMessage, type FileUploadCompleteResponse, type FileUploadConfig, FileUploadManager, type FileUploadProgressResponse, type FileUploadStartMessage, type FluxStackWSData, type FluxStackWebSocket, type GenericWebSocket, type HttpRequest, type HttpResponse, type HttpRouteDefinition, type HybridComponentOptions, type HybridState, type InferComponentState, type InferPrivateState, type LiveActionAuth, type LiveActionAuthMap, type LiveAuthContext, type LiveAuthCredentials, LiveAuthManager, type LiveAuthProvider, type LiveAuthResult, type LiveAuthUser, LiveComponent, type LiveComponentAuth, type LiveComponentContext, type LiveComponentInstance, LiveDebugger, type LiveLogCategory, type LiveLogConfig, type LiveMessage, LiveRoomManager, LiveServer, type LiveServerOptions, type LiveTransport, type LiveWSData, PROTOCOL_VERSION, type PerformanceAlert, type PerformanceConfig, PerformanceMonitor, RateLimiterRegistry, RoomEventBus, type RoomInfo, type RoomMessage, type RoomStateData, RoomStateManager, type RoomSubscription, type ServerRoomHandle, type ServerRoomProxy, type SignedState, type StateMigration, type StateSignatureConfig, StateSignatureManager, type TypedCall, type TypedCallAndWait, type TypedSetValue, type UseTypedLiveComponentReturn, type WebSocketConfig, WebSocketConnectionManager, type WebSocketMessage, type WebSocketResponse, createTypedRoomEventBus, createTypedRoomState, decodeBinaryChunk, encodeBinaryChunk, getLiveComponentContext, liveLog, liveWarn, registerComponentLogging, setLiveComponentContext, unregisterComponentLogging };
+export { ANONYMOUS_CONTEXT, type ActionNames, type ActionPayload, type ActionReturn, type ActiveUpload, AnonymousContext, AuthenticatedContext, type BinaryChunkHeader, type BroadcastMessage, type ClusterActionRequest, type ClusterActionResponse, type ClusterComponentState, type ClusterDeltaHandler, type ClusterSingletonClaim, type ClusterSingletonOwner, type ComponentDefinition, type ComponentMetadata, type ComponentMetrics, type ComponentPerformanceMetrics, ComponentRegistry, type ComponentSnapshot, type ComponentState, type ConnectionConfig, type ConnectionHealth, type ConnectionMetrics, ConnectionRateLimiter, DEFAULT_CHUNK_SIZE, DEFAULT_WS_PATH, type DebugEvent, type DebugEventType, type DebugSnapshot, type DebugWsMessage, EMIT_OVERRIDE_KEY, type EventHandler, type ExtractActions, type FileChunkData, type FileUploadChunkMessage, type FileUploadCompleteMessage, type FileUploadCompleteResponse, type FileUploadConfig, FileUploadManager, type FileUploadProgressResponse, type FileUploadStartMessage, type FluxStackWSData, type FluxStackWebSocket, type GenericWebSocket, type HttpRequest, type HttpResponse, type HttpRouteDefinition, type HybridComponentOptions, type HybridState, type IClusterAdapter, type IRoomPubSubAdapter, type IRoomStorageAdapter, InMemoryRoomAdapter, type InferComponentState, type InferPrivateState, type LiveActionAuth, type LiveActionAuthMap, type LiveAuthContext, type LiveAuthCredentials, LiveAuthManager, type LiveAuthProvider, type LiveAuthResult, type LiveAuthUser, LiveComponent, type LiveComponentAuth, type LiveComponentContext, type LiveComponentInstance, LiveDebugger, type LiveLogCategory, type LiveLogConfig, type LiveMessage, LiveRoomManager, LiveServer, type LiveServerOptions, type LiveTransport, type LiveWSData, PROTOCOL_VERSION, type PerformanceAlert, type PerformanceConfig, PerformanceMonitor, RateLimiterRegistry, RoomEventBus, type RoomInfo, type RoomMessage, type RoomStateData, RoomStateManager, type RoomSubscription, type ServerRoomHandle, type ServerRoomProxy, type SignedState, type StateMigration, type StateSignatureConfig, StateSignatureManager, type TypedCall, type TypedCallAndWait, type TypedSetValue, type UseTypedLiveComponentReturn, type WebSocketConfig, WebSocketConnectionManager, type WebSocketMessage, type WebSocketResponse, createTypedRoomEventBus, createTypedRoomState, decodeBinaryChunk, encodeBinaryChunk, getLiveComponentContext, liveLog, liveWarn, queueWsMessage, registerComponentLogging, sendImmediate, setLiveComponentContext, unregisterComponentLogging };