@aprovan/patchwork-image-boardgameio 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 zolvery
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,559 @@
+import { Game, StorageAPI, State, LogEntry, Server, CredentialedActionShape, ChatMessage } from 'boardgame.io';
+
+/**
+ * @aprovan/patchwork-image-boardgameio
+ *
+ * Setup function for the Boardgame.io image.
+ * Uses Tailwind Play CDN for runtime CSS generation.
+ */
+interface SetupOptions {
+    darkMode?: boolean | 'system';
+    cssRuntime?: boolean;
+    multiplayer?: boolean;
+}
+declare global {
+    interface Window {
+        tailwind?: {
+            config?: Record<string, unknown>;
+        };
+    }
+}
+declare function setup(container: HTMLElement, options?: SetupOptions): Promise<void>;
+declare function cleanup(container: HTMLElement): void;
+/**
+ * Ensures PeerJS is loaded (can be called directly by mount if needed)
+ */
+declare function ensurePeerJS(): Promise<void>;
+
+/**
+ * Settings Context for boardgame.io widgets
+ *
+ * Provides game settings to board components via React context.
+ * Uses window.React at runtime (preloaded by the compiler).
+ */
+type GameSettings = Record<string, unknown>;
+interface SettingsProviderProps {
+    settings: GameSettings;
+    children: unknown;
+}
+declare function SettingsProvider({ settings, children, }: SettingsProviderProps): unknown;
+/**
+ * Hook to access game settings from within a board component.
+ *
+ * @example
+ * ```tsx
+ * function MyBoard({ G, ctx, moves }: BoardProps) {
+ *   const settings = useSettings<{ difficulty: string }>();
+ *   // ...
+ * }
+ * ```
+ */
+declare function useSettings<T extends GameSettings = GameSettings>(): T;
+
+/**
+ * Bot Manager for boardgame.io widgets
+ *
+ * Centralizes bot execution with support for:
+ * - Multiple strategies (Random, MCTS, Custom)
+ * - Configurable delays with variable timing
+ * - Difficulty presets with mistake rates
+ * - Observable thinking state
+ */
+
+interface BoardgameState {
+    G: unknown;
+    ctx: {
+        currentPlayer: string;
+        gameover?: unknown;
+        turn?: number;
+        phase?: string;
+    };
+}
+type BotStrategy = 'random' | 'mcts' | 'custom';
+type BotDifficulty = 'easy' | 'medium' | 'hard' | 'custom';
+interface DifficultyPreset {
+    strategy: BotStrategy;
+    mctsIterations: number;
+    delay: number;
+    minDelay: number;
+    mistakeRate: number;
+}
+declare const DIFFICULTY_PRESETS: Record<BotDifficulty, DifficultyPreset>;
+interface BotConfig {
+    /** Difficulty preset: 'easy', 'medium', 'hard', or 'custom' */
+    difficulty?: BotDifficulty;
+    /** Bot strategy: 'random' or 'mcts' (overrides difficulty preset) */
+    strategy?: BotStrategy;
+    /** Delay before bot makes move (ms). Default from difficulty. */
+    delay?: number;
+    /** Min delay for variable timing (ms). If set, delay becomes max. */
+    minDelay?: number;
+    /** MCTS iterations (only for strategy: 'mcts'). Default from difficulty. */
+    mctsIterations?: number;
+    /** Chance bot picks suboptimal move (0-1). Default from difficulty. */
+    mistakeRate?: number;
+    /** Custom bot factory (only for strategy: 'custom') */
+    customBot?: () => BotInstance;
+}
+interface ResolvedBotConfig {
+    strategy: BotStrategy;
+    delay: number;
+    minDelay: number;
+    mctsIterations: number;
+    mistakeRate: number;
+    customBot?: () => BotInstance;
+}
+interface BotState {
+    /** Whether a bot is currently "thinking" */
+    isThinking: boolean;
+    /** Which player ID is thinking (null if none) */
+    thinkingPlayer: string | null;
+    /** Estimated time remaining for bot move (ms, if calculable) */
+    estimatedTime?: number;
+}
+interface BotInstance {
+    play(state: BoardgameState, playerID: string): Promise<BotAction | null> | BotAction | null;
+}
+interface BotAction {
+    action?: {
+        payload: {
+            type: string;
+            args: unknown[];
+        };
+    };
+}
+interface EnumeratedMove {
+    move: string;
+    args: unknown[];
+}
+declare global {
+    interface Window {
+        BoardgameAI?: {
+            RandomBot?: new (opts: {
+                game: BoardgameGame;
+                enumerate: (G: unknown, ctx: unknown) => EnumeratedMove[];
+            }) => BotInstance;
+            MCTSBot?: new (opts: {
+                game: BoardgameGame;
+                enumerate: (G: unknown, ctx: unknown) => EnumeratedMove[];
+                iterations?: number;
+                playoutDepth?: number;
+            }) => BotInstance;
+        };
+    }
+}
+/**
+ * Resolves bot configuration from inputs, game-specific overrides, and defaults.
+ *
+ * Resolution order:
+ * 1. Explicit input values (e.g., inputs.mctsIterations)
+ * 2. Game-specific difficulty preset (game.ai.difficulty[level])
+ * 3. Global difficulty preset (DIFFICULTY_PRESETS[level])
+ */
+declare function resolveBotConfig(inputs: Record<string, unknown>, gameAiDifficulty?: Partial<Record<BotDifficulty, Partial<DifficultyPreset>>>): ResolvedBotConfig;
+/**
+ * Computes which player IDs should be controlled by bots.
+ *
+ * Bots fill all slots except the human player's slot.
+ */
+declare function computeBotPlayerIDs(numPlayers: number, botCount: number, humanPlayerID: string): string[];
+declare class BotManager {
+    private game;
+    private config;
+    private bot;
+    private pendingMove;
+    private stateListeners;
+    private currentState;
+    private moveInProgress;
+    constructor(game: BoardgameGame, config: ResolvedBotConfig);
+    private initializeBot;
+    /**
+     * Select a move, potentially with mistakes for easier difficulties.
+     */
+    private selectMove;
+    /**
+     * Check if it's a bot's turn and schedule a move if so.
+     * Call this after every state update.
+     */
+    maybePlayBot(state: BoardgameState, botPlayerIDs: string[], makeMove: (type: string, ...args: unknown[]) => void): Promise<void>;
+    /** Subscribe to bot state changes */
+    subscribe(listener: (state: BotState) => void): () => void;
+    /** Get current bot state */
+    getState(): BotState;
+    private notifyState;
+    private cancelPendingMove;
+    dispose(): void;
+}
+
+/**
+ * Mount helper for boardgame.io widgets
+ *
+ * Handles mounting automatically when widgets export `game` and `app` (or default).
+ * The image detects these exports and creates the mount - widgets don't need to
+ * reference image internals.
+ *
+ * Uses window.React at runtime (preloaded by the compiler).
+ */
+
+/** Multiplayer configuration passed via inputs */
+interface MultiplayerInput {
+    matchID: string;
+    playerID: string;
+    credentials?: string;
+    isHost?: boolean;
+}
+interface GameMountOptions {
+    /** Number of players for the game */
+    numPlayers?: number;
+    /** Default player ID */
+    defaultPlayerID?: string;
+}
+interface BoardgameGame {
+    name?: string;
+    minPlayers?: number;
+    maxPlayers?: number;
+    setup: (context: unknown) => unknown;
+    ai?: {
+        /** Enumerate legal moves for bot players */
+        enumerate: (G: unknown, ctx: unknown) => Array<{
+            move: string;
+            args: unknown[];
+        }>;
+        /** Optional game-specific difficulty presets */
+        difficulty?: Partial<Record<BotDifficulty, Partial<DifficultyPreset>>>;
+    };
+}
+/** Manifest structure for player count */
+interface WidgetManifest {
+    players?: {
+        min?: number;
+        max?: number;
+    };
+    [key: string]: unknown;
+}
+type BoardComponent = (props: any) => unknown;
+declare global {
+    interface Window {
+        BoardgameReact?: {
+            Client: (opts: {
+                game: BoardgameGame;
+                board: BoardComponent;
+                numPlayers?: number;
+                multiplayer?: unknown;
+            }) => any;
+        };
+        BoardgameMultiplayer?: {
+            Local?: () => unknown;
+        };
+        React?: any;
+        ReactDOM?: {
+            createRoot: (el: HTMLElement) => {
+                render: (el: unknown) => void;
+                unmount: () => void;
+            };
+        };
+    }
+}
+/**
+ * Creates a mount function for a boardgame.io widget.
+ *
+ * @param game - The boardgame.io game definition
+ * @param Board - The React board component
+ * @param options - Mount options (numPlayers, defaultPlayerID)
+ * @returns A mount function compatible with the patchwork runtime
+ *
+ * @example
+ * ```tsx
+ * export const game = { name: 'my-game', setup: () => ({}) };
+ * export default function MyBoard({ G, ctx, moves }) { ... }
+ * export const mount = createGameMount(game, MyBoard, { numPlayers: 2 });
+ * ```
+ */
+declare function createGameMount(game: BoardgameGame, Board: BoardComponent, options?: GameMountOptions): (container: HTMLElement, inputs?: GameSettings) => () => void;
+/**
+ * Widget module structure expected by the boardgameio image.
+ * Widgets should export `game` and either `app` or `default`.
+ */
+interface BoardgameWidgetModule {
+    game: BoardgameGame;
+    app?: BoardComponent;
+    default?: BoardComponent;
+}
+/**
+ * Creates a mount function from a widget module's exports.
+ * Called automatically by the runtime when it detects a boardgameio widget.
+ *
+ * @param module - The widget module with game and app/default exports
+ * @param manifest - The widget manifest (for player count settings)
+ * @returns A mount function or null if not a valid boardgameio widget
+ */
+declare function createMountFromExports(module: BoardgameWidgetModule, manifest?: WidgetManifest): ((container: HTMLElement, inputs?: GameSettings) => () => void) | null;
+/**
+ * Injects the mount helpers onto the window for runtime access.
+ * Called during image setup.
+ */
+declare function injectMountHelper(): void;
+/**
+ * Image mount function - handles mounting widgets for the boardgameio image.
+ *
+ * Supports three patterns:
+ * 1. BoardGame.io widgets: exports `game` and `app`/`default`
+ * 2. Custom mount: exports a `mount` function
+ * 3. React component: exports `default` as a React component
+ *
+ * @param module - The widget module exports
+ * @param container - The DOM element to mount into
+ * @param inputs - Props/settings to pass to the widget
+ * @returns A cleanup function to unmount, or void
+ */
+declare function mount(module: Record<string, unknown>, container: HTMLElement, inputs: Record<string, unknown>): Promise<void | (() => void)>;
+
+interface MultiplayerConfig {
+    isMultiplayer: boolean;
+    isHost?: boolean;
+    appId: string;
+    matchID?: string;
+    botCount?: number;
+}
+declare function getMultiplayer(config: MultiplayerConfig, game?: Game): unknown;
+declare function generateMatchID(): string;
+
+declare class P2PDB {
+    private initialState;
+    private state;
+    private log;
+    private metadata;
+    connect(): void;
+    createMatch(matchID: string, opts: StorageAPI.CreateMatchOpts): void;
+    setState(matchID: string, state: State, deltalog?: LogEntry[]): void;
+    setMetadata(matchID: string, metadata: Server.MatchData): void;
+    fetch<O extends StorageAPI.FetchOpts>(matchID: string): StorageAPI.FetchResult<O>;
+    wipe(matchID: string): void;
+    listMatches(): string[];
+}
+
+interface ClientMetadata {
+    playerID: string | null;
+    credentials?: string;
+    message?: string;
+}
+interface Client {
+    metadata: ClientMetadata;
+    send: (data: unknown) => void;
+}
+type ClientAction = {
+    type: 'sync';
+} | {
+    type: 'update';
+    args: [string, State, CredentialedActionShape.Any];
+} | {
+    type: 'chat';
+    args: [string, ChatMessage, string | undefined];
+};
+
+declare function generateCredentials(): string;
+declare function generateKeyPair(): {
+    publicKey: string;
+    privateKey: string;
+};
+
+declare class P2PHost {
+    private clients;
+    private hostClient;
+    private matchID;
+    private db;
+    private game;
+    private numPlayers;
+    private state;
+    constructor({ game, numPlayers, matchID, }: {
+        game: Game;
+        numPlayers?: number;
+        matchID: string;
+    });
+    private persistSession;
+    private createInitialState;
+    registerClient(client: Client): void;
+    registerHostClient(client: Client): void;
+    unregisterClient(client: Client): void;
+    processAction(client: Client, data: ClientAction): void;
+    private syncClient;
+    private filterStateForPlayer;
+    private handleUpdate;
+    private broadcastState;
+    private broadcastChat;
+}
+
+declare global {
+    interface Window {
+        Peer?: new (id?: string, options?: object) => PeerInstance;
+        __peerConfig?: {
+            host?: string;
+            port?: number;
+            path?: string;
+            secure?: boolean;
+            iceServers?: RTCIceServer[];
+        };
+    }
+}
+interface DataConnection {
+    on(event: 'data' | 'open' | 'close' | 'error', handler: (data?: unknown) => void): void;
+    send(data: unknown): void;
+    close(): void;
+}
+interface PeerInstance {
+    on(event: 'open' | 'connection' | 'error' | 'close', handler: (data?: unknown) => void): void;
+    connect(peerId: string, options?: {
+        reliable?: boolean;
+        serialization?: string;
+    }): DataConnection;
+    destroy(): void;
+    id: string;
+}
+type TransportData = {
+    type: 'sync' | 'update' | 'chat';
+    args: unknown[];
+};
+interface P2PTransportOpts {
+    isHost?: boolean;
+    peerOptions?: object;
+    onError?: (error: Error) => void;
+}
+interface TransportConfig {
+    gameName: string;
+    playerID: string | null;
+    matchID: string;
+    credentials?: string;
+    numPlayers: number;
+    game: Game;
+    transportDataCallback: (data: TransportData) => void;
+}
+declare class P2PTransport {
+    private peer;
+    private connection;
+    private host;
+    private isHost;
+    private game;
+    private gameName;
+    private playerID;
+    private matchID;
+    private credentials?;
+    private numPlayers;
+    private privateKey?;
+    private transportDataCallback;
+    private peerOptions?;
+    private onError?;
+    private connected;
+    private connectionStatusCallbacks;
+    private hostRetryCount;
+    private maxHostRetries;
+    private lastPeerConfig;
+    constructor(config: TransportConfig, opts?: P2PTransportOpts);
+    private get hostID();
+    private setCredentials;
+    private get metadata();
+    connect(): void;
+    private createPeer;
+    private retryCount;
+    private maxRetries;
+    private retryDelayMs;
+    private connectToHost;
+    private onConnect;
+    private notifyConnectionStatus;
+    private notifyClient;
+    disconnect(): void;
+    requestSync(): void;
+    sendAction(state: State, action: CredentialedActionShape.Any): void;
+    sendChatMessage(matchID: string, chatMessage: ChatMessage): void;
+    updateMatchID(id: string): void;
+    updatePlayerID(id: string): void;
+    updateCredentials(credentials?: string): void;
+    isConnected(): boolean;
+    subscribeToConnectionStatus(callback: (connected: boolean) => void): () => void;
+}
+declare function createP2PTransport(opts?: P2PTransportOpts): (config: TransportConfig) => P2PTransport;
+
+/**
+ * Type definitions for boardgame.io widgets with bot support.
+ */
+
+/**
+ * BoardGame.io context object
+ */
+interface Ctx {
+    currentPlayer: string;
+    numPlayers: number;
+    turn: number;
+    phase: string | null;
+    gameover?: unknown;
+    playOrder: string[];
+    playOrderPos: number;
+    activePlayers: Record<string, string> | null;
+}
+/**
+ * Extended board props with bot-related information.
+ *
+ * All board components receive these props when mounted via createGameMount.
+ */
+interface BoardPropsWithBots<G = unknown> {
+    /** Game state */
+    G: G;
+    /** BoardGame.io context */
+    ctx: Ctx;
+    /** Available moves */
+    moves: Record<string, (...args: unknown[]) => void>;
+    /** BoardGame.io events (endTurn, setActivePlayers, etc) */
+    events: Record<string, (...args: unknown[]) => void>;
+    /** The player ID for this client */
+    playerID: string;
+    /** Whether it's this player's turn */
+    isActive: boolean;
+    /** Bot thinking state (injected by mount) */
+    botState: BotState;
+    /** List of player IDs controlled by bots */
+    botPlayerIDs: string[];
+    /** Total number of bots in the game */
+    botCount: number;
+    /** Current difficulty setting */
+    botDifficulty: BotDifficulty;
+    /** Whether this is a multiplayer game */
+    isMultiplayer: boolean;
+}
+/**
+ * Props for boards that don't use bots.
+ * Maintains backward compatibility with existing games.
+ */
+interface BoardProps<G = unknown> {
+    G: G;
+    ctx: Ctx;
+    moves: Record<string, (...args: unknown[]) => void>;
+    events: Record<string, (...args: unknown[]) => void>;
+    playerID: string;
+    isActive: boolean;
+    isMultiplayer?: boolean;
+    botCount?: number;
+}
+/**
+ * Game settings that can be passed via inputs.
+ */
+interface BotGameSettings {
+    /** Total player count */
+    numPlayers?: number;
+    /** Number of bot players */
+    botCount?: number;
+    /** Bot difficulty preset */
+    botDifficulty?: BotDifficulty;
+    /** Bot strategy override */
+    botStrategy?: 'random' | 'mcts' | 'custom';
+    /** Delay before bot move (ms) */
+    botDelay?: number;
+    /** Minimum delay for variable timing (ms) */
+    botMinDelay?: number;
+    /** MCTS iterations (for mcts strategy) */
+    mctsIterations?: number;
+    /** Chance of suboptimal move (0-1) */
+    botMistakeRate?: number;
+    /** Player ID for this client */
+    playerID?: string;
+}
+
+export { type BoardProps, type BoardPropsWithBots, type BoardgameGame, type BoardgameState, type BoardgameWidgetModule, type BotConfig, type BotDifficulty, type BotGameSettings, BotManager, type BotState, type BotStrategy, type Ctx, DIFFICULTY_PRESETS, type DifficultyPreset, type GameMountOptions, type GameSettings, type MultiplayerConfig, type MultiplayerInput, P2PDB, P2PHost, P2PTransport, type P2PTransportOpts, type ResolvedBotConfig, SettingsProvider, type SettingsProviderProps, type SetupOptions, type TransportConfig, type WidgetManifest, cleanup, computeBotPlayerIDs, createGameMount, createMountFromExports, createP2PTransport, ensurePeerJS, generateCredentials, generateKeyPair, generateMatchID, getMultiplayer, injectMountHelper, mount, resolveBotConfig, setup, useSettings };