@fluxstack/live 0.1.0 → 0.3.0

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,31 +252,319 @@ 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>;
+}
+
+interface LiveRoomManagerInterface {
+    joinRoom<TState = any>(componentId: string, roomId: string, ws: any, initialState?: TState, options?: {
+        deepDiff?: boolean;
+        deepDiffDepth?: number;
+        serverOnlyState?: boolean;
+    }, joinContext?: {
+        userId?: string;
+        payload?: any;
+    }): {
+        state: TState;
+        rejected?: false;
+    } | {
+        rejected: true;
+        reason: string;
+    };
+    leaveRoom(componentId: string, roomId: string, leaveReason?: 'leave' | 'disconnect' | 'cleanup'): void;
+    cleanupComponent(componentId: string): void;
+    emitToRoom(roomId: string, event: string, data: any, excludeComponentId?: string): number;
+    setRoomState(roomId: string, updates: any, excludeComponentId?: string): void;
+    getRoomState<TState = any>(roomId: string): TState;
+    isInRoom(componentId: string, roomId: string): boolean;
+    getComponentRooms(componentId: string): string[];
+    getMemberCount?(roomId: string): number;
+    getRoomInstance?(roomId: string): LiveRoom<any, any, any> | undefined;
+    getStats(): any;
+}
+interface LiveComponentContext {
+    roomEvents: RoomEventBus;
+    roomManager: LiveRoomManagerInterface;
+}
+/**
+ * Set the global Live Component context.
+ * Called once by LiveServer.start() before any components are mounted.
+ */
+declare function setLiveComponentContext(ctx: LiveComponentContext): void;
+/**
+ * Get the global Live Component context.
+ * Throws if LiveServer.start() hasn't been called yet.
+ */
+declare function getLiveComponentContext(): LiveComponentContext;
+
+declare const BINARY_ROOM_EVENT = 2;
+declare const BINARY_ROOM_STATE = 3;
+interface RoomCodec {
+    encode(data: unknown): Uint8Array;
+    decode(buf: Uint8Array): unknown;
+}
+declare const msgpackCodec: RoomCodec;
+declare const jsonCodec: RoomCodec;
+type RoomCodecOption = 'msgpack' | 'json' | RoomCodec;
+declare function resolveCodec(option?: RoomCodecOption): RoomCodec;
+/**
+ * Build a binary room frame.
+ * Format: [frameType:u8][compIdLen:u8][compId:utf8][roomIdLen:u8][roomId:utf8][eventLen:u16BE][event:utf8][payload]
+ */
+declare function buildRoomFrame(frameType: number, componentId: string, roomId: string, event: string, payload: Uint8Array): Uint8Array;
+/**
+ * Build frame tail (roomId + event + payload) that is shared across all members.
+ * Per-member: prepend [frameType:u8][compIdLen:u8][compId:utf8].
+ */
+declare function buildRoomFrameTail(roomId: string, event: string, payload: Uint8Array): Uint8Array;
+/**
+ * Prepend per-member header to a shared tail.
+ * Header: [frameType:u8][compIdLen:u8][compId:utf8]
+ */
+declare function prependMemberHeader(frameType: number, componentId: string, tail: Uint8Array): Uint8Array;
+/**
+ * Parse a binary room frame header (client-side).
+ * Returns parsed fields and the payload offset.
+ */
+declare function parseRoomFrame(buf: Uint8Array): {
+    frameType: number;
+    componentId: string;
+    roomId: string;
+    event: string;
+    payload: Uint8Array;
+} | null;
+
+interface RoomJoinContext {
+    componentId: string;
+    userId?: string;
+    payload?: any;
+}
+interface RoomLeaveContext {
+    componentId: string;
+    userId?: string;
+    reason: 'leave' | 'disconnect' | 'cleanup';
+}
+interface RoomEventContext {
+    componentId: string;
+    userId?: string;
+}
+interface LiveRoomOptions {
+    /** Enable deep diff for room state. Default: true */
+    deepDiff?: boolean;
+    /** Max recursion depth for deep diff. Default: 3 */
+    deepDiffDepth?: number;
+    /** Max number of members allowed. Undefined = unlimited */
+    maxMembers?: number;
+    /**
+     * Wire codec for room messages. Default: 'msgpack' (binary).
+     * - 'msgpack' — Built-in MessagePack encoder (zero deps, ~30% smaller, ~2-3x faster)
+     * - 'json' — Standard JSON (text-based, larger but human-readable)
+     * - Custom RoomCodec object with encode/decode methods
+     */
+    codec?: RoomCodecOption;
+}
+/**
+ * Base class for typed rooms with lifecycle hooks and public/private state.
+ *
+ * @typeParam TState - Public state synced to all connected clients
+ * @typeParam TMeta - Private server-only metadata (never broadcasted)
+ * @typeParam TEvents - Event map for typed emit/on
+ */
+declare abstract class LiveRoom<TState extends Record<string, any> = Record<string, any>, TMeta extends Record<string, any> = Record<string, any>, TEvents extends Record<string, any> = Record<string, any>> {
+    /** Unique room type name. Used as prefix in compound room IDs (e.g. "chat:lobby"). */
+    static roomName: string;
+    /** Initial public state template. Cloned per room instance. */
+    static defaultState: Record<string, any>;
+    /** Initial private metadata template. Cloned per room instance. */
+    static defaultMeta: Record<string, any>;
+    /** Room-level options */
+    static $options?: LiveRoomOptions;
+    /** The unique room instance identifier (e.g. "chat:lobby") */
+    readonly id: string;
+    /** Public state — synced to all connected clients via setState(). */
+    state: TState;
+    /** Private metadata — NEVER leaves the server. Mutate directly. */
+    meta: TMeta;
+    /** @internal Type brand for client-side event inference.
+     * No runtime value. Usage: `$room<CounterRoom>('id').on(...)` */
+    readonly $events: TEvents;
+    /** @internal Reference to the room manager for broadcasting */
+    protected readonly _manager: LiveRoomManagerInterface;
+    constructor(id: string, manager: LiveRoomManagerInterface);
+    /**
+     * Update public state and broadcast changes to all room members.
+     * Uses deep diff by default — only changed fields are sent over the wire.
+     */
+    setState(updates: Partial<TState>): void;
+    /**
+     * Emit a typed event to all members in this room.
+     * @returns Number of members notified
+     */
+    emit<K extends keyof TEvents & string>(event: K, data: TEvents[K]): number;
+    /** Get current member count */
+    get memberCount(): number;
+    /**
+     * Called when a component attempts to join this room.
+     * Return false to reject the join.
+     */
+    onJoin(_ctx: RoomJoinContext): void | false | Promise<void | false>;
+    /**
+     * Called after a component leaves this room.
+     */
+    onLeave(_ctx: RoomLeaveContext): void | Promise<void>;
+    /**
+     * Called when an event is emitted to this room.
+     * Can intercept/validate events before broadcasting.
+     */
+    onEvent(_event: string, _data: any, _ctx: RoomEventContext): void | Promise<void>;
+    /**
+     * Called once when the room is first created (first member joins).
+     */
+    onCreate(): void | Promise<void>;
+    /**
+     * Called when the last member leaves and the room is about to be destroyed.
+     * Return false to keep the room alive (e.g., persist state).
+     */
+    onDestroy(): void | false | Promise<void | false>;
+}
+/** Extract the public state type from a LiveRoom subclass */
+type InferRoomState<R> = R extends LiveRoom<infer S, any, any> ? S : Record<string, any>;
+/** Extract the private meta type from a LiveRoom subclass */
+type InferRoomMeta<R> = R extends LiveRoom<any, infer M, any> ? M : Record<string, any>;
+/** Extract the events type from a LiveRoom subclass */
+type InferRoomEvents<R> = R extends LiveRoom<any, any, infer E> ? E : Record<string, any>;
+/** LiveRoom class constructor type */
+type LiveRoomClass<R extends LiveRoom = LiveRoom> = {
+    new (id: string, manager: LiveRoomManagerInterface): R;
+    roomName: string;
+    defaultState: Record<string, any>;
+    defaultMeta: Record<string, any>;
+    $options?: LiveRoomOptions;
+};
+
+declare class RoomRegistry {
+    private rooms;
+    /**
+     * Register a LiveRoom subclass.
+     * @throws If the class doesn't define a static roomName
+     */
+    register(roomClass: LiveRoomClass): void;
+    /**
+     * Get a registered room class by name.
+     */
+    get(name: string): LiveRoomClass | undefined;
+    /**
+     * Check if a room class is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * Resolve a compound room ID (e.g. "chat:lobby") to its registered class.
+     * Returns undefined if the prefix doesn't match any registered room.
+     */
+    resolveFromId(roomId: string): LiveRoomClass | undefined;
+    /**
+     * Get all registered room names.
+     */
+    getRegisteredNames(): string[];
+    /**
+     * Check if a value is a LiveRoom subclass.
+     */
+    static isLiveRoomClass(cls: unknown): cls is LiveRoomClass;
+}
+
 declare class LiveRoomManager {
     private roomEvents;
+    private pubsub?;
     private rooms;
     private componentRooms;
-    constructor(roomEvents: RoomEventBus);
+    /** Room registry for LiveRoom class lookup. Set by LiveServer. */
+    roomRegistry?: RoomRegistry;
+    /**
+     * @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
+     * Component joins a room.
+     * @param options.deepDiff - Enable/disable deep diff for this room's state. Default: true
+     * @param joinContext - Optional context for LiveRoom lifecycle hooks (userId, payload)
      */
-    joinRoom<TState = any>(componentId: string, roomId: string, ws: GenericWebSocket, initialState?: TState): {
+    joinRoom<TState = any>(componentId: string, roomId: string, ws: GenericWebSocket, initialState?: TState, options?: {
+        deepDiff?: boolean;
+        deepDiffDepth?: number;
+        serverOnlyState?: boolean;
+    }, joinContext?: {
+        userId?: string;
+        payload?: any;
+    }): {
         state: TState;
+        rejected?: false;
+    } | {
+        rejected: true;
+        reason: string;
     };
     /**
      * Component leaves a room
+     * @param leaveReason - Why the component is leaving. Default: 'leave'
      */
-    leaveRoom(componentId: string, roomId: string): void;
+    leaveRoom(componentId: string, roomId: string, leaveReason?: 'leave' | 'disconnect' | 'cleanup'): void;
     /**
-     * Component disconnects - leave all rooms
+     * Component disconnects - leave all rooms.
+     * Batches removals: calls onLeave hooks, removes member from all rooms,
+     * then sends leave notifications in bulk.
      */
     cleanupComponent(componentId: string): void;
     /**
-     * Emit event to all members in a room
+     * Emit event to all members in a room.
+     * For LiveRoom-backed rooms, calls onEvent() hook before broadcasting.
      */
     emitToRoom(roomId: string, event: string, data: any, excludeComponentId?: string): number;
     /**
-     * Update room state
+     * Update room state.
+     * When deepDiff is enabled (default), deep-diffs plain objects to send only changed fields.
+     * When disabled, uses shallow diff (reference equality) like classic behavior.
      */
     setRoomState(roomId: string, updates: any, excludeComponentId?: string): void;
     /**
@@ -278,17 +572,36 @@ declare class LiveRoomManager {
      */
     getRoomState<TState = any>(roomId: string): TState;
     /**
-     * Broadcast to all members in a room
+     * Broadcast to all members in a room.
+     *
+     * When the room has a binary codec (LiveRoom-backed), builds a binary frame
+     * once (encode payload + frame tail), then prepends per-member componentId header.
+     *
+     * When no codec (legacy rooms), uses JSON with serialize-once optimization:
+     * builds the JSON string template once, then inserts each member's componentId.
      */
     private broadcastToRoom;
     /**
      * Check if component is in a room
      */
     isInRoom(componentId: string, roomId: string): boolean;
+    /**
+     * Check if room state is server-only (no client writes)
+     */
+    isServerOnlyState(roomId: string): boolean;
     /**
      * Get rooms for a component
      */
     getComponentRooms(componentId: string): string[];
+    /**
+     * Get member count for a room
+     */
+    getMemberCount(roomId: string): number;
+    /**
+     * Get the LiveRoom instance for a room (if backed by a typed room class).
+     * Used by ComponentRoomProxy to expose custom methods.
+     */
+    getRoomInstance(roomId: string): LiveRoom<any, any, any> | undefined;
     /**
      * Get statistics
      */
@@ -302,80 +615,6 @@ declare class LiveRoomManager {
     };
 }
 
-type DebugEventType = 'COMPONENT_MOUNT' | 'COMPONENT_UNMOUNT' | 'COMPONENT_REHYDRATE' | 'STATE_CHANGE' | 'ACTION_CALL' | 'ACTION_RESULT' | 'ACTION_ERROR' | 'ROOM_JOIN' | 'ROOM_LEAVE' | 'ROOM_EMIT' | 'ROOM_EVENT_RECEIVED' | 'WS_CONNECT' | 'WS_DISCONNECT' | 'ERROR' | 'LOG';
-interface DebugEvent {
-    id: string;
-    timestamp: number;
-    type: DebugEventType;
-    componentId: string | null;
-    componentName: string | null;
-    data: Record<string, unknown>;
-}
-interface ComponentSnapshot {
-    componentId: string;
-    componentName: string;
-    /** Developer-defined label for easier identification in the debugger */
-    debugLabel?: string;
-    state: Record<string, unknown>;
-    rooms: string[];
-    mountedAt: number;
-    lastActivity: number;
-    actionCount: number;
-    stateChangeCount: number;
-    errorCount: number;
-}
-interface DebugSnapshot {
-    components: ComponentSnapshot[];
-    connections: number;
-    uptime: number;
-    totalEvents: number;
-}
-interface DebugWsMessage {
-    type: 'DEBUG_EVENT' | 'DEBUG_SNAPSHOT' | 'DEBUG_WELCOME' | 'DEBUG_DISABLED';
-    event?: DebugEvent;
-    snapshot?: DebugSnapshot;
-    enabled?: boolean;
-    timestamp: number;
-}
-declare class LiveDebugger {
-    private events;
-    private componentSnapshots;
-    private debugClients;
-    private _enabled;
-    private startTime;
-    private eventCounter;
-    constructor(enabled?: boolean);
-    get enabled(): boolean;
-    set enabled(value: boolean);
-    emit(type: DebugEventType | string, componentId: string | null, componentName: string | null, data?: Record<string, unknown>): void;
-    trackComponentMount(componentId: string, componentName: string, initialState: Record<string, unknown>, room?: string, debugLabel?: string): void;
-    trackComponentUnmount(componentId: string): void;
-    trackStateChange(componentId: string, delta: Record<string, unknown>, fullState: Record<string, unknown>, source?: 'proxy' | 'setState' | 'rehydrate'): void;
-    trackActionCall(componentId: string, action: string, payload: unknown): void;
-    trackActionResult(componentId: string, action: string, result: unknown, duration: number): void;
-    trackActionError(componentId: string, action: string, error: string, duration: number): void;
-    trackRoomJoin(componentId: string, roomId: string): void;
-    trackRoomLeave(componentId: string, roomId: string): void;
-    trackRoomEmit(componentId: string, roomId: string, event: string, data: unknown): void;
-    trackConnection(connectionId: string): void;
-    trackDisconnection(connectionId: string, componentCount: number): void;
-    trackError(componentId: string | null, error: string, context?: Record<string, unknown>): void;
-    registerDebugClient(ws: GenericWebSocket): void;
-    unregisterDebugClient(ws: GenericWebSocket): void;
-    getSnapshot(): DebugSnapshot;
-    getComponentState(componentId: string): ComponentSnapshot | null;
-    getEvents(filter?: {
-        componentId?: string;
-        type?: DebugEventType;
-        limit?: number;
-    }): DebugEvent[];
-    clearEvents(): void;
-    private broadcastEvent;
-    private sanitizeData;
-    private sanitizeState;
-    private updateSnapshot;
-}
-
 declare class LiveAuthManager {
     private providers;
     private defaultProviderName?;
@@ -446,33 +685,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 +736,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 +1103,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?;
@@ -873,45 +1131,19 @@ declare class WebSocketConnectionManager extends EventEmitter {
     shutdown(): void;
 }
 
-interface LiveRoomManagerInterface {
-    joinRoom<TState = any>(componentId: string, roomId: string, ws: any, initialState?: TState): {
-        state: TState;
-    };
-    leaveRoom(componentId: string, roomId: string): void;
-    cleanupComponent(componentId: string): void;
-    emitToRoom(roomId: string, event: string, data: any, excludeComponentId?: string): number;
-    setRoomState(roomId: string, updates: any, excludeComponentId?: string): void;
-    getRoomState<TState = any>(roomId: string): TState;
-    isInRoom(componentId: string, roomId: string): boolean;
-    getComponentRooms(componentId: string): string[];
-    getStats(): any;
-}
-interface LiveDebuggerInterface {
-    enabled: boolean;
-    trackStateChange(componentId: string, delta: Record<string, unknown>, fullState: Record<string, unknown>, source?: string): void;
-    trackActionCall(componentId: string, action: string, payload: unknown): void;
-    trackActionResult(componentId: string, action: string, result: unknown, duration: number): void;
-    trackActionError(componentId: string, action: string, error: string, duration: number): void;
-    trackRoomEmit(componentId: string, roomId: string, event: string, data: unknown): void;
-}
-interface LiveComponentContext {
-    roomEvents: RoomEventBus;
-    roomManager: LiveRoomManagerInterface;
-    debugger?: LiveDebuggerInterface;
-}
-/**
- * Set the global Live Component context.
- * Called once by LiveServer.start() before any components are mounted.
- */
-declare function setLiveComponentContext(ctx: LiveComponentContext): void;
-/**
- * Get the global Live Component context.
- * Throws if LiveServer.start() hasn't been called yet.
- */
-declare function getLiveComponentContext(): LiveComponentContext;
-
-/** @internal Symbol key for singleton emit override */
+/** Symbol key for singleton emit override */
 declare const EMIT_OVERRIDE_KEY: unique symbol;
+
+interface ComponentOptions {
+    /** Enable deep diff for plain objects in setState(). Default: false */
+    deepDiff?: boolean;
+    /** Enable deep diff for room state updates. Default: true */
+    roomDeepDiff?: boolean;
+    /** Max recursion depth for deep diff (component + room). Default: 3 */
+    deepDiffDepth?: number;
+    /** When true, room state can only be set from server-side code. Client ROOM_STATE_SET is rejected. Default: false */
+    serverOnlyRoomState?: boolean;
+}
 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 +1165,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.
      */
@@ -942,8 +1203,14 @@ declare abstract class LiveComponent<TState = ComponentState, TPrivate extends R
      * All clients share the same state.
      */
     static singleton?: boolean;
+    /**
+     * Component behavior options.
+     *
+     * @example
+     * static $options = { deepDiff: true }
+     */
+    static $options?: ComponentOptions;
     readonly id: string;
-    private _state;
     state: TState;
     protected ws: GenericWebSocket;
     room?: string;
@@ -951,27 +1218,53 @@ 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
+     * Unified room accessor.
+     *
+     * Usage:
+     * - `this.$room` — default room handle (legacy)
+     * - `this.$room('roomId')` — untyped room handle (legacy)
+     * - `this.$room(ChatRoom, 'lobby')` — typed handle with custom methods
+     */
+    get $room(): ServerRoomProxy & {
+        <R extends LiveRoom<any, any, any>>(roomClass: LiveRoomClass<R>, instanceId: string): R & {
+            readonly id: string;
+            join: (payload?: any) => {
+                rejected?: false;
+            } | {
+                rejected: true;
+                reason: string;
+            };
+            leave: () => void;
+            emit: R['emit'];
+            on: <K extends string>(event: K, handler: (data: any) => void) => () => void;
+            setState: (updates: Partial<R['state']>) => void;
+            readonly memberCount: number;
+        };
+    };
+    /**
+     * 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 +1278,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;
@@ -1038,9 +1419,9 @@ interface StateMigration {
 }
 interface ComponentRegistryDeps {
     authManager: LiveAuthManager;
-    debugger: LiveDebugger;
     stateSignature: StateSignatureManager;
     performanceMonitor: PerformanceMonitor;
+    cluster?: IClusterAdapter;
 }
 declare class ComponentRegistry {
     private components;
@@ -1051,11 +1432,14 @@ 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 +1469,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 +1496,13 @@ declare class ComponentRegistry {
                 connections: number;
             };
         };
+        remoteSingletons: {
+            [k: string]: {
+                componentId: string;
+                ownerInstanceId: string;
+                connections: number;
+            };
+        };
         roomDetails: {
             [k: string]: number;
         };
@@ -1176,11 +1569,25 @@ 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;
+    /** LiveRoom classes to register. These define typed rooms with lifecycle hooks. */
+    rooms?: LiveRoomClass[];
 }
 declare class LiveServer {
     readonly roomEvents: RoomEventBus;
     readonly roomManager: LiveRoomManager;
-    readonly debugger: LiveDebugger;
     readonly authManager: LiveAuthManager;
     readonly stateSignature: StateSignatureManager;
     readonly performanceMonitor: PerformanceMonitor;
@@ -1188,6 +1595,7 @@ declare class LiveServer {
     readonly connectionManager: WebSocketConnectionManager;
     readonly registry: ComponentRegistry;
     readonly rateLimiter: RateLimiterRegistry;
+    readonly roomRegistry: RoomRegistry;
     private transport;
     private options;
     constructor(options: LiveServerOptions);
@@ -1195,6 +1603,11 @@ declare class LiveServer {
      * Register an auth provider.
      */
     useAuth(provider: LiveAuthProvider): this;
+    /**
+     * Register a LiveRoom class.
+     * Can be called before start() to register room types dynamically.
+     */
+    useRoom(roomClass: LiveRoomClass): this;
     /**
      * Start the LiveServer: register WS + HTTP handlers on the transport.
      */
@@ -1211,6 +1624,32 @@ 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 binary message immediately (bypass batching).
+ * Binary frames are never batched — they are self-framing.
+ */
+declare function sendBinaryImmediate(ws: GenericWebSocket, data: Uint8Array): 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 +1753,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[];
 /**
@@ -1326,12 +1785,10 @@ declare function registerComponentLogging(componentId: string, config: LiveLogCo
 declare function unregisterComponentLogging(componentId: string): void;
 /**
  * Log a message gated by the component's logging config.
- * Always forwarded to the Live Debugger when active.
  */
 declare function liveLog(category: LiveLogCategory, componentId: string | null, message: string, ...args: unknown[]): void;
 /**
  * Warn-level log gated by config.
- * Always forwarded to the Live Debugger when active.
  */
 declare function liveWarn(category: LiveLogCategory, componentId: string | null, message: string, ...args: unknown[]): void;
 
@@ -1397,4 +1854,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, BINARY_ROOM_EVENT, BINARY_ROOM_STATE, 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 ComponentState, type ConnectionConfig, type ConnectionHealth, type ConnectionMetrics, ConnectionRateLimiter, DEFAULT_CHUNK_SIZE, DEFAULT_WS_PATH, 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 InferRoomEvents, type InferRoomMeta, type InferRoomState, type LiveActionAuth, type LiveActionAuthMap, type LiveAuthContext, type LiveAuthCredentials, LiveAuthManager, type LiveAuthProvider, type LiveAuthResult, type LiveAuthUser, LiveComponent, type LiveComponentAuth, type LiveComponentContext, type LiveComponentInstance, type LiveLogCategory, type LiveLogConfig, type LiveMessage, LiveRoom, type LiveRoomClass, LiveRoomManager, type LiveRoomManagerInterface, type LiveRoomOptions, LiveServer, type LiveServerOptions, type LiveTransport, type LiveWSData, PROTOCOL_VERSION, type PerformanceAlert, type PerformanceConfig, PerformanceMonitor, RateLimiterRegistry, type RoomCodec, type RoomCodecOption, RoomEventBus, type RoomEventContext, type RoomInfo, type RoomJoinContext, type RoomLeaveContext, type RoomMessage, RoomRegistry, 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, buildRoomFrame, buildRoomFrameTail, createTypedRoomEventBus, createTypedRoomState, decodeBinaryChunk, encodeBinaryChunk, getLiveComponentContext, jsonCodec, liveLog, liveWarn, msgpackCodec, parseRoomFrame, prependMemberHeader, queueWsMessage, registerComponentLogging, resolveCodec, sendBinaryImmediate, sendImmediate, setLiveComponentContext, unregisterComponentLogging };