@littlepartytime/dev-kit 1.1.0 → 1.2.0

package/dist/commands/dev.d.ts

@@ -1,6 +1,12 @@
 export interface DevOptions {
     port?: number;
     socketPort?: number;
+    silent?: boolean;
 }
-export declare function devCommand(projectDir: string, options?: DevOptions): Promise<void>;
+export interface DevServerHandle {
+    stop(): Promise<void>;
+    port: number;
+    socketPort: number;
+}
+export declare function devCommand(projectDir: string, options?: DevOptions): Promise<DevServerHandle>;
 //# sourceMappingURL=dev.d.ts.map

package/dist/commands/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAsD5F"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAwEvG"}

package/dist/commands/dev.js

@@ -12,12 +12,14 @@ const chokidar_1 = __importDefault(require("chokidar"));
 async function devCommand(projectDir, options = {}) {
     const port = options.port || 4000;
     const socketPort = options.socketPort || 4001;
-    console.log('');
-    console.log('  Little Party Time Dev Kit');
-    console.log('  =========================');
-    console.log('');
+    if (!options.silent) {
+        console.log('');
+        console.log('  Little Party Time Dev Kit');
+        console.log('  =========================');
+        console.log('');
+    }
     // Start Socket.IO server
-    const { reloadEngine } = (0, socket_server_1.createSocketServer)({
+    const { server, io, reloadEngine } = (0, socket_server_1.createSocketServer)({
         port: socketPort,
         projectDir,
     });
@@ -25,7 +27,9 @@ async function devCommand(projectDir, options = {}) {
     const enginePath = path_1.default.join(projectDir, 'dist', 'engine.cjs');
     const watcher = chokidar_1.default.watch(enginePath, { ignoreInitial: true });
     watcher.on('change', () => {
-        console.log('[Dev] Engine changed, reloading...');
+        if (!options.silent) {
+            console.log('[Dev] Engine changed, reloading...');
+        }
         reloadEngine();
     });
     // Start Vite dev server
@@ -48,12 +52,25 @@ async function devCommand(projectDir, options = {}) {
         },
     });
     await vite.listen();
-    console.log(`  Preview:      http://localhost:${port}/preview`);
-    console.log(`  Multiplayer:  http://localhost:${port}/play`);
-    console.log(`  Debug Panel:  http://localhost:${port}/debug`);
-    console.log(`  Socket.IO:    ws://localhost:${socketPort}`);
-    console.log('');
-    console.log('  Press Ctrl+C to stop');
-    console.log('');
+    if (!options.silent) {
+        console.log(`  Preview:      http://localhost:${port}/preview`);
+        console.log(`  Multiplayer:  http://localhost:${port}/play`);
+        console.log(`  Debug Panel:  http://localhost:${port}/debug`);
+        console.log(`  Socket.IO:    ws://localhost:${socketPort}`);
+        console.log('');
+        console.log('  Press Ctrl+C to stop');
+        console.log('');
+    }
+    return {
+        port,
+        socketPort,
+        async stop() {
+            await watcher.close();
+            await vite.close();
+            io.disconnectSockets(true);
+            io.close();
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
 }
 //# sourceMappingURL=dev.js.map

package/dist/commands/dev.js.map

@@ -1 +1 @@
-{"version":3,"file":"dev.js","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":";;;;;AAWA,gCAsDC;AAjED,uCAAuC;AACvC,gDAAwB;AACxB,+BAAmD;AACnD,2DAA6D;AAC7D,wDAAgC;AAOzB,KAAK,UAAU,UAAU,CAAC,UAAkB,EAAE,UAAsB,EAAE;IAC3E,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC;IAClC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC;IAE9C,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAEhB,yBAAyB;IACzB,MAAM,EAAE,YAAY,EAAE,GAAG,IAAA,kCAAkB,EAAC;QAC1C,IAAI,EAAE,UAAU;QAChB,UAAU;KACX,CAAC,CAAC;IAEH,2BAA2B;IAC3B,MAAM,UAAU,GAAG,cAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;IAC/D,MAAM,OAAO,GAAG,kBAAQ,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACpE,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;QACxB,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;QAClD,YAAY,EAAE,CAAC;IACjB,CAAC,CAAC,CAAC;IAEH,wBAAwB;IACxB,MAAM,SAAS,GAAG,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAEvD,8DAA8D;IAC9D,MAAM,KAAK,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC,OAAO,CAAC;IAEtD,MAAM,IAAI,GAAkB,MAAM,IAAA,mBAAY,EAAC;QAC7C,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,EAAE;YACN,IAAI;YACJ,EAAE,EAAE;gBACF,KAAK,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;aAC/B;SACF;QACD,OAAO,EAAE;YACP,KAAK,EAAE;gBACL,MAAM,EAAE,cAAI,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC;aACrC;SACF;KACF,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;IAEpB,OAAO,CAAC,GAAG,CAAC,oCAAoC,IAAI,UAAU,CAAC,CAAC;IAChE,OAAO,CAAC,GAAG,CAAC,oCAAoC,IAAI,OAAO,CAAC,CAAC;IAC7D,OAAO,CAAC,GAAG,CAAC,oCAAoC,IAAI,QAAQ,CAAC,CAAC;IAC9D,OAAO,CAAC,GAAG,CAAC,kCAAkC,UAAU,EAAE,CAAC,CAAC;IAC5D,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;IACtC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"dev.js","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { validateBundle } from './utils/validate-bundle';
 export type { ValidationResult } from './utils/validate-bundle';
+export { devCommand } from './commands/dev';
+export type { DevOptions, DevServerHandle } from './commands/dev';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateBundle = void 0;
+exports.devCommand = exports.validateBundle = void 0;
 var validate_bundle_1 = require("./utils/validate-bundle");
 Object.defineProperty(exports, "validateBundle", { enumerable: true, get: function () { return validate_bundle_1.validateBundle; } });
+var dev_1 = require("./commands/dev");
+Object.defineProperty(exports, "devCommand", { enumerable: true, get: function () { return dev_1.devCommand; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,2DAAyD;AAAhD,iHAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,2DAAyD;AAAhD,iHAAA,cAAc,OAAA;AAEvB,sCAA4C;AAAnC,iGAAA,UAAU,OAAA"}

package/dist/testing/game-preview.d.ts

@@ -0,0 +1,53 @@
+export interface GamePreviewOptions {
+    /** Absolute path to the game project directory */
+    projectDir: string;
+    /** Number of players to simulate */
+    playerCount: number;
+    /** Vite dev server port (default: 4100) */
+    port?: number;
+    /** Socket.IO server port (default: 4101) */
+    socketPort?: number;
+    /** Run browser in headless mode (default: true) */
+    headless?: boolean;
+    /** Browser type to use (default: 'chromium') */
+    browserType?: 'chromium' | 'firefox' | 'webkit';
+}
+export declare class GamePreview {
+    private options;
+    private serverHandle;
+    private browser;
+    private context;
+    private playerPages;
+    constructor(options: GamePreviewOptions);
+    /**
+     * Start the dev server and launch browser pages for each player.
+     * Each player automatically joins the game lobby.
+     */
+    start(): Promise<void>;
+    /**
+     * Get the Playwright Page object for a specific player by index.
+     * Player 0 is the host.
+     */
+    getPlayerPage(playerIndex: number): any;
+    /**
+     * Get all Playwright Page objects.
+     */
+    getPlayerPages(): any[];
+    /**
+     * Get the number of players.
+     */
+    get playerCount(): number;
+    /**
+     * Click "Ready" for all players.
+     */
+    readyAll(): Promise<void>;
+    /**
+     * Have the host start the game. Requires all players to be ready.
+     */
+    startGame(): Promise<void>;
+    /**
+     * Stop the browser and dev server, cleaning up all resources.
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=game-preview.d.ts.map

package/dist/testing/game-preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-preview.d.ts","sourceRoot":"","sources":["../../src/testing/game-preview.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gDAAgD;IAChD,WAAW,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;CACjD;AAID,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,YAAY,CAAgC;IACpD,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,WAAW,CAAyC;gBAEhD,OAAO,EAAE,kBAAkB;IAUvC;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiD5B;;;OAGG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG;IASvC;;OAEG;IACH,cAAc,IAAI,GAAG,EAAE;IAIvB;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAS/B;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAYhC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAe5B"}

package/dist/testing/game-preview.js

@@ -0,0 +1,158 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GamePreview = void 0;
+const PLAYER_NAMES = ['Alice', 'Bob', 'Carol', 'Dave', 'Eve', 'Frank', 'Grace', 'Heidi'];
+class GamePreview {
+    options;
+    serverHandle = null;
+    browser = null;
+    context = null;
+    playerPages = [];
+    constructor(options) {
+        this.options = {
+            port: 4100,
+            socketPort: 4101,
+            headless: true,
+            browserType: 'chromium',
+            ...options,
+        };
+    }
+    /**
+     * Start the dev server and launch browser pages for each player.
+     * Each player automatically joins the game lobby.
+     */
+    async start() {
+        // 1. Start dev server programmatically
+        const { devCommand } = await Promise.resolve().then(() => __importStar(require('../commands/dev')));
+        this.serverHandle = await devCommand(this.options.projectDir, {
+            port: this.options.port,
+            socketPort: this.options.socketPort,
+            silent: true,
+        });
+        // 2. Launch browser (dynamic import to handle optional dependency)
+        let playwright;
+        try {
+            // Use variable to prevent TypeScript from resolving the module at compile time
+            const moduleName = 'playwright';
+            playwright = await Promise.resolve(`${moduleName}`).then(s => __importStar(require(s)));
+        }
+        catch {
+            throw new Error('GamePreview requires playwright. Install it with: npm install -D playwright');
+        }
+        const browserType = playwright[this.options.browserType];
+        if (!browserType) {
+            throw new Error(`Unknown browser type: ${this.options.browserType}`);
+        }
+        this.browser = await browserType.launch({
+            headless: this.options.headless,
+        });
+        this.context = await this.browser.newContext();
+        // 3. Open pages and join lobby for each player
+        for (let i = 0; i < this.options.playerCount; i++) {
+            const nickname = PLAYER_NAMES[i] || `Player ${i + 1}`;
+            const page = await this.context.newPage();
+            await page.goto(`http://localhost:${this.options.port}/play`);
+            // Fill nickname and join
+            await page.fill('input[placeholder="Your nickname"]', nickname);
+            await page.click('button:has-text("Join")');
+            // Wait for lobby to appear
+            await page.waitForSelector('text=Lobby', { timeout: 10000 });
+            this.playerPages.push({ page, nickname });
+        }
+    }
+    /**
+     * Get the Playwright Page object for a specific player by index.
+     * Player 0 is the host.
+     */
+    getPlayerPage(playerIndex) {
+        if (playerIndex < 0 || playerIndex >= this.playerPages.length) {
+            throw new Error(`Invalid playerIndex: ${playerIndex}. Valid range: 0-${this.playerPages.length - 1}`);
+        }
+        return this.playerPages[playerIndex].page;
+    }
+    /**
+     * Get all Playwright Page objects.
+     */
+    getPlayerPages() {
+        return this.playerPages.map(pp => pp.page);
+    }
+    /**
+     * Get the number of players.
+     */
+    get playerCount() {
+        return this.playerPages.length;
+    }
+    /**
+     * Click "Ready" for all players.
+     */
+    async readyAll() {
+        for (const pp of this.playerPages) {
+            const readyButton = pp.page.locator('button:has-text("Ready")');
+            await readyButton.click();
+            // Small delay to let Socket.IO propagate
+            await pp.page.waitForTimeout(100);
+        }
+    }
+    /**
+     * Have the host start the game. Requires all players to be ready.
+     */
+    async startGame() {
+        const hostPage = this.playerPages[0].page;
+        await hostPage.click('button:has-text("Start Game")');
+        // Wait for game state to load on all pages
+        await Promise.all(this.playerPages.map(pp => pp.page.waitForTimeout(500)));
+    }
+    /**
+     * Stop the browser and dev server, cleaning up all resources.
+     */
+    async stop() {
+        if (this.context) {
+            await this.context.close().catch(() => { });
+            this.context = null;
+        }
+        if (this.browser) {
+            await this.browser.close().catch(() => { });
+            this.browser = null;
+        }
+        if (this.serverHandle) {
+            await this.serverHandle.stop();
+            this.serverHandle = null;
+        }
+        this.playerPages = [];
+    }
+}
+exports.GamePreview = GamePreview;
+//# sourceMappingURL=game-preview.js.map

package/dist/testing/game-preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-preview.js","sourceRoot":"","sources":["../../src/testing/game-preview.ts"],"names":[],"mappings":"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"}

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+export { GamePreview } from './game-preview';
+export type { GamePreviewOptions } from './game-preview';
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/testing/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GamePreview = void 0;
+var game_preview_1 = require("./game-preview");
+Object.defineProperty(exports, "GamePreview", { enumerable: true, get: function () { return game_preview_1.GamePreview; } });
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":";;;AAAA,+CAA6C;AAApC,2GAAA,WAAW,OAAA"}

package/dist/webapp/pages/Preview.tsx

@@ -1,90 +1,243 @@
-import React, { useState, useEffect, useCallback } from 'react';
+import React, { useState, useEffect, useCallback, useMemo, useRef } from 'react';
+
+const PLAYER_NAMES = ['Alice', 'Bob', 'Carol', 'Dave', 'Eve', 'Frank', 'Grace', 'Heidi'];
 
 export default function Preview() {
-  const [state, setState] = useState<any>({ phase: 'playing', players: [], data: {} });
-  const [stateJson, setStateJson] = useState('');
+  const [playerCount, setPlayerCount] = useState(3);
   const [playerIndex, setPlayerIndex] = useState(0);
   const [actions, setActions] = useState<any[]>([]);
   const [GameRenderer, setGameRenderer] = useState<React.ComponentType<any> | null>(null);
+  const [engine, setEngine] = useState<any>(null);
+  const [fullState, setFullState] = useState<any>(null);
+  const [viewState, setViewState] = useState<any>(null);
+  const [gameOver, setGameOver] = useState(false);
+  const [gameResult, setGameResult] = useState<any>(null);
+  const [stateJson, setStateJson] = useState('');
+
+  // Refs to avoid recreating platform on every state change
+  const fullStateRef = useRef(fullState);
+  fullStateRef.current = fullState;
+  const playerIndexRef = useRef(playerIndex);
+  playerIndexRef.current = playerIndex;
+  const stateUpdateListeners = useRef<Set<(...args: unknown[]) => void>>(new Set());
 
-  // Load renderer dynamically
+  // Generate mock players
+  const mockPlayers = useMemo(() => {
+    return Array.from({ length: playerCount }, (_, i) => ({
+      id: `player-${i + 1}`,
+      nickname: PLAYER_NAMES[i] || `Player ${i + 1}`,
+      avatarUrl: null,
+      isHost: i === 0,
+    }));
+  }, [playerCount]);
+
+  const mockPlayersRef = useRef(mockPlayers);
+  mockPlayersRef.current = mockPlayers;
+
+  // Load renderer and engine dynamically
   useEffect(() => {
-    import('/src/renderer.tsx').then((mod) => {
-      setGameRenderer(() => mod.default || mod.Renderer);
+    import('/src/index.ts').then((mod) => {
+      setGameRenderer(() => mod.Renderer || mod.default);
+      if (mod.engine) {
+        setEngine(mod.engine);
+      }
     }).catch((err) => {
-      console.error('Failed to load renderer:', err);
+      console.error('Failed to load game module:', err);
+      // Fallback: try loading renderer directly
+      import('/src/renderer.tsx').then((mod) => {
+        setGameRenderer(() => mod.default || mod.Renderer);
+      }).catch((err2) => {
+        console.error('Failed to load renderer:', err2);
+      });
     });
   }, []);
 
-  // Mock players
-  const mockPlayers = [
-    { id: 'player-1', nickname: 'Alice', avatarUrl: null, isHost: true },
-    { id: 'player-2', nickname: 'Bob', avatarUrl: null, isHost: false },
-    { id: 'player-3', nickname: 'Carol', avatarUrl: null, isHost: false },
-  ];
-
-  // Mock platform
-  const platform = {
-    getPlayers: () => mockPlayers,
-    getLocalPlayer: () => mockPlayers[playerIndex],
-    send: (action: any) => {
-      setActions((prev) => [...prev, { time: new Date().toISOString(), player: mockPlayers[playerIndex].nickname, action }]);
-    },
-    on: () => {},
-    off: () => {},
-    reportResult: () => {},
-  };
-
-  const updateState = useCallback(() => {
+  // Initialize game when engine loads or player count changes
+  useEffect(() => {
+    if (!engine) return;
+    const initialState = engine.init(mockPlayers);
+    setFullState(initialState);
+    setGameOver(false);
+    setGameResult(null);
+    setActions([]);
+  }, [engine, mockPlayers]);
+
+  // Compute view state whenever fullState or playerIndex changes
+  useEffect(() => {
+    if (!engine || !fullState) return;
+    const view = engine.getPlayerView(fullState, mockPlayers[playerIndex].id);
+    setViewState(view);
+    // Notify renderer of new view
+    stateUpdateListeners.current.forEach(handler => handler(view));
+  }, [fullState, playerIndex, engine, mockPlayers]);
+
+  // Sync state JSON editor
+  useEffect(() => {
+    if (fullState) {
+      setStateJson(JSON.stringify(fullState, null, 2));
+    }
+  }, [fullState]);
+
+  // Platform object — stable reference via useMemo on engine + mockPlayers
+  const platform = useMemo(() => {
+    if (!engine) return null;
+    return {
+      getPlayers: () => mockPlayersRef.current,
+      getLocalPlayer: () => mockPlayersRef.current[playerIndexRef.current],
+      send: (action: any) => {
+        const currentState = fullStateRef.current;
+        if (!currentState) return;
+
+        const playerId = mockPlayersRef.current[playerIndexRef.current].id;
+
+        // Log the action
+        setActions(prev => [...prev, {
+          time: new Date().toISOString(),
+          player: mockPlayersRef.current[playerIndexRef.current].nickname,
+          action,
+        }]);
+
+        // Run through engine
+        const newState = engine.handleAction(currentState, playerId, action);
+        setFullState(newState);
+
+        // Check game over
+        if (engine.isGameOver(newState)) {
+          setGameOver(true);
+          setGameResult(engine.getResult(newState));
+        }
+      },
+      on: (event: string, handler: (...args: unknown[]) => void) => {
+        if (event === 'stateUpdate') {
+          stateUpdateListeners.current.add(handler);
+        }
+      },
+      off: (event: string, handler: (...args: unknown[]) => void) => {
+        if (event === 'stateUpdate') {
+          stateUpdateListeners.current.delete(handler);
+        }
+      },
+      reportResult: (result: any) => {
+        console.log('Game result reported:', result);
+      },
+    };
+  }, [engine]);
+
+  // Apply manual state override from JSON editor
+  const applyState = useCallback(() => {
     try {
       const parsed = JSON.parse(stateJson);
-      setState(parsed);
+      setFullState(parsed);
+      if (engine) {
+        setGameOver(engine.isGameOver(parsed));
+        if (engine.isGameOver(parsed)) {
+          setGameResult(engine.getResult(parsed));
+        } else {
+          setGameResult(null);
+        }
+      }
     } catch (e) {
-      // ignore
+      // ignore invalid JSON
     }
-  }, [stateJson]);
+  }, [stateJson, engine]);
+
+  // Reset game
+  const resetGame = useCallback(() => {
+    if (!engine) return;
+    const newState = engine.init(mockPlayersRef.current);
+    setFullState(newState);
+    setGameOver(false);
+    setGameResult(null);
+    setActions([]);
+  }, [engine]);
 
+  // Clamp playerIndex when playerCount decreases
   useEffect(() => {
-    setStateJson(JSON.stringify(state, null, 2));
-  }, []);
+    if (playerIndex >= playerCount) {
+      setPlayerIndex(0);
+    }
+  }, [playerCount, playerIndex]);
 
   return (
     <div className="flex gap-4 h-[calc(100vh-80px)]">
       {/* Renderer */}
       <div className="flex-1 bg-zinc-900 rounded-lg overflow-auto">
-        {GameRenderer ? (
-          <GameRenderer platform={platform} state={state} />
+        {GameRenderer && platform && viewState ? (
+          <GameRenderer platform={platform} state={viewState} />
         ) : (
-          <div className="p-4 text-zinc-500">Loading renderer...</div>
+          <div className="p-4 text-zinc-500">
+            {!engine ? 'Loading engine...' : 'Initializing game...'}
+          </div>
         )}
       </div>
 
       {/* Control Panel */}
-      <div className="w-80 flex flex-col gap-4">
+      <div className="w-80 flex flex-col gap-4 overflow-auto">
+        {/* Player Count */}
+        <div className="bg-zinc-900 rounded-lg p-3">
+          <h3 className="text-sm font-bold text-zinc-400 mb-2">Player Count</h3>
+          <input
+            type="number"
+            min={2}
+            max={8}
+            value={playerCount}
+            onChange={(e) => setPlayerCount(Math.max(2, Math.min(8, Number(e.target.value))))}
+            className="w-full bg-zinc-800 border border-zinc-700 rounded px-2 py-1 text-sm"
+          />
+        </div>
+
         {/* Player Switcher */}
         <div className="bg-zinc-900 rounded-lg p-3">
           <h3 className="text-sm font-bold text-zinc-400 mb-2">Current Player</h3>
           <select
             value={playerIndex}
             onChange={(e) => setPlayerIndex(Number(e.target.value))}
-            className="w-full bg-zinc-800 border border-zinc-700 rounded px-2 py-1"
+            className="w-full bg-zinc-800 border border-zinc-700 rounded px-2 py-1 text-sm"
           >
             {mockPlayers.map((p, i) => (
-              <option key={p.id} value={i}>{p.nickname}</option>
+              <option key={p.id} value={i}>{p.nickname}{p.isHost ? ' (Host)' : ''}</option>
             ))}
           </select>
         </div>
 
+        {/* Game Result */}
+        {gameOver && gameResult && (
+          <div className="bg-zinc-900 rounded-lg p-3">
+            <h3 className="text-sm font-bold text-green-400 mb-2">Game Over</h3>
+            <pre className="text-xs font-mono bg-zinc-800 rounded p-2 overflow-auto max-h-32 whitespace-pre-wrap">
+              {JSON.stringify(gameResult, null, 2)}
+            </pre>
+            <button
+              onClick={resetGame}
+              className="mt-2 w-full bg-amber-600 hover:bg-amber-500 text-white px-3 py-1 rounded text-sm"
+            >
+              Reset Game
+            </button>
+          </div>
+        )}
+
+        {/* Reset button (when game is not over) */}
+        {!gameOver && engine && (
+          <div className="bg-zinc-900 rounded-lg p-3">
+            <button
+              onClick={resetGame}
+              className="w-full bg-zinc-700 hover:bg-zinc-600 text-white px-3 py-1 rounded text-sm"
+            >
+              Reset Game
+            </button>
+          </div>
+        )}
+
         {/* State Editor */}
-        <div className="bg-zinc-900 rounded-lg p-3 flex-1 flex flex-col">
-          <h3 className="text-sm font-bold text-zinc-400 mb-2">Game State</h3>
+        <div className="bg-zinc-900 rounded-lg p-3 flex-1 flex flex-col min-h-0">
+          <h3 className="text-sm font-bold text-zinc-400 mb-2">Game State (Full)</h3>
           <textarea
             value={stateJson}
             onChange={(e) => setStateJson(e.target.value)}
-            className="flex-1 bg-zinc-800 border border-zinc-700 rounded p-2 font-mono text-xs resize-none"
+            className="flex-1 bg-zinc-800 border border-zinc-700 rounded p-2 font-mono text-xs resize-none min-h-[120px]"
           />
           <button
-            onClick={updateState}
+            onClick={applyState}
             className="mt-2 bg-amber-600 hover:bg-amber-500 text-white px-3 py-1 rounded text-sm"
           >
             Apply State

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "@littlepartytime/dev-kit",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Development toolkit CLI for Little Party Time game developers",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    }
+  },
   "bin": {
     "lpt-dev-kit": "./dist/cli.js"
   },
@@ -21,6 +31,14 @@
     "url": "https://github.com/chesterli710/littlepartytime-sdk.git",
     "directory": "packages/dev-kit"
   },
+  "peerDependencies": {
+    "playwright": ">=1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@vitejs/plugin-react": "^5",
     "archiver": "^7",