@littlepartytime/sdk 2.2.3 → 2.3.1

package/GAME_DEV_GUIDE.md

@@ -86,6 +86,8 @@ const config: GameConfig = {
   tags: ["strategy", "card"],
   version: "1.0.0",
   sdkVersion: "2.0.0",
+  // Optional: include a demo site in the game package
+  // demo: { title: "My Game — Demo" },
 };
 
 export default config;
@@ -430,9 +432,33 @@ Features:
 - **Action log**: See all actions sent by players in real-time
 - **Game over detection**: Automatically detects when `isGameOver()` returns true and displays results
 - **Reset**: Re-initialize the game at any time
+- **Screenshot**: Capture the game content area (without the phone frame) as a PNG file
 
 This enables a rapid development cycle: **edit code -> refresh browser -> test immediately**.
 
+### Screenshot
+
+A **Screenshot** button floats at the bottom of the phone frame on the Preview page. Clicking it captures the game's safe area (390×751 px, 2× retina resolution) as a PNG and downloads it immediately. The phone bezel, Dynamic Island, and Home Indicator are excluded.
+
+The same capture function is also exposed as a JavaScript API on the page, so LLMs and Playwright scripts can call it programmatically:
+
+```javascript
+// Via Playwright evaluate (e.g. in a test or from an AI agent):
+const dataUrl = await page.evaluate(() => window.__devkit__.captureScreen());
+// dataUrl is a "data:image/png;base64,..." string — pass it to a vision model or save it.
+
+// Save to file in Node.js:
+const base64 = dataUrl.replace(/^data:image\/png;base64,/, '');
+fs.writeFileSync('screenshot.png', Buffer.from(base64, 'base64'));
+```
+
+Alternatively, Playwright's built-in element screenshot can target the game area directly using the stable test ID:
+
+```javascript
+const el = page.getByTestId('game-screen');
+await el.screenshot({ path: 'screenshot.png' });
+```
+
 ### Multiplayer Page
 
 The Play page runs your game with real Socket.IO multiplayer:
@@ -535,6 +561,16 @@ await preview.startGame();                // Host clicks "Start Game"
 await preview.stop();                     // Clean up browser + server
 ```
 
+To capture a screenshot of the game area during a test, use either approach:
+
+```typescript
+// Option A: via window.__devkit__ (returns base64 data URL)
+const dataUrl = await page.evaluate(() => window.__devkit__.captureScreen());
+
+// Option B: via Playwright element screenshot (saves directly to file)
+await page.getByTestId('game-screen').screenshot({ path: 'screenshot.png' });
+```
+
 ### Excluding E2E Tests from Unit Test Runs
 
 E2E tests are slower and require playwright. Exclude them from the default `vitest run`:
@@ -572,8 +608,9 @@ This command:
 3. Reads `GameConfig` from the built engine to extract metadata
 4. Validates the required image assets (format, dimensions, aspect ratio)
 5. Validates `rules.md` exists and is non-empty
-6. Generates `manifest.json` from your config
-7. Creates a `.zip` file in the `dist/` directory containing code, manifest, rules, and images
+6. If `GameConfig.demo` is set, validates that `demo/dist/index.html` exists and uses relative paths (no absolute `src="/..."` or `href="/..."` references)
+7. Generates `manifest.json` from your config
+8. Creates a `.zip` file in the `dist/` directory containing code, manifest, rules, images, and optional demo site
 
 ### Build Output
 
@@ -598,13 +635,31 @@ The `.zip` upload package contains:
 ├── banner.png|.webp  # 16:9 banner
 ├── cover.png|.webp   # 21:9 cover
 ├── splash.png|.webp  # 9:21 splash screen
-└── assets/        # Custom game assets (if any)
-    ├── cards/
-    │   └── king.png
-    └── sounds/
-        └── flip.mp3
+├── assets/        # Custom game assets (if any)
+│   ├── cards/
+│   │   └── king.png
+│   └── sounds/
+│       └── flip.mp3
+└── demo/          # Demo site (optional, only if GameConfig.demo is set)
+    └── index.html
 ```
 
+### Demo Site Configuration
+
+If your game includes a demo site (`GameConfig.demo` is set), the demo SPA will be deployed to a CDN subdirectory (e.g. `games/{gameId}/demo/`). **You must set `base: './'` in the demo's Vite config** to ensure all asset references use relative paths. Absolute paths like `/assets/...` will resolve to the CDN root and cause 404 errors.
+
+```typescript
+// demo/vite.config.ts
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  base: "./",
+  // ... other config
+});
+```
+
+The `pack` command will check `demo/dist/index.html` for absolute path references and report an error if any are found.
+
 ### Configuration
 
 The `lpt.config.ts` file configures local development. The `gameId` is a local project identifier used for the zip filename and dev server — it is NOT the platform game ID (the platform assigns that upon upload):

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export type { Player, GameAction, GameResult, Platform, HapticImpactStyle, HapticNotificationType, DeviceTilt, DeviceCapabilities, } from './types';
-export type { PlayerState, GameState, GameAssets, GameConfig, GameEngine, GameRendererProps } from './interfaces';
+export type { PlayerState, GameState, GameAssets, GameDemo, GameConfig, GameEngine, GameRendererProps } from './interfaces';
 //# 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,YAAY,EACV,MAAM,EACN,UAAU,EACV,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,EACV,kBAAkB,GACnB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,MAAM,EACN,UAAU,EACV,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,EACV,kBAAkB,GACnB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/interfaces.d.ts

@@ -18,6 +18,10 @@ export interface GameAssets {
     /** 9:21 loading/splash screen (1080x2520+ recommended, .png or .webp) */
     splash: string;
 }
+export interface GameDemo {
+    /** Title shown on the demo page (e.g. "奶酪大盗 — 游戏演示") */
+    title: string;
+}
 export interface GameConfig {
     name: string;
     description: string;
@@ -28,6 +32,8 @@ export interface GameConfig {
     version: string;
     sdkVersion: string;
     price?: number;
+    /** Optional demo site metadata. When present, `lpt-dev-kit pack` will look for `demo/dist/` and include it in the ZIP. */
+    demo?: GameDemo;
 }
 export interface GameEngine {
     init(players: Player[], options?: Record<string, unknown>): GameState;

package/dist/interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtE,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAChF;;;;;;;;;OASG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC;IACtC,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC;IACxC,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CAC3B"}
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0HAA0H;IAC1H,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtE,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAChF;;;;;;;;;OASG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC;IACtC,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC;IACxC,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CAC3B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlepartytime/sdk",
-  "version": "2.2.3",
+  "version": "2.3.1",
   "description": "Game SDK for Little Party Time platform - type definitions and testing utilities",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",