p2p-lockstep-kit-session 0.1.2 → 0.1.4

package/dist/session/index.d.ts

@@ -0,0 +1,363 @@
+import { NetworkClient } from 'p2p-lockstep-kit-network';
+
+type SessionMessageType = 'READY' | 'START' | 'MOVE' | 'UNDO' | 'RESTART' | 'APPROVE' | 'REJECT' | 'REJOIN' | 'SYNC_REQUEST' | 'SYNC_STATE' | 'OFFLINE' | 'ONLINE' | 'GAME_OVER';
+type SessionMessage = {
+    type: SessionMessageType;
+    from?: string;
+    seq?: number;
+    sid?: string;
+    turn?: number;
+    stateHash?: string;
+    payload?: any;
+};
+
+type CommandOrigin = 'local' | 'remote';
+type BusMessageType = SessionMessageType | 'OFFLINE' | 'ONLINE' | 'GAME_OVER';
+type BusMessage = Omit<SessionMessage, 'type'> & {
+    type: BusMessageType;
+};
+type CommandListener = (message: BusMessage) => Promise<void> | void;
+declare class CommandBus {
+    private handlers;
+    private processingQueue;
+    emit(type: BusMessageType, payload?: unknown, from?: CommandOrigin): void;
+    register(type: BusMessageType, handler: CommandListener): void;
+    dispatch(message: BusMessage): void;
+}
+
+/**
+ * Network client wrapper that bridges NetworkClient with CommandBus
+ * Handles message encoding/decoding and connection state monitoring
+ */
+declare class NetClient {
+    private readonly client;
+    private readonly bus;
+    private localPeerId;
+    private remotePeerId;
+    private isConnected;
+    private connectionChangeListener;
+    private mediaStateListener;
+    constructor(client: NetworkClient, bus: CommandBus, peerId: string | null);
+    /**
+     * Send a message to the remote peer
+     * Drops message if not connected and logs warning
+     */
+    send(message: SessionMessage): void;
+    /**
+     * Update local and remote peer IDs
+     */
+    setPeerIds(ids: {
+        local?: string | null;
+        remote?: string | null;
+    }): void;
+    /**
+     * Get current peer IDs
+     */
+    getPeerIds(): {
+        local: string | null;
+        remote: string | null;
+    };
+    /**
+     * Check if currently connected to peer
+     */
+    getIsConnected(): boolean;
+    /**
+     * Monitor connection state changes
+     * @param handler Called when connection state changes (true=connected, false=disconnected)
+     */
+    onConnectionChange(handler: (isConnected: boolean) => void): void;
+    /**
+     * Monitor remote media stream state changes
+     * @param handler Called when remote media becomes available or unavailable
+     */
+    onMediaStateChange(handler: (active: boolean) => void): void;
+}
+
+type SessionState = 'idle' | 'ready' | 'could_start' | 'turn' | 'remote_turn' | 'approving' | 'waiting_approval' | 'syncing' | 'offline';
+type SessionEvent = 'REMOTE_READY' | 'READY' | 'START' | 'REMOTE_START' | 'MOVE' | 'REMOTE_MOVE' | 'UNDO' | 'REMOTE_UNDO' | 'RESTART' | 'REMOTE_RESTART' | 'APPROVE' | 'REJECT' | 'GAME_OVER' | 'REJOIN' | 'SYNC' | 'SYNC_COMPLETE' | 'OFFLINE' | 'ONLINE';
+
+interface GameStateSnapshot {
+    localState: SessionState;
+    remoteState: SessionState;
+    turn: number;
+    history: TurnEntry[];
+    lastStart: PlayerLabel | null;
+    pendingAction: 'undo' | 'restart' | null;
+    connected: boolean;
+}
+interface GameEvent {
+    type: 'READY' | 'START' | 'MOVE' | 'GAME_OVER' | 'UNDO' | 'RESTART' | 'OFFLINE' | 'ONLINE' | 'SYNC' | 'ERROR';
+    payload?: any;
+    from?: 'local' | 'remote';
+    timestamp?: number;
+}
+interface IGameObserver {
+    onStateChange(snapshot: GameStateSnapshot): void;
+    onGameEvent(event: GameEvent): void;
+    onConnectionChange?(connected: boolean): void;
+    onError?(error: {
+        message: string;
+        context?: any;
+    }): void;
+}
+interface IStateObserver {
+    onStateChanged?(): void;
+    onHistoryChanged?(): void;
+    onGameReset?(): void;
+}
+interface IGamePlugin {
+    validateMove(move: unknown, gameState: GameState): ValidationResult;
+    checkWin(gameState: GameState, history: TurnEntry[]): PlayerLabel | null;
+    initialize?(): void;
+    cleanup?(): void;
+}
+interface ValidationResult {
+    valid: boolean;
+    reason?: string;
+}
+interface GameState {
+    history: TurnEntry[];
+    localState: 'turn' | 'remote_turn' | string;
+    remoteState: 'turn' | 'remote_turn' | string;
+    turn: number;
+    lastStart: PlayerLabel | null;
+}
+declare class DefaultGamePlugin implements IGamePlugin {
+    validateMove(): ValidationResult;
+    checkWin(): PlayerLabel | null;
+}
+declare class StateObserverManager {
+    private observers;
+    subscribe(observer: IStateObserver): void;
+    unsubscribe(observer: IStateObserver): void;
+    notifyStateChanged(): void;
+    notifyHistoryChanged(): void;
+    notifyGameReset(): void;
+}
+declare class GameStateObserver {
+    private observers;
+    private currentSnapshot;
+    subscribe(observer: IGameObserver): () => void;
+    unsubscribe(observer: IGameObserver): void;
+    notifyStateChange(snapshot: GameStateSnapshot): void;
+    notifyGameEvent(event: GameEvent): void;
+    notifyConnectionChange(connected: boolean): void;
+    notifyError(error: {
+        message: string;
+        context?: any;
+    }): void;
+    getSnapshot(): GameStateSnapshot | null;
+    getObserverCount(): number;
+}
+declare function buildGameStateSnapshot(state: State, connected?: boolean): GameStateSnapshot;
+declare class UINotificationAdapter implements IStateObserver {
+    private stateRef;
+    private uiObserver;
+    private getConnected;
+    private lastNotificationTime;
+    private notificationThrottleMs;
+    constructor(stateRef: State, uiObserver: GameStateObserver, getConnected?: () => boolean);
+    onStateChanged(): void;
+    onHistoryChanged(): void;
+    onGameReset(): void;
+    emitEvent(event: Omit<GameEvent, 'timestamp'>): void;
+}
+
+type TurnEntry = {
+    turn: number;
+    player: 'local' | 'remote';
+    move?: any;
+};
+type PlayerLabel = 'local' | 'remote';
+declare class State {
+    private local;
+    private remote;
+    private readonly localId;
+    private remoteId;
+    private readonly history;
+    private pendingAction;
+    private pendingUndoCount;
+    private resumeTurn;
+    private lastStart;
+    private gamePlugin;
+    private stateObserverManager;
+    constructor(id: string | null, remoteId: string | null);
+    /**
+     * Register an internal observer (like plugin pattern)
+     * Use this to connect State mutations to UI updates
+     */
+    subscribeStateObserver(observer: IStateObserver): void;
+    getId(): string | null;
+    getremoteId(): string | null;
+    setremoteId(id: string): void;
+    getState(player: PlayerLabel): SessionState;
+    getTurnCount(): number;
+    getHistory(): TurnEntry[];
+    replaceHistory(entries: TurnEntry[]): void;
+    clearHistory(): void;
+    pushHistory(entry: TurnEntry): void;
+    popHistory(): TurnEntry | null;
+    canAction(player: PlayerLabel, action: SessionEvent): boolean;
+    /**
+     * Dispatch an action and automatically determine target state if unique
+     * Only use explicit 'to' parameter for ambiguous transitions (APPROVE, REJECT, etc.)
+     *
+     * For most actions (READY, MOVE, START, etc.), there's only one valid transition,
+     * so we automatically find and apply it.
+     */
+    dispatch(player: PlayerLabel, action: SessionEvent, to?: SessionState): void;
+    setPendingAction(action: 'undo' | 'restart' | null): void;
+    getPendingAction(): "undo" | "restart" | null;
+    setPendingUndoCount(count: 1 | 2 | null): void;
+    getPendingUndoCount(): 1 | 2 | null;
+    setLastStart(player: PlayerLabel | null): void;
+    getLastStart(): PlayerLabel | null;
+    setResumeTurn(player: PlayerLabel | null): void;
+    getResumeTurn(): PlayerLabel | null;
+    private getPlayerFsm;
+    /**
+     * Save game state snapshot for undo/restart operations
+     */
+    private gameSnapshot;
+    saveGameSnapshot(snapshot: unknown): void;
+    getGameSnapshot(): unknown;
+    clearGameSnapshot(): void;
+    /**
+     * Check if there's a pending action (undo/restart)
+     */
+    hasPendingAction(): boolean;
+    /**
+     * Clear all pending states (called after approval/rejection)
+     */
+    clearPendingStates(): void;
+    /**
+     * Initialize undo request with undo count and current turn holder
+     */
+    initializeUndoRequest(undoCount: 1 | 2, resumeTurn: PlayerLabel): void;
+    /**
+     * Initialize restart request with resume turn
+     */
+    initializeRestartRequest(resumeTurn: PlayerLabel): void;
+    /**
+     * Check if pending action is undo
+     */
+    isPendingUndo(): boolean;
+    /**
+     * Check if pending action is restart
+     */
+    isPendingRestart(): boolean;
+    /**
+     * Apply undo by popping history N times
+     */
+    applyUndo(count?: 1 | 2): void;
+    /**
+     * Reset game state to initial (for restart)
+     */
+    resetGame(): void;
+    /**
+     * Save start player for rejoin flow
+     */
+    recordStartPlayer(player: PlayerLabel): void;
+    /**
+     * Get move to undo from history
+     */
+    getLastMove(): TurnEntry | null;
+    /**
+     * Dispatch APPROVE action with automatic target state resolution
+     * Multiple valid transitions exist - use state context to determine target
+     */
+    dispatchApprove(): void;
+    /**
+     * Dispatch REJECT action with automatic target state resolution
+     * Multiple valid transitions exist - use resumeTurn to determine who continues
+     */
+    dispatchReject(): void;
+    /**
+     * Dispatch START action with automatic target state resolution
+     * Determines who plays first based on starter parameter
+     */
+    dispatchStart(firstPlayer: PlayerLabel): void;
+    /**
+     * Dispatch SYNC_COMPLETE with automatic target state resolution
+     * Based on who should have the turn after sync
+     */
+    dispatchSyncComplete(nextPlayer: PlayerLabel): void;
+    /**
+     * Set the game plugin for rule validation and win checking
+     * @param plugin Implementation of IGamePlugin
+     */
+    setGamePlugin(plugin: IGamePlugin): void;
+    /**
+     * Get current game plugin
+     */
+    getGamePlugin(): IGamePlugin;
+    /**
+     * Validate a move using the game plugin
+     * Called by move handler to check if move is legal
+     * @param move The move data to validate
+     * @returns Validation result with reason if invalid
+     */
+    validateMove(move: unknown): ValidationResult;
+    /**
+     * Check if game has ended (someone won)
+     * Called by move handler after move is applied
+     * @returns Winner (local/remote) or null if game continues
+     */
+    checkWin(): PlayerLabel | null;
+    /**
+     * Cleanup when game ends (for plugin to reset internal state)
+     */
+    cleanupGame(): void;
+    /**
+     * Build game state for plugin
+     * @private
+     */
+    private buildGameState;
+}
+
+interface ISessionActions {
+    ready(): void;
+    start(): void;
+    move(data: unknown): void;
+    undo(): void;
+    restart(): void;
+    approve(): void;
+    reject(): void;
+    rejoin(sid: string): void;
+}
+declare class LocalActionsAPI implements ISessionActions {
+    private bus;
+    constructor(bus: CommandBus);
+    ready(): void;
+    start(): void;
+    move(data: unknown): void;
+    undo(): void;
+    restart(): void;
+    approve(): void;
+    reject(): void;
+    rejoin(sid: string): void;
+}
+
+/**
+ * Create a new game session with state management and networking
+ * @param sid Session ID for rejoining (optional)
+ * @param networkClient Custom network client (optional, creates default if not provided)
+ * @returns Session manager with bus, state, observer, net, and send method
+ *
+ * @example
+ * const session = createSession();
+ * // UI automatically updates when state changes - no manual observer calls needed!
+ * session.observer.subscribe(myUIObserver);
+ * session.bus.emit('READY', undefined, 'local');
+ * await session.net.connect(remotePeerId);
+ */
+declare const createSession: (networkClient: NetworkClient, sid?: string) => {
+    bus: CommandBus;
+    state: State;
+    observer: GameStateObserver;
+    net: NetClient;
+    actions: LocalActionsAPI;
+    send: (message: SessionMessage) => void;
+};
+
+export { DefaultGamePlugin, type GameEvent, type GameState, GameStateObserver, type GameStateSnapshot, type IGameObserver, type IGamePlugin, type ISessionActions, type IStateObserver, StateObserverManager, UINotificationAdapter, type ValidationResult, buildGameStateSnapshot, createSession };