@littlepartytime/dev-kit 1.17.0 → 1.18.1

package/dist/webapp/App.tsx

@@ -1,7 +1,8 @@
-import React, { useState } from 'react';
+import React, { useState, useEffect } from 'react';
 import Preview from './pages/Preview';
 import Play from './pages/Play';
 import Debug from './pages/Debug';
+import { captureScreen } from './utils/captureScreen';
 
 type Page = 'preview' | 'play' | 'debug';
 
@@ -13,6 +14,13 @@ export default function App() {
     return 'preview';
   });
 
+  // Expose capture API for LLM/Playwright callers:
+  //   await page.evaluate(() => window.__devkit__.captureScreen())
+  useEffect(() => {
+    (window as any).__devkit__ = { captureScreen };
+    return () => { delete (window as any).__devkit__; };
+  }, []);
+
   return (
     <div style={{ minHeight: '100vh', display: 'flex', flexDirection: 'column' }}>
       {/* Nav */}

package/dist/webapp/components/PhoneFrame.tsx

@@ -84,6 +84,8 @@ export default function PhoneFrame({ children }: { children: React.ReactNode })
                 contain:paint makes this the containing block for
                 position:fixed elements inside the game. */}
             <div
+              id="devkit-game-screen"
+              data-testid="game-screen"
               style={{
                 position: 'absolute',
                 overflow: 'hidden',

package/dist/webapp/pages/Preview.tsx

@@ -1,6 +1,7 @@
 import React, { useState, useEffect, useCallback, useMemo, useRef } from 'react';
 import PhoneFrame from '../components/PhoneFrame';
 import PlatformTakeover from '../components/PlatformTakeover';
+import { captureScreen, downloadScreenshot } from '../utils/captureScreen';
 
 const PLAYER_NAMES = ['Alice', 'Bob', 'Carol', 'Dave', 'Eve', 'Frank', 'Grace', 'Heidi'];
 
@@ -23,6 +24,7 @@ export default function Preview() {
   const [gameOver, setGameOver] = useState(false);
   const [gameResult, setGameResult] = useState<any>(null);
   const [stateJson, setStateJson] = useState('');
+  const [capturing, setCapturing] = useState(false);
 
   // Refs to avoid recreating platform on every state change
   const fullStateRef = useRef(fullState);
@@ -202,10 +204,23 @@ export default function Preview() {
     return () => { window.removeEventListener('mousemove', onMove); window.removeEventListener('mouseup', onUp); };
   }, []);
 
+  const handleScreenshot = useCallback(async () => {
+    if (capturing) return;
+    setCapturing(true);
+    try {
+      const dataUrl = await captureScreen();
+      downloadScreenshot(dataUrl);
+    } catch (err) {
+      console.error('[DevKit] Screenshot failed:', err);
+    } finally {
+      setCapturing(false);
+    }
+  }, [capturing]);
+
   return (
     <div style={{ display: 'flex', gap: 16, height: 'calc(100vh - 80px)' }}>
       {/* Renderer — half the screen width */}
-      <div style={{ width: '50%', height: '100%' }}>
+      <div style={{ width: '50%', height: '100%', position: 'relative' }}>
         <PhoneFrame>
           {gameOver && gameResult ? (
             <PlatformTakeover result={gameResult} players={mockPlayers} onReturn={resetGame} />
@@ -217,6 +232,36 @@ export default function Preview() {
             </div>
           )}
         </PhoneFrame>
+        {/* Screenshot button — floats below the centered phone */}
+        <button
+          onClick={handleScreenshot}
+          disabled={capturing}
+          title="Capture game screen (without phone frame)"
+          style={{
+            position: 'absolute',
+            bottom: 12,
+            left: '50%',
+            transform: 'translateX(-50%)',
+            display: 'flex',
+            alignItems: 'center',
+            gap: 6,
+            padding: '5px 14px',
+            borderRadius: 6,
+            border: '1px solid #3f3f46',
+            background: capturing ? '#27272a' : '#18181b',
+            color: capturing ? '#71717a' : '#a1a1aa',
+            fontSize: 13,
+            cursor: capturing ? 'default' : 'pointer',
+            transition: 'background 0.15s, color 0.15s',
+            zIndex: 10,
+          }}
+        >
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <path d="M23 19a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h4l2-3h6l2 3h4a2 2 0 0 1 2 2z"/>
+            <circle cx="12" cy="13" r="4"/>
+          </svg>
+          {capturing ? 'Capturing...' : 'Screenshot'}
+        </button>
       </div>
 
       {/* Control Panel — fills remaining width, resizable two-column */}

package/dist/webapp/utils/captureScreen.ts

@@ -0,0 +1,84 @@
+import html2canvas from 'html2canvas';
+
+// Must match PhoneFrame constants: SCREEN_W=390, SAFE_AREA_TOP=59, SAFE_AREA_BOTTOM=34, SCREEN_H=844
+const CAPTURE_W = 390;
+const CAPTURE_H = 751; // 844 - 59 - 34
+
+/**
+ * Captures the game content area (safe area only, no phone bezel).
+ * Returns a base64-encoded PNG data URL.
+ *
+ * Also exposed on window.__devkit__.captureScreen() for LLM/Playwright callers:
+ *   await page.evaluate(() => window.__devkit__.captureScreen())
+ *
+ * ## Why the style normalization?
+ * The PhoneFrame has two CSS properties that break html2canvas:
+ *
+ * 1. `contain: paint` on Screen div and safe-area div — html2canvas uses
+ *    getBoundingClientRect() to determine clip rects. With a scaled ancestor,
+ *    getBoundingClientRect() returns the *visual* (post-transform) size. Combined
+ *    with contain:paint, html2canvas clips the rendered output to the visual height
+ *    (e.g. 375px at 0.5× scale) even though the canvas is 751px tall, leaving the
+ *    bottom half black.
+ *
+ * 2. `transform: scale(x)` on the phone body — causes the same getBoundingClientRect
+ *    mismatch; the element's intrinsic size is 390×751 but its visual rect is smaller.
+ *
+ * Fix: temporarily set both to neutral values, wait two rAF ticks for the browser to
+ * apply the changes, run html2canvas, then restore. An invisible overlay prevents the
+ * user from seeing the brief layout shift.
+ */
+export async function captureScreen(): Promise<string> {
+  const el = document.getElementById('devkit-game-screen');
+  if (!el) throw new Error('[devkit] #devkit-game-screen not found — is the Preview page active?');
+
+  // Invisible overlay so the user never sees the brief style normalization flash.
+  const overlay = document.createElement('div');
+  overlay.style.cssText = 'position:fixed;inset:0;z-index:99999;pointer-events:none;';
+  document.body.appendChild(overlay);
+
+  // Wait for overlay to paint before touching any styles.
+  await new Promise<void>(r => requestAnimationFrame(() => requestAnimationFrame(r)));
+
+  // Walk up the DOM and neutralise contain:paint and transform:scale on all ancestors.
+  const saved: Array<[HTMLElement, 'contain' | 'transform', string]> = [];
+  let node: HTMLElement | null = el;
+  while (node && node !== document.body) {
+    for (const prop of ['contain', 'transform'] as const) {
+      if (node.style[prop]) {
+        saved.push([node, prop, node.style[prop]]);
+        node.style[prop] = prop === 'transform' ? 'none' : '';
+      }
+    }
+    node = node.parentElement;
+  }
+
+  // Wait for the browser to reflow/repaint with the normalised styles.
+  await new Promise<void>(r => requestAnimationFrame(() => requestAnimationFrame(r)));
+
+  try {
+    const canvas = await html2canvas(el, {
+      width: CAPTURE_W,
+      height: CAPTURE_H,
+      scale: 2,
+      logging: false,
+      backgroundColor: null,
+      useCORS: true,
+      allowTaint: true,
+    });
+    return canvas.toDataURL('image/png');
+  } finally {
+    // Restore styles and remove overlay regardless of success/failure.
+    for (const [node, prop, val] of saved) node.style[prop] = val;
+    document.body.removeChild(overlay);
+  }
+}
+
+export function downloadScreenshot(dataUrl: string): void {
+  const a = document.createElement('a');
+  a.href = dataUrl;
+  a.download = `game-screenshot-${Date.now()}.png`;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlepartytime/dev-kit",
-  "version": "1.17.0",
+  "version": "1.18.1",
   "description": "Development toolkit CLI for Little Party Time game developers",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -23,8 +23,14 @@
     "test": "vitest run",
     "test:watch": "vitest"
   },
-  "files": ["dist"],
-  "keywords": ["boardgame", "dev-tools", "littlepartytime"],
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "boardgame",
+    "dev-tools",
+    "littlepartytime"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -44,6 +50,7 @@
     "archiver": "^7",
     "chokidar": "^4",
     "express": "^5",
+    "html2canvas": "^1.4.1",
     "react": "^19",
     "react-dom": "^19",
     "socket.io": "^4",