create-smore-game 0.2.0 → 0.2.1

package/templates.js

@@ -1,21 +1,27 @@
 // ─── Shared ───
 
-export const pnpmWorkspace = `packages:
-  - screen
-  - player
-`;
+// pnpm-workspace.yaml is no longer generated.
+// npm workspaces are configured in root package.json instead.
+
+const SDK_VERSION = '^1.0.0';
 
 export function rootPackageJson(name) {
   return JSON.stringify(
     {
       name,
       private: true,
+      workspaces: ["screen", "controller"],
       scripts: {
-        "dev": "pnpm -r --parallel dev",
-        "dev:screen": "pnpm --filter screen dev",
-        "dev:player": "pnpm --filter player dev",
-        "build": "pnpm -r build",
-        "zip": "pnpm build && node -e \"const{execSync:e}=require('child_process');e('cd dist && zip -r ../'+process.env.npm_package_name+'.zip .');\""
+        dev: "node dev/server.js",
+        "dev:screen": "npm run dev -w screen",
+        "dev:controller": "npm run dev -w controller",
+        build: "npm run build --workspaces --if-present",
+        zip: 'npm run build --workspaces --if-present && cp game.json dist/ && cd dist && zip -r ../game.zip .',
+      },
+      devDependencies: {
+        "socket.io": "^4.7.0",
+        express: "^4.18.0",
+        cors: "^2.8.5",
       },
     },
     null,
@@ -23,6 +29,12 @@ export function rootPackageJson(name) {
   );
 }
 
+export function envExample() {
+  return `# Server URL for development (optional)
+# VITE_SERVER_URL=http://localhost:3001
+`;
+}
+
 // ─── Screen templates ───
 
 const screenTsconfig = JSON.stringify(
@@ -66,8 +78,9 @@ function screenViteConfig(isReact) {
 import react from '@vitejs/plugin-react';
 
 export default defineConfig({
+  base: './',
   plugins: [react()],
-  server: { port: 5173 },
+  server: { port: 5173, host: true },
   build: { outDir: '../dist/screen' },
 });
 `;
@@ -75,7 +88,8 @@ export default defineConfig({
   return `import { defineConfig } from 'vite';
 
 export default defineConfig({
-  server: { port: 5173 },
+  base: './',
+  server: { port: 5173, host: true },
   build: { outDir: '../dist/screen' },
 });
 `;
@@ -104,6 +118,8 @@ function screenIndexHtml(title, isReact) {
 }
 
 // Screen: React + Phaser
+// Test utilities: createMockScreen(), createMockController() can be imported in test files
+// Example: import { createMockScreen } from '@smoregg/sdk';
 export function screenReactPhaser(gameId) {
   return {
     "package.json": JSON.stringify(
@@ -119,7 +135,7 @@ export function screenReactPhaser(gameId) {
           react: "^18.3.1",
           "react-dom": "^18.3.1",
           phaser: "^3.80.1",
-          "@smoregg/sdk": "^0.1.0",
+          "@smoregg/sdk": SDK_VERSION, // TODO: auto-detect or update on release
         },
         devDependencies: {
           "@types/react": "^18.3.0",
@@ -136,38 +152,108 @@ export function screenReactPhaser(gameId) {
     "vite.config.ts": screenViteConfig(true),
     "index.html": screenIndexHtml(gameId, true),
     "src/main.tsx": `import { createRoot } from 'react-dom/client';
-import { IframeRoomProvider } from '@smoregg/sdk/iframe';
 import { App } from './App';
 
-createRoot(document.getElementById('root')!).render(
-  <IframeRoomProvider>
-    <App />
-  </IframeRoomProvider>
-);
+createRoot(document.getElementById('root')!).render(<App />);
 `,
-    "src/App.tsx": `import { useGameHost } from '@smoregg/sdk/iframe';
-import { useEffect, useRef } from 'react';
+    "src/App.tsx": `import { createScreen } from '@smoregg/sdk';
+import type { Screen, ControllerInfo, GameResults } from '@smoregg/sdk';
+import { useEffect, useRef, useState } from 'react';
 import Phaser from 'phaser';
 import { GameScene } from './scenes/GameScene';
 
+// Type-safe events example:
+// type MyEvents = { 'player-move': { x: number; y: number } };
+// const screen = await createScreen<MyEvents>({ ... });
+
+// Testing: Use mock utilities for unit tests
+// import { createMockScreen, createMockController } from '@smoregg/sdk';
+// const mockScreen = createMockScreen();
+// mockScreen.simulateControllerJoin({ playerIndex: 0, name: 'Test' });
+
+// Error handling:
+// screen/controller onError callback handles initialization and runtime errors.
+// Wrap critical game logic in try/catch for graceful error recovery.
+
+// Import GameMetadata type for game.json schema:
+// import type { GameMetadata } from '@smoregg/sdk';
+// game.json fields: { id, title, description, minPlayers, maxPlayers, version }
+// See docs for full GameMetadata schema.
+
 export function App() {
+  const screenRef = useRef<Screen | null>(null);
   const gameRef = useRef<Phaser.Game | null>(null);
-  const { room, broadcast } = useGameHost({
-    gameId: '${gameId}',
-    onInput: {
-      tap: (playerId, data) => {
-        console.log('Player tapped:', playerId, data);
+  const [roomCode, setRoomCode] = useState('');
+  const [controllers, setControllers] = useState<ControllerInfo[]>([]);
+
+  useEffect(() => {
+    let mounted = true;
+
+    const init = async () => {
+      // Alternative: register listeners in config (instead of screen.on())
+      // const screen = await createScreen({
+      //   listeners: {
+      //     'tap': (playerIndex, data) => console.log('Player', playerIndex, 'tapped:', data),
+      //   },
+      // });
+      // Note: listeners in config are set during initialization and cannot be removed.
+      // Use screen.on(event, handler) / screen.off(event, handler) for dynamic listeners.
+
+      const screen = await createScreen({
+        debug: true,
+        onControllerJoin: (playerIndex, info) => {
+          console.log('Player joined:', playerIndex);
+          // Access player character data:
+          // const { nickname, appearance } = info;
+          // console.log(nickname, appearance?.style, appearance?.seed);
+          setControllers([...screen.controllers]);
+        },
+        onControllerLeave: (playerIndex) => {
+          console.log('Player left:', playerIndex);
+          setControllers([...screen.controllers]);
+        },
+        // Advanced callbacks (uncomment to use):
+        onControllerDisconnect: (playerIndex) => {
+          console.log(\`Player \${playerIndex} disconnected\`);
+        },
+        // onControllerReconnect: (playerIndex: number, info: ControllerInfo) => void — called when a disconnected player reconnects
+        // onCharacterUpdated: (playerIndex: number, appearance: CharacterAppearance | null) => void — called when a player updates their character appearance
+        // onRateLimited: (event: string) => void — called when client is rate-limited by server
+        onError: (error) => {
+          console.error('SDK Error:', error.message);
+          // Show user-friendly error UI
+        },
+      });
+      if (!mounted) {
+        screen.destroy();
+        return;
+      }
+
+      screenRef.current = screen;
+      setRoomCode(screen.roomCode);
+      setControllers([...screen.controllers]);
+
+      // Note: listeners in config are set during initialization (onControllerJoin, etc. above).
+      // Use screen.on(event, handler) / screen.off(event, handler) for dynamic event listeners.
+      // Cleanup example (useful in React useEffect):
+      // const handler = (playerIndex, data) => { ... };
+      // screen.on('my-event', handler);
+      // Later: screen.off('my-event', handler);
+      screen.on('tap', (playerIndex, data) => {
+        console.log('Player', playerIndex, 'tapped:', data);
         // Forward input to Phaser scene
-        gameRef.current?.events.emit('player-tap', { playerId, ...data });
-      },
-    },
-    onPlayerJoin: (playerId) => {
-      console.log('Player joined:', playerId);
-    },
-    onPlayerLeave: (playerId) => {
-      console.log('Player left:', playerId);
-    },
-  });
+        gameRef.current?.events.emit('player-tap', { playerIndex, ...data });
+      });
+    };
+
+    init();
+
+    return () => {
+      mounted = false;
+      screenRef.current?.destroy();
+      screenRef.current = null;
+    };
+  }, []);
 
   useEffect(() => {
     if (gameRef.current) return;
@@ -194,6 +280,11 @@ export function App() {
   return (
     <div style={{ width: '100%', height: '100%' }}>
       <div id="phaser-container" style={{ width: '100%', height: '100%' }} />
+      {roomCode && (
+        <div style={{ position: 'absolute', top: '20px', left: '20px', fontSize: '24px' }}>
+          Room: {roomCode} | Players: {controllers.length}
+        </div>
+      )}
     </div>
   );
 }
@@ -216,8 +307,8 @@ export class GameScene extends Phaser.Scene {
       .setOrigin(0.5);
 
     // Listen for player taps forwarded from React
-    this.game.events.on('player-tap', (data: { playerId: string }) => {
-      this.label.setText(\`Player \${data.playerId.slice(0, 6)} tapped!\`);
+    this.game.events.on('player-tap', (data: { playerIndex: number }) => {
+      this.label.setText(\`Player \${data.playerIndex} tapped!\`);
     });
   }
 }
@@ -226,6 +317,8 @@ export class GameScene extends Phaser.Scene {
 }
 
 // Screen: React only
+// Test utilities: createMockScreen(), createMockController() can be imported in test files
+// Example: import { createMockScreen } from '@smoregg/sdk';
 export function screenReact(gameId) {
   return {
     "package.json": JSON.stringify(
@@ -240,7 +333,7 @@ export function screenReact(gameId) {
         dependencies: {
           react: "^18.3.1",
           "react-dom": "^18.3.1",
-          "@smoregg/sdk": "^0.1.0",
+          "@smoregg/sdk": SDK_VERSION, // TODO: auto-detect or update on release
         },
         devDependencies: {
           "@types/react": "^18.3.0",
@@ -257,44 +350,130 @@ export function screenReact(gameId) {
     "vite.config.ts": screenViteConfig(true),
     "index.html": screenIndexHtml(gameId, true),
     "src/main.tsx": `import { createRoot } from 'react-dom/client';
-import { IframeRoomProvider } from '@smoregg/sdk/iframe';
 import { App } from './App';
 
-createRoot(document.getElementById('root')!).render(
-  <IframeRoomProvider>
-    <App />
-  </IframeRoomProvider>
-);
+createRoot(document.getElementById('root')!).render(<App />);
 `,
-    "src/App.tsx": `import { useGameHost } from '@smoregg/sdk/iframe';
-import { useState } from 'react';
+    "src/App.tsx": `import { createScreen } from '@smoregg/sdk';
+import type { Screen, ControllerInfo, GameResults } from '@smoregg/sdk';
+import { useEffect, useRef, useState } from 'react';
+
+// Type-safe events example:
+// type MyEvents = { 'player-move': { x: number; y: number } };
+// const screen = await createScreen<MyEvents>({ ... });
+
+// Testing: Use mock utilities for unit tests
+// import { createMockScreen, createMockController } from '@smoregg/sdk';
+// const mockScreen = createMockScreen();
+// mockScreen.simulateControllerJoin({ playerIndex: 0, name: 'Test' });
+
+// Error handling:
+// screen/controller onError callback handles initialization and runtime errors.
+// Wrap critical game logic in try/catch for graceful error recovery.
+
+// Import GameMetadata type for game.json schema:
+// import type { GameMetadata } from '@smoregg/sdk';
+// game.json fields: { id, title, description, minPlayers, maxPlayers, version }
+// See docs for full GameMetadata schema.
+
+// Advanced: Validate custom event names before sending
+// import { validateEventName } from '@smoregg/sdk';
+// validateEventName('my-event'); // throws if contains ':'
 
 export function App() {
-  const [taps, setTaps] = useState<{ playerId: string; time: number }[]>([]);
+  const screenRef = useRef<Screen | null>(null);
+  const [roomCode, setRoomCode] = useState('');
+  const [controllers, setControllers] = useState<ControllerInfo[]>([]);
+  const [taps, setTaps] = useState<{ playerIndex: number; time: number }[]>([]);
 
-  const { room, broadcast } = useGameHost({
-    gameId: '${gameId}',
-    onInput: {
-      tap: (playerId, data) => {
-        setTaps((prev) => [...prev.slice(-9), { playerId, time: Date.now() }]);
-      },
-    },
-    onPlayerJoin: (playerId) => {
-      console.log('Player joined:', playerId);
-    },
-    onPlayerLeave: (playerId) => {
-      console.log('Player left:', playerId);
-    },
-  });
+  useEffect(() => {
+    let mounted = true;
+
+    const init = async () => {
+      const screen = await createScreen({
+        debug: true,
+        onControllerJoin: (playerIndex, info) => {
+          console.log('Player joined:', playerIndex);
+          setControllers([...screen.controllers]);
+        },
+        onControllerLeave: (playerIndex) => {
+          console.log('Player left:', playerIndex);
+          setControllers([...screen.controllers]);
+        },
+        // Advanced callbacks (uncomment to use):
+        onControllerDisconnect: (playerIndex) => {
+          console.log(\`Player \${playerIndex} disconnected\`);
+        },
+        // onControllerReconnect: (playerIndex: number, info: ControllerInfo) => void — called when a disconnected player reconnects
+        // onCharacterUpdated: (playerIndex: number, appearance: CharacterAppearance | null) => void — called when a player updates their character appearance
+        // onRateLimited: (event: string) => void — called when client is rate-limited by server
+        onError: (error) => {
+          console.error('SDK Error:', error.message);
+          // Show user-friendly error UI
+        },
+      });
+      if (!mounted) {
+        screen.destroy();
+        return;
+      }
+
+      screenRef.current = screen;
+      setRoomCode(screen.roomCode);
+      setControllers([...screen.controllers]);
+
+      // Note: listeners in config are set during initialization (onControllerJoin, etc. above).
+      // Use screen.on(event, handler) / screen.off(event, handler) for dynamic event listeners.
+      // destroy() automatically removes all listeners, so explicit off() cleanup is not needed.
+      screen.on('tap', (playerIndex) => {
+        setTaps((prev) => [...prev.slice(-9), { playerIndex, time: Date.now() }]);
+      });
+    };
+
+    init();
+
+    return () => {
+      mounted = false;
+      screenRef.current?.destroy();
+      screenRef.current = null;
+    };
+  }, []);
+
+  // Example: send score update to all players
+  const handleBroadcastScore = () => {
+    screenRef.current?.broadcast('score-update', { score: 100 });
+  };
+
+  // Example: send to specific player
+  const handleSendToPlayer = (playerIndex: number) => {
+    screenRef.current?.sendToController(playerIndex, 'personal-message', { text: 'Hello!' });
+  };
+
+  // Example: end game with GameResults type
+  const handleGameOver = () => {
+    const scores: Record<number, number> = {};
+    controllers.forEach((_, idx) => {
+      scores[idx] = Math.floor(Math.random() * 100);
+    });
+    // GameResults fields: scores (required), winner (optional), reason (optional)
+    const results: GameResults = {
+      scores,
+      // winner: 0, // optional — playerIndex of winner
+      // reason: 'time-up', // optional — custom game-over reason
+    };
+    screenRef.current?.gameOver(results);
+  };
 
   return (
     <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', height: '100%', gap: '2vmin' }}>
       <h1 style={{ fontSize: '5vmin' }}>
-        {room?.players?.length ? \`\${room.players.length} player(s) connected\` : 'Waiting for players...'}
+        {controllers.length ? \`\${controllers.length} player(s) connected\` : 'Waiting for players...'}
       </h1>
+      {roomCode && (
+        <div style={{ fontSize: '3vmin', opacity: 0.8 }}>Room Code: {roomCode}</div>
+      )}
       <div style={{ fontSize: '3vmin', opacity: 0.6 }}>
         {taps.map((t, i) => (
-          <div key={i}>Player {t.playerId.slice(0, 6)} tapped</div>
+          <div key={i}>Player {t.playerIndex} tapped</div>
         ))}
       </div>
     </div>
@@ -305,6 +484,8 @@ export function App() {
 }
 
 // Screen: Vanilla JS
+// Test utilities: createMockScreen(), createMockController() can be imported in test files
+// Example: import { createMockScreen } from '@smoregg/sdk';
 export function screenVanilla(gameId) {
   return {
     "package.json": JSON.stringify(
@@ -317,7 +498,7 @@ export function screenVanilla(gameId) {
           build: "tsc && vite build",
         },
         dependencies: {
-          "@smoregg/sdk": "^0.1.0",
+          "@smoregg/sdk": SDK_VERSION, // TODO: auto-detect or update on release
         },
         devDependencies: {
           typescript: "^5.5.0",
@@ -340,43 +521,111 @@ export function screenVanilla(gameId) {
       html, body { width: 100%; height: 100%; background: #0f0f0f; color: #fff; font-family: sans-serif; overflow: hidden; }
       #app { width: 100%; height: 100%; display: flex; align-items: center; justify-content: center; flex-direction: column; gap: 2vmin; }
       h1 { font-size: 5vmin; }
+      #room-code { font-size: 3vmin; opacity: 0.8; }
       #log { font-size: 3vmin; opacity: 0.6; }
     </style>
   </head>
   <body>
     <div id="app">
       <h1 id="status">Waiting for players...</h1>
+      <div id="room-code"></div>
       <div id="log"></div>
     </div>
     <script type="module" src="/src/main.ts"></script>
   </body>
 </html>
 `,
-    "src/main.ts": `import { createIframeHost } from '@smoregg/sdk/iframe';
-
-const host = createIframeHost({
-  gameId: '${gameId}',
-  onInput: {
-    tap: (playerId: string, data: unknown) => {
-      const log = document.getElementById('log')!;
-      const line = document.createElement('div');
-      line.textContent = \`Player \${playerId.slice(0, 6)} tapped\`;
-      log.appendChild(line);
-      // Keep last 10
-      while (log.children.length > 10) log.removeChild(log.firstChild!);
+    "src/main.ts": `import { createScreen } from '@smoregg/sdk';
+import type { Screen, ControllerInfo, GameResults } from '@smoregg/sdk';
+
+// Type-safe events example:
+// type MyEvents = { 'player-move': { x: number; y: number } };
+// const screen = await createScreen<MyEvents>({ ... });
+
+// Testing: Use mock utilities for unit tests
+// import { createMockScreen, createMockController } from '@smoregg/sdk';
+// const mockScreen = createMockScreen();
+// mockScreen.simulateControllerJoin({ playerIndex: 0, name: 'Test' });
+
+// Error handling:
+// screen/controller onError callback handles initialization and runtime errors.
+// Wrap critical game logic in try/catch for graceful error recovery.
+
+// Import GameMetadata type for game.json schema:
+// import type { GameMetadata } from '@smoregg/sdk';
+// game.json fields: { id, title, description, minPlayers, maxPlayers, version }
+// See docs for full GameMetadata schema.
+
+const statusEl = document.getElementById('status')!;
+const roomCodeEl = document.getElementById('room-code')!;
+const logEl = document.getElementById('log')!;
+
+let screen: Screen;
+
+async function init() {
+  screen = await createScreen({
+    debug: true,
+    onControllerJoin: (playerIndex) => {
+      console.log('Player joined:', playerIndex);
+      updateStatus();
     },
-  },
-  onPlayerJoin: (playerId: string) => {
-    document.getElementById('status')!.textContent = 'Player connected!';
-  },
-});
+    onControllerLeave: (playerIndex) => {
+      console.log('Player left:', playerIndex);
+      updateStatus();
+    },
+    // Advanced callbacks (uncomment to use):
+    onControllerDisconnect: (playerIndex) => {
+      console.log(\`Player \${playerIndex} disconnected\`);
+    },
+    // onControllerReconnect: (playerIndex, info) => { console.log('Player reconnected:', playerIndex); },
+    // onCharacterUpdated: (playerIndex, appearance) => { console.log('Character updated:', playerIndex); },
+    // onRateLimited: (event: string) => { console.warn('Rate limited:', event); },
+    onError: (error) => {
+      console.error('SDK Error:', error.message);
+      // Show user-friendly error UI
+    },
+  });
+
+  roomCodeEl.textContent = \`Room Code: \${screen.roomCode}\`;
+  updateStatus();
+
+  // Note: listeners in config are set during initialization (onControllerJoin, etc. above).
+  // Use screen.on(event, handler) / screen.off(event, handler) for dynamic event listeners.
+  // destroy() automatically removes all listeners, so explicit off() cleanup is not needed.
+  screen.on('tap', (playerIndex: number, data: unknown) => {
+    const line = document.createElement('div');
+    line.textContent = \`Player \${playerIndex} tapped\`;
+    logEl.appendChild(line);
+    // Keep last 10 entries
+    while (logEl.children.length > 10) {
+      logEl.removeChild(logEl.firstChild!);
+    }
+  });
+}
+
+function updateStatus() {
+  const count = screen.controllers.length;
+  statusEl.textContent = count > 0 ? \`\${count} player(s) connected\` : 'Waiting for players...';
+}
+
+init();
+
+// Example functions (can be called from console for testing):
+// screen.broadcast('score-update', { score: 100 });
+// screen.sendToController(0, 'message', { text: 'Hello!' });
+// const results: GameResults = {
+//   scores: { 0: 50, 1: 75 },
+//   // winner: 0,
+//   // reason: 'time-up',
+// };
+// screen.gameOver(results);
 `,
   };
 }
 
-// ─── Player templates ───
+// ─── Controller templates ───
 
-const playerTsconfig = JSON.stringify(
+const controllerTsconfig = JSON.stringify(
   {
     compilerOptions: {
       target: "ES2020",
@@ -394,7 +643,7 @@ const playerTsconfig = JSON.stringify(
   2,
 );
 
-const playerTsconfigVanilla = JSON.stringify(
+const controllerTsconfigVanilla = JSON.stringify(
   {
     compilerOptions: {
       target: "ES2020",
@@ -411,12 +660,12 @@ const playerTsconfigVanilla = JSON.stringify(
   2,
 );
 
-// Player: React
-export function playerReact(gameId) {
+// Controller: React
+export function controllerReact(gameId) {
   return {
     "package.json": JSON.stringify(
       {
-        name: "player",
+        name: "controller",
         private: true,
         type: "module",
         scripts: {
@@ -426,7 +675,7 @@ export function playerReact(gameId) {
         dependencies: {
           react: "^18.3.1",
           "react-dom": "^18.3.1",
-          "@smoregg/sdk": "^0.1.0",
+          "@smoregg/sdk": SDK_VERSION, // TODO: auto-detect or update on release
         },
         devDependencies: {
           "@types/react": "^18.3.0",
@@ -439,14 +688,15 @@ export function playerReact(gameId) {
       null,
       2,
     ),
-    "tsconfig.json": playerTsconfig,
+    "tsconfig.json": controllerTsconfig,
     "vite.config.ts": `import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 
 export default defineConfig({
+  base: './',
   plugins: [react()],
-  server: { port: 5174 },
-  build: { outDir: '../dist/player' },
+  server: { port: 5174, host: true },
+  build: { outDir: '../dist/controller' },
 });
 `,
     "index.html": `<!DOCTYPE html>
@@ -454,7 +704,7 @@ export default defineConfig({
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
-    <title>${gameId} - Player</title>
+    <title>${gameId} - Controller</title>
     <style>
       * { margin: 0; padding: 0; box-sizing: border-box; }
       html, body, #root {
@@ -471,32 +721,65 @@ export default defineConfig({
 </html>
 `,
     "src/main.tsx": `import { createRoot } from 'react-dom/client';
-import { IframeRoomProvider } from '@smoregg/sdk/iframe';
 import { App } from './App';
 
-createRoot(document.getElementById('root')!).render(
-  <IframeRoomProvider>
-    <App />
-  </IframeRoomProvider>
-);
+createRoot(document.getElementById('root')!).render(<App />);
 `,
-    "src/App.tsx": `import { useGamePlayer, TapButton } from '@smoregg/sdk/iframe';
-import { useState } from 'react';
+    "src/App.tsx": `import { createController } from '@smoregg/sdk';
+import type { Controller, ControllerInfo } from '@smoregg/sdk';
+import { useEffect, useRef, useState } from 'react';
+
+// You can also register listeners in config:
+// const controller = await createController({
+//   listeners: { 'game-state': (data) => { /* handle state */ } },
+// });
 
 export function App() {
+  const controllerRef = useRef<Controller | null>(null);
+  const [myIndex, setMyIndex] = useState(-1);
   const [count, setCount] = useState(0);
+  const [isReady, setIsReady] = useState(false);
+
+  useEffect(() => {
+    let mounted = true;
+
+    const init = async () => {
+      const controller = await createController({
+        debug: true,
+        // Lifecycle callbacks (uncomment to use):
+        // onControllerJoin: (playerIndex: number, info: ControllerInfo) => void — called when any player joins
+        // onControllerLeave: (playerIndex: number) => void — called when any player leaves
+        // onError: (error: SmoreError) => void — called on SDK errors
+      });
+      if (!mounted) {
+        controller.destroy();
+        return;
+      }
+
+      controllerRef.current = controller;
+      setMyIndex(controller.myIndex);
+      setIsReady(true);
 
-  const { emit, room } = useGamePlayer({
-    gameId: '${gameId}',
-    listeners: {
-      'score-update': (data: { score: number }) => {
+      controller.on('score-update', (data: { score: number }) => {
         setCount(data.score);
-      },
-    },
-  });
+      });
+
+      controller.on('personal-message', (data: { text: string }) => {
+        console.log('Received message:', data.text);
+      });
+    };
+
+    init();
+
+    return () => {
+      mounted = false;
+      controllerRef.current?.destroy();
+      controllerRef.current = null;
+    };
+  }, []);
 
   const handleTap = () => {
-    emit('tap', { timestamp: Date.now() });
+    controllerRef.current?.send('tap', { timestamp: Date.now() });
     setCount((c) => c + 1);
   };
 
@@ -507,14 +790,21 @@ export function App() {
       padding: 'env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left)',
       touchAction: 'manipulation', userSelect: 'none',
     }}>
+      {isReady && (
+        <div style={{ fontSize: '16px', opacity: 0.6 }}>Player {myIndex}</div>
+      )}
       <div style={{ fontSize: '48px', fontWeight: 'bold' }}>{count}</div>
-      <TapButton onTap={handleTap} style={{
-        width: '200px', height: '200px', borderRadius: '50%',
-        background: '#4f46e5', border: 'none', color: '#fff',
-        fontSize: '24px', fontWeight: 'bold', cursor: 'pointer',
-      }}>
+      <button
+        onPointerDown={handleTap}
+        style={{
+          width: '200px', height: '200px', borderRadius: '50%',
+          background: '#4f46e5', border: 'none', color: '#fff',
+          fontSize: '24px', fontWeight: 'bold', cursor: 'pointer',
+          WebkitTapHighlightColor: 'transparent',
+        }}
+      >
         TAP
-      </TapButton>
+      </button>
     </div>
   );
 }
@@ -522,12 +812,12 @@ export function App() {
   };
 }
 
-// Player: Vanilla JS
-export function playerVanilla(gameId) {
+// Controller: Vanilla JS
+export function controllerVanilla(gameId) {
   return {
     "package.json": JSON.stringify(
       {
-        name: "player",
+        name: "controller",
         private: true,
         type: "module",
         scripts: {
@@ -535,7 +825,7 @@ export function playerVanilla(gameId) {
           build: "tsc && vite build",
         },
         dependencies: {
-          "@smoregg/sdk": "^0.1.0",
+          "@smoregg/sdk": SDK_VERSION, // TODO: auto-detect or update on release
         },
         devDependencies: {
           typescript: "^5.5.0",
@@ -545,12 +835,13 @@ export function playerVanilla(gameId) {
       null,
       2,
     ),
-    "tsconfig.json": playerTsconfigVanilla,
+    "tsconfig.json": controllerTsconfigVanilla,
     "vite.config.ts": `import { defineConfig } from 'vite';
 
 export default defineConfig({
-  server: { port: 5174 },
-  build: { outDir: '../dist/player' },
+  base: './',
+  server: { port: 5174, host: true },
+  build: { outDir: '../dist/controller' },
 });
 `,
     "index.html": `<!DOCTYPE html>
@@ -558,7 +849,7 @@ export default defineConfig({
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
-    <title>${gameId} - Player</title>
+    <title>${gameId} - Controller</title>
     <style>
       * { margin: 0; padding: 0; box-sizing: border-box; }
       html, body {
@@ -573,6 +864,7 @@ export default defineConfig({
         display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 24px;
         padding: env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left);
       }
+      #player-info { font-size: 16px; opacity: 0.6; }
       #count { font-size: 48px; font-weight: bold; }
       #tap-btn {
         width: 200px; height: 200px; border-radius: 50%;
@@ -585,6 +877,7 @@ export default defineConfig({
   </head>
   <body>
     <div id="app">
+      <div id="player-info"></div>
       <div id="count">0</div>
       <button id="tap-btn">TAP</button>
     </div>
@@ -592,27 +885,1118 @@ export default defineConfig({
   </body>
 </html>
 `,
-    "src/main.ts": `import { createIframePlayer } from '@smoregg/sdk/iframe';
+    "src/main.ts": `import { createController } from '@smoregg/sdk';
+import type { Controller, ControllerInfo } from '@smoregg/sdk';
+
+// You can also register listeners in config:
+// const controller = await createController({
+//   listeners: { 'game-state': (data) => { /* handle state */ } },
+// });
 
 let count = 0;
+let controller: Controller;
+
+const playerInfoEl = document.getElementById('player-info')!;
 const countEl = document.getElementById('count')!;
 const tapBtn = document.getElementById('tap-btn')!;
 
-const player = createIframePlayer({
-  gameId: '${gameId}',
-  listeners: {
-    'score-update': (data: { score: number }) => {
-      count = data.score;
-      countEl.textContent = String(count);
-    },
-  },
-});
+async function init() {
+  controller = await createController({
+    debug: true,
+    // Lifecycle callbacks (uncomment to use):
+    // onControllerJoin: (playerIndex, info) => { console.log('Player joined:', playerIndex); },
+    // onControllerLeave: (playerIndex) => { console.log('Player left:', playerIndex); },
+    // onError: (error) => { console.error('SDK Error:', error.message); },
+  });
+
+  playerInfoEl.textContent = \`Player \${controller.myIndex}\`;
+
+  controller.on('score-update', (data: { score: number }) => {
+    count = data.score;
+    countEl.textContent = String(count);
+  });
+
+  controller.on('personal-message', (data: { text: string }) => {
+    console.log('Received message:', data.text);
+  });
+}
+
+init();
 
 tapBtn.addEventListener('pointerdown', () => {
-  player.emit('tap', { timestamp: Date.now() });
+  controller.send('tap', { timestamp: Date.now() });
   count++;
   countEl.textContent = String(count);
 });
 `,
   };
 }
+
+// ─── Dev Server templates ───
+
+export function devServer(gameId) {
+  return {
+    "dev/server.js": `/**
+ * S'MORE Dev Server - minimal Socket.IO relay for local development.
+ *
+ * Replicates the production genericRelay protocol:
+ *   Player -> Host: attach playerIndex, forward to host socket
+ *   Host -> All:    broadcast to all player sockets (no targetPlayerIndex)
+ *   Host -> One:    route to specific player, strip targetPlayerIndex
+ *
+ * System events (smore:*) are handled explicitly and never relayed.
+ */
+
+import express from 'express';
+import { createServer } from 'node:http';
+import { createServer as createTcpServer } from 'node:net';
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { Server } from 'socket.io';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { networkInterfaces } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ── Port detection ──
+
+function isPortFree(port) {
+  return new Promise((resolve) => {
+    const srv = createTcpServer();
+    srv.once('error', () => resolve(false));
+    srv.once('listening', () => srv.close(() => resolve(true)));
+    srv.listen(port);
+  });
+}
+
+async function findPort(preferred) {
+  for (let p = preferred; p < preferred + 100; p++) {
+    if (await isPortFree(p)) return p;
+  }
+  return new Promise((resolve) => {
+    const srv = createTcpServer();
+    srv.listen(0, () => {
+      const port = srv.address().port;
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+function getLocalIP() {
+  const nets = networkInterfaces();
+  for (const name of Object.keys(nets)) {
+    for (const net of nets[name]) {
+      if (net.family === 'IPv4' && !net.internal) return net.address;
+    }
+  }
+  return 'localhost';
+}
+
+// ── Room state ──
+
+function generateCode() {
+  const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+  let code = '';
+  for (let i = 0; i < 4; i++) code += chars[Math.floor(Math.random() * chars.length)];
+  return code;
+}
+
+const room = {
+  code: generateCode(),
+  hostSocketId: null,
+  players: [],       // { socketId, playerIndex, nickname, sessionId }
+  nextIndex: 0,
+  gameId: '',
+  status: 'waiting',
+};
+
+function toPlayerDTO(p) {
+  return { playerIndex: p.playerIndex, name: p.nickname, connected: p.connected !== undefined ? p.connected : true, character: null };
+}
+
+function toRoomDTO() {
+  return {
+    code: room.code,
+    players: room.players.map(toPlayerDTO),
+    maxPlayers: 12,
+    gameId: room.gameId,
+    status: room.status,
+    gameSelectionMode: false,
+  };
+}
+
+// ── Main ──
+
+async function main() {
+  const SERVER_PORT = await findPort(3000);
+  const SCREEN_PORT = await findPort(5173);
+  const CONTROLLER_PORT = await findPort(5174);
+
+  const app = express();
+  const server = createServer(app);
+  const io = new Server(server, {
+    cors: {
+      origin: true,
+      methods: ['GET', 'POST'],
+    },
+  });
+
+  // ── Serve dev harness & controller page ──
+
+  function servePage(filePath) {
+    return (_req, res) => {
+      let html = readFileSync(filePath, 'utf-8');
+      html = html.replace(/__LOCAL_IP__/g, localIP);
+      html = html.replace(/__SERVER_PORT__/g, String(SERVER_PORT));
+      html = html.replace(/__SCREEN_PORT__/g, String(SCREEN_PORT));
+      html = html.replace(/__CONTROLLER_PORT__/g, String(CONTROLLER_PORT));
+      res.type('html').send(html);
+    };
+  }
+
+  const localIP = getLocalIP();
+  app.get('/', servePage(join(__dirname, 'index.html')));
+  app.get('/controller', servePage(join(__dirname, 'controller.html')));
+
+  // ── Socket handling ──
+
+  io.on('connection', (socket) => {
+    console.log('  [connect] ' + socket.id);
+
+    // Screen (host) connects
+    // Note: smore:create matches production server's EVENT_NAMES.ROOM.CREATE
+    socket.on('smore:create', (data, callback) => {
+      // Reset room state for fresh start
+      room.players = [];
+      room.nextIndex = 0;
+      room.gameId = '';
+      room.status = 'waiting';
+      room.hostSocketId = socket.id;
+      socket.role = 'host';
+      socket.join(room.code);
+      console.log('  [host] Screen connected, room ' + room.code);
+      if (typeof callback === 'function') {
+        callback({ code: room.code, room: toRoomDTO() });
+      }
+    });
+
+    // Controller (player) joins
+    socket.on('smore:join', (data, callback) => {
+      const playerIndex = room.nextIndex++;
+      const sessionId = 'session-' + playerIndex;
+      const nickname = (data && data.nickname) || ('Player ' + (playerIndex + 1));
+
+      const player = { socketId: socket.id, playerIndex, nickname, sessionId };
+      room.players.push(player);
+
+      socket.role = 'player';
+      socket.playerIndex = playerIndex;
+      socket.sessionId = sessionId;
+      socket.join(room.code);
+
+      console.log('  [join] ' + nickname + ' (index ' + playerIndex + ')');
+
+      // Notify entire room (host + all controllers)
+      io.to(room.code).emit('smore:player-joined', {
+        player: toPlayerDTO(player),
+        room: toRoomDTO(),
+      });
+
+      if (typeof callback === 'function') {
+        callback({
+          success: true,
+          playerIndex,
+          sessionId,
+          roomCode: room.code,
+          player: toPlayerDTO(player),
+          room: toRoomDTO(),
+        });
+      }
+    });
+
+    // Game lifecycle
+    // NOTE: Dev server combines select-game + start-game for simplicity.
+    // Production server handles these as separate events.
+    socket.on('smore:select-game', (data) => {
+      room.gameId = (data && data.gameId) || '';
+      room.status = 'playing';
+      console.log('  [game] Selected: ' + room.gameId);
+      io.to(room.code).emit('smore:game-selected', { gameId: room.gameId, room: toRoomDTO() });
+      io.to(room.code).emit('smore:game-started', { gameId: room.gameId, room: toRoomDTO() });
+    });
+
+    socket.on('smore:start-game', (data) => {
+      room.status = 'playing';
+      console.log('  [game] Started');
+      io.to(room.code).emit('smore:game-started', { gameId: room.gameId, room: toRoomDTO() });
+    });
+
+    socket.on('smore:game-over', (data) => {
+      room.status = 'finished';
+      console.log('  [game] Game over');
+      io.to(room.code).emit('smore:game-over', data);
+    });
+
+    socket.on('smore:return-to-selection', () => {
+      room.status = 'waiting';
+      room.gameId = '';
+      console.log('  [game] Return to selection');
+      io.to(room.code).emit('smore:selection-returned', { room: toRoomDTO() });
+    });
+
+    // Dashboard reset
+    socket.on('smore:reset-room', (data, callback) => {
+      if (socket.role !== 'host') return;
+      // Emit kicked to all players (they will disconnect themselves)
+      for (const p of room.players) {
+        const ps = io.sockets.sockets.get(p.socketId);
+        if (ps) ps.emit('smore:kicked');
+      }
+      // Clear room state immediately (no setTimeout!)
+      room.players = [];
+      room.nextIndex = 0;
+      room.gameId = '';
+      room.status = 'waiting';
+      console.log('  [reset] Room reset by host');
+      if (typeof callback === 'function') callback({ success: true });
+    });
+
+    // ── Generic relay (the core protocol) ──
+    // Note: Rate limiting is not implemented in dev server. Production server applies rate limits.
+    // Note: Event name validation (EVENT_NAME_REGEX) is not implemented in dev server. SDK client-side validateEventName() provides primary validation.
+    socket.onAny((event, ...args) => {
+      // Skip system events - they are handled above
+      if (event.startsWith('smore:')) return;
+
+      const data = args[0];
+      const callback = typeof args[args.length - 1] === 'function' ? args[args.length - 1] : undefined;
+
+      if (socket.role === 'player') {
+        // Player -> Host: inject playerIndex, forward to host
+        if (!room.hostSocketId) {
+          if (callback) callback({ success: false, error: 'No host' });
+          return;
+        }
+
+        const payload = data && typeof data === 'object' ? data : (data !== undefined ? { data: data } : {});
+        io.to(room.hostSocketId).emit(event, {
+          ...payload,
+          playerIndex: socket.playerIndex,
+        });
+
+        if (callback) callback({ success: true });
+
+      } else if (socket.role === 'host') {
+        if (data && data.targetPlayerIndex !== undefined) {
+          // Host -> Specific Player: route by playerIndex, strip targetPlayerIndex
+          const target = room.players.find((p) => p.playerIndex === data.targetPlayerIndex);
+          if (target) {
+            const { targetPlayerIndex, ...rest } = data;
+            io.to(target.socketId).emit(event, rest);
+          }
+        } else {
+          // Host -> All Players: broadcast to room (excludes host)
+          socket.to(room.code).emit(event, data);
+        }
+      }
+    });
+
+    // Disconnect
+    // Dev server limitation: no reconnection support.
+    // Production server has a grace period + sessionId-based reconnect.
+    // Here, disconnect immediately removes the player (simplified for dev).
+    // This means we emit smore:player-left instead of smore:player-disconnected,
+    // because the player is permanently removed from the room.
+    socket.on('disconnect', () => {
+      if (socket.role === 'player') {
+        const idx = room.players.findIndex((p) => p.socketId === socket.id);
+        if (idx !== -1) {
+          const player = room.players[idx];
+          room.players.splice(idx, 1);
+          console.log('  [leave] Player ' + player.playerIndex + ' left');
+
+          // Notify entire room (host + all controllers)
+          // Dev server immediately removes players, so emit smore:player-left.
+          io.to(room.code).emit('smore:player-left', {
+            player: toPlayerDTO(player),
+            room: toRoomDTO(),
+          });
+        }
+      } else if (socket.role === 'host') {
+        console.log('  [host] Screen disconnected');
+        room.hostSocketId = null;
+      }
+    });
+  });
+
+  // ── Start ──
+
+  server.listen(SERVER_PORT, () => {
+    console.log('');
+    console.log("  \\x1b[1m\\x1b[35mS'MORE Dev Server\\x1b[0m");
+    console.log('');
+    console.log('  Room Code:   \\x1b[1m\\x1b[36m' + room.code + '\\x1b[0m');
+    console.log('');
+    console.log('  Dashboard:   \\x1b[36mhttp://localhost:' + SERVER_PORT + '\\x1b[0m');
+    console.log('  Controller:  \\x1b[36mhttp://' + localIP + ':' + SERVER_PORT + '/controller\\x1b[0m  (open on phone)');
+    console.log('');
+    console.log('  Screen app:  \\x1b[36mhttp://localhost:' + SCREEN_PORT + '\\x1b[0m');
+    console.log('  Controller:  \\x1b[36mhttp://localhost:' + CONTROLLER_PORT + '\\x1b[0m');
+    console.log('');
+  });
+
+  const ROOT = join(__dirname, '..');
+  const screenProc = spawn('npx', ['vite', '--port', String(SCREEN_PORT), '--host'], {
+    cwd: join(ROOT, 'screen'), stdio: ['ignore', 'pipe', 'pipe'], shell: true,
+  });
+  const controllerProc = spawn('npx', ['vite', '--port', String(CONTROLLER_PORT), '--host'], {
+    cwd: join(ROOT, 'controller'), stdio: ['ignore', 'pipe', 'pipe'], shell: true,
+  });
+  screenProc.stderr.on('data', (d) => { const s = d.toString().trim(); if (s) console.error('  \\x1b[33m[screen]\\x1b[0m ' + s); });
+  controllerProc.stderr.on('data', (d) => { const s = d.toString().trim(); if (s) console.error('  \\x1b[33m[controller]\\x1b[0m ' + s); });
+  function cleanup() { screenProc.kill(); controllerProc.kill(); process.exit(); }
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+}
+
+main();
+`,
+  };
+}
+
+export function devHarness(gameId) {
+  return {
+    "dev/index.html": `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>S'MORE Dev Server</title>
+  <script src="/socket.io/socket.io.js"><\/script>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { height: 100%; background: #0f0f0f; color: #e0e0e0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; overflow: hidden; }
+
+    /* Top bar */
+    .topbar {
+      height: 48px; display: flex; align-items: center; gap: 10px;
+      padding: 0 16px; background: #181818; border-bottom: 1px solid #2a2a2a;
+    }
+    .topbar-title { font-weight: 700; font-size: 14px; color: #fff; letter-spacing: -0.02em; white-space: nowrap; }
+    .topbar-title span { color: #a78bfa; }
+    .badge {
+      background: #a78bfa; color: #0f0f0f; font-weight: 700; font-size: 12px;
+      padding: 2px 8px; border-radius: 5px; letter-spacing: 0.06em; white-space: nowrap;
+    }
+    .badge-muted {
+      background: #2a2a2a; color: #888; font-weight: 600; font-size: 11px;
+      padding: 2px 8px; border-radius: 5px; white-space: nowrap;
+    }
+    .phase-badge {
+      font-weight: 600; font-size: 11px; padding: 2px 8px; border-radius: 5px;
+      white-space: nowrap; text-transform: uppercase; letter-spacing: 0.04em;
+    }
+    .phase-lobby { background: #1a3a1a; color: #4ade80; }
+    .phase-playing { background: #3a2a1a; color: #fbbf24; }
+    .phase-results { background: #1a1a3a; color: #818cf8; }
+    .topbar-spacer { flex: 1; }
+    .btn {
+      background: #2a2a2a; color: #e0e0e0; border: 1px solid #3a3a3a;
+      padding: 5px 12px; border-radius: 6px; font-size: 12px; cursor: pointer;
+      font-weight: 600; transition: background 0.15s; white-space: nowrap;
+    }
+    .btn:hover { background: #3a3a3a; }
+    .btn:disabled { opacity: 0.35; cursor: not-allowed; }
+    .btn:disabled:hover { background: #2a2a2a; }
+    .btn-primary { background: #4f46e5; border-color: #4f46e5; color: #fff; }
+    .btn-primary:hover { background: #4338ca; }
+    .btn-primary:disabled:hover { background: #4f46e5; }
+    .btn-danger { background: #dc2626; border-color: #dc2626; color: #fff; }
+    .btn-danger:hover { background: #b91c1c; }
+
+    /* Main layout */
+    .main { display: flex; height: calc(100% - 48px); }
+    .screen-panel {
+      flex: 1; position: relative; border-right: 1px solid #2a2a2a;
+      display: flex; align-items: center; justify-content: center; background: #111;
+      overflow: hidden;
+    }
+    .screen-panel iframe {
+      border: none; border-radius: 8px;
+      box-shadow: 0 4px 24px rgba(0, 0, 0, 0.5), 0 0 0 1px rgba(255,255,255,0.05);
+    }
+    .controller-panel {
+      width: 320px; min-width: 320px; max-width: 320px;
+      display: flex; flex-direction: column;
+      padding: 8px; overflow-y: auto; background: #141414;
+    }
+    .controller-grid {
+      display: grid; grid-template-columns: 1fr 1fr; gap: 6px;
+    }
+    .controller-slot {
+      position: relative; border: 1px solid #2a2a2a; border-radius: 8px;
+      overflow: hidden; background: #0f0f0f; aspect-ratio: 9 / 16;
+    }
+    .controller-slot iframe { width: 100%; height: 100%; border: none; display: block; }
+    .controller-label {
+      position: absolute; top: 4px; left: 4px; font-size: 10px;
+      background: rgba(0,0,0,0.75); color: #888; padding: 1px 6px; border-radius: 3px;
+      pointer-events: none; z-index: 1; white-space: nowrap;
+    }
+    .status-dot {
+      width: 6px; height: 6px; border-radius: 50%; display: inline-block;
+      margin-right: 4px; vertical-align: middle;
+    }
+    .status-connected { background: #22c55e; }
+    .status-disconnected { background: #ef4444; }
+    .status-pending { background: #eab308; }
+    .empty-state {
+      display: flex; align-items: center; justify-content: center;
+      height: 200px; color: #444; font-size: 12px; text-align: center;
+      padding: 24px; line-height: 1.5;
+    }
+    .placeholder {
+      display: flex; align-items: center; justify-content: center;
+      height: 100%; color: #555; font-size: 14px;
+    }
+
+    /* Modal */
+    .modal-overlay {
+      position: fixed; inset: 0; background: rgba(0,0,0,0.75);
+      display: flex; align-items: center; justify-content: center; z-index: 100;
+    }
+    .modal-overlay.hidden { display: none; }
+    .modal {
+      background: #1e1e1e; border: 1px solid #3a3a3a; border-radius: 16px;
+      padding: 32px; max-width: 400px; width: 90%; text-align: center;
+    }
+    .modal h2 { font-size: 18px; margin-bottom: 16px; color: #fff; }
+    .modal img { margin: 16px auto; display: block; border-radius: 8px; }
+    .modal .url-text {
+      font-size: 13px; color: #a78bfa; word-break: break-all;
+      background: #2a2a2a; padding: 8px 12px; border-radius: 8px; margin: 12px 0;
+      user-select: all;
+    }
+    .modal .btn { margin-top: 12px; }
+  </style>
+</head>
+<body>
+
+<div class="topbar">
+  <div class="topbar-title"><span>S'MORE</span> Dev</div>
+  <div class="badge" id="roomCode">----</div>
+  <div class="badge-muted" id="playerCount">0 players</div>
+  <div class="phase-badge phase-lobby" id="phaseBadge">Lobby</div>
+  <div class="topbar-spacer"></div>
+  <button class="btn btn-danger" id="endGameBtn" style="display:none;">End Game</button>
+  <button class="btn" id="resetBtn">Reset</button>
+  <button class="btn btn-primary" id="addPlayerBtn">+ Player</button>
+  <button class="btn" id="phoneBtn">Phone</button>
+</div>
+
+<div class="main">
+  <div class="screen-panel" id="screenPanel">
+    <div class="placeholder" id="screenPlaceholder">Waiting for screen app (localhost:5173)...</div>
+  </div>
+  <div class="controller-panel" id="controllerPanel">
+    <div class="empty-state" id="emptyState">Press '+ Player' to add controllers</div>
+    <div class="controller-grid" id="controllerGrid"></div>
+  </div>
+</div>
+
+<div class="modal-overlay hidden" id="phoneModal">
+  <div class="modal">
+    <h2>Open on Phone</h2>
+    <p style="color:#888;font-size:13px;margin-bottom:8px;">Scan the QR code or enter the URL on your phone.</p>
+    <img id="qrImage" width="200" height="200" alt="QR Code" />
+    <div class="url-text" id="phoneUrl"></div>
+    <button class="btn" id="closeModalBtn">Close</button>
+  </div>
+</div>
+
+<script>
+(function() {
+  // ── State ──
+  var SCREEN_URL = 'http://' + location.hostname + ':' + __SCREEN_PORT__;
+  var CONTROLLER_URL = 'http://' + location.hostname + ':' + __CONTROLLER_PORT__;
+  var roomCode = '';
+  var players = [];         // Local iframe controllers only
+  var serverPlayers = [];   // Authoritative full list from server (includes phone players)
+  var screenSocket = null;
+  var screenIframe = null;
+  var screenReady = false;
+  var gamePhase = 'lobby';
+
+  // ── DOM refs ──
+  var roomCodeEl = document.getElementById('roomCode');
+  var playerCountEl = document.getElementById('playerCount');
+  var phaseBadgeEl = document.getElementById('phaseBadge');
+  var screenPanel = document.getElementById('screenPanel');
+  var screenPlaceholder = document.getElementById('screenPlaceholder');
+  var controllerPanel = document.getElementById('controllerPanel');
+  var controllerGrid = document.getElementById('controllerGrid');
+  var emptyState = document.getElementById('emptyState');
+  var addPlayerBtn = document.getElementById('addPlayerBtn');
+  var endGameBtn = document.getElementById('endGameBtn');
+  var resetBtn = document.getElementById('resetBtn');
+
+  // ── Phase management ──
+  function setPhase(phase) {
+    if (phase !== 'lobby' && phase !== 'playing' && phase !== 'results') return;
+    gamePhase = phase;
+    phaseBadgeEl.textContent = phase.charAt(0).toUpperCase() + phase.slice(1);
+    phaseBadgeEl.className = 'phase-badge phase-' + phase;
+    addPlayerBtn.disabled = (phase === 'playing');
+    endGameBtn.style.display = (phase === 'playing') ? 'inline-block' : 'none';
+  }
+
+  // ── Helpers ──
+  function updatePlayerCount() {
+    var count = serverPlayers.length;
+    playerCountEl.textContent = count + ' player' + (count !== 1 ? 's' : '');
+  }
+
+  function updateEmptyState() {
+    emptyState.style.display = players.length === 0 ? 'flex' : 'none';
+  }
+
+  function getPlayerList() {
+    return serverPlayers;
+  }
+
+  function broadcastUpdate() {
+    var payload = { players: serverPlayers };
+    if (screenIframe && screenReady) {
+      screenIframe.contentWindow.postMessage({ type: '_bridge:update', payload: payload }, '*');
+    }
+    players.forEach(function(p) {
+      if (p.iframe && p.ready) {
+        p.iframe.contentWindow.postMessage({ type: '_bridge:update', payload: payload }, '*');
+      }
+    });
+  }
+
+  // ── Screen resize (16:9 fit) ──
+  function resizeScreen() {
+    if (!screenIframe) return;
+    var rect = screenPanel.getBoundingClientRect();
+    var pw = rect.width - 48;
+    var ph = rect.height - 48;
+    if (pw <= 0 || ph <= 0) return;
+    var w, h;
+    if (pw / ph > 16 / 9) {
+      h = ph; w = Math.round(h * 16 / 9);
+    } else {
+      w = pw; h = Math.round(w * 9 / 16);
+    }
+    screenIframe.style.width = w + 'px';
+    screenIframe.style.height = h + 'px';
+  }
+
+  window.addEventListener('resize', resizeScreen);
+
+  // ── Screen setup ──
+  function initScreen(onRoomCreated) {
+    screenSocket = io();
+
+    screenSocket.on('connect', function() {
+      screenSocket.emit('smore:create', {}, function(res) {
+        roomCode = res.code;
+        roomCodeEl.textContent = roomCode;
+        if (onRoomCreated) onRoomCreated();
+      });
+    });
+
+    screenIframe = document.createElement('iframe');
+    screenIframe.src = SCREEN_URL;
+    screenIframe.sandbox = 'allow-scripts allow-same-origin';
+    screenPlaceholder.style.display = 'none';
+    screenPanel.appendChild(screenIframe);
+
+    setTimeout(resizeScreen, 100);
+
+    // Bridge: screen socket.onAny -> iframe smore:event (game events only)
+    screenSocket.onAny(function(event) {
+      if (event.startsWith('smore:')) return;
+      var data = arguments[1];
+      if (screenIframe && screenReady) {
+        screenIframe.contentWindow.postMessage({
+          type: '_bridge:event',
+          payload: { event: event, data: data },
+        }, '*');
+      }
+    });
+
+    // Forward specific smore: system events to screen iframe
+    var screenSysEvents = [
+      'smore:player-joined', 'smore:player-left', 'smore:player-disconnected', 'smore:player-reconnected',
+      'smore:player-character-updated', 'smore:rate-limited', 'smore:game-over'
+    ];
+    screenSysEvents.forEach(function(sysEvent) {
+      screenSocket.on(sysEvent, function(data) {
+        if (screenIframe && screenReady) {
+          screenIframe.contentWindow.postMessage({
+            type: '_bridge:event',
+            payload: { event: sysEvent, data: data },
+          }, '*');
+        }
+
+        // Sync authoritative player list from server (production format: data.room.players)
+        if (data && data.room && data.room.players) {
+          serverPlayers = data.room.players;
+          updatePlayerCount();
+          broadcastUpdate();
+        }
+      });
+    });
+  }
+
+  // ── Controller setup ──
+  function addController() {
+    var controllerSocket = io({ forceNew: true });
+    var idx = players.length;
+    var nickname = 'Player ' + (idx + 1);
+
+    var slot = document.createElement('div');
+    slot.className = 'controller-slot';
+
+    var label = document.createElement('div');
+    label.className = 'controller-label';
+    label.innerHTML = '<span class="status-dot status-pending"></span>P' + (idx + 1);
+    slot.appendChild(label);
+
+    var iframe = document.createElement('iframe');
+    iframe.src = CONTROLLER_URL;
+    iframe.sandbox = 'allow-scripts allow-same-origin';
+    slot.appendChild(iframe);
+    controllerGrid.appendChild(slot);
+
+    var playerData = {
+      playerIndex: -1, nickname: nickname, sessionId: '',
+      socket: controllerSocket, iframe: iframe, label: label, slot: slot,
+      connected: false, ready: false,
+    };
+    players.push(playerData);
+    updatePlayerCount();
+    updateEmptyState();
+
+    controllerSocket.on('connect', function() {
+      controllerSocket.emit('smore:join', { nickname: nickname, roomCode: roomCode }, function(res) {
+        if (!res || !res.success) return;
+        playerData.playerIndex = res.playerIndex;
+        playerData.sessionId = res.sessionId;
+        playerData.connected = true;
+        label.innerHTML = '<span class="status-dot status-connected"></span>P' + (res.playerIndex + 1);
+      });
+    });
+
+    controllerSocket.on('disconnect', function() {
+      playerData.connected = false;
+      label.innerHTML = '<span class="status-dot status-disconnected"></span>P' + (playerData.playerIndex >= 0 ? playerData.playerIndex + 1 : '?');
+    });
+
+    // Bridge: controller socket.onAny -> iframe smore:event (game events only)
+    controllerSocket.onAny(function(event) {
+      if (event.startsWith('smore:')) return;
+      var data = arguments[1];
+      if (iframe && playerData.ready) {
+        iframe.contentWindow.postMessage({
+          type: '_bridge:event',
+          payload: { event: event, data: data },
+        }, '*');
+      }
+    });
+
+    // Forward system events to controller iframe
+    var ctrlSysEvents = [
+      'smore:game-over',
+      'smore:player-joined', 'smore:player-left', 'smore:player-disconnected', 'smore:player-reconnected',
+      'smore:player-character-updated', 'smore:rate-limited'
+    ];
+    ctrlSysEvents.forEach(function(sysEvent) {
+      controllerSocket.on(sysEvent, function(data) {
+        if (iframe && playerData.ready) {
+          iframe.contentWindow.postMessage({
+            type: '_bridge:event',
+            payload: { event: sysEvent, data: data },
+          }, '*');
+        }
+      });
+    });
+  }
+
+  // ── postMessage listener (from all iframes) ──
+  window.addEventListener('message', function(e) {
+    var msg = e.data;
+    if (!msg || typeof msg !== 'object' || typeof msg.type !== 'string') return;
+    if (!msg.type.startsWith('_bridge:')) return;
+
+    if (screenIframe && e.source === screenIframe.contentWindow) {
+      handleScreenMessage(msg);
+    } else {
+      var player = players.find(function(p) { return p.iframe && e.source === p.iframe.contentWindow; });
+      if (player) handleControllerMessage(msg, player);
+    }
+  });
+
+  function handleScreenMessage(msg) {
+    if (msg.type === '_bridge:ready') {
+      screenReady = true;
+      screenIframe.contentWindow.postMessage({
+        type: '_bridge:init',
+        payload: {
+          side: 'host',
+          roomCode: roomCode,
+          players: getPlayerList(),
+        },
+      }, '*');
+      return;
+    }
+
+    if (msg.type === '_bridge:emit') {
+      var event = msg.payload.event;
+      var data = msg.payload.data;
+      var ackId = msg.payload.ackId;
+
+      // Phase tracking from screen messages
+      if (data && typeof data === 'object' && data.phase) {
+        if (data.phase === 'lobby' || data.phase === 'playing' || data.phase === 'results') {
+          setPhase(data.phase);
+        }
+      }
+
+      // Intercept game-over to broadcast via system event and update phase
+      if (event === 'smore:game-over') {
+        setPhase('results');
+        screenSocket.emit('smore:game-over', data);
+        return;
+      }
+
+      // Block smore:* events from crossing the bridge
+      if (event.startsWith('smore:')) return;
+
+      if (ackId) {
+        screenSocket.emit(event, data, function(response) {
+          screenIframe.contentWindow.postMessage({ type: '_bridge:ack', payload: { ackId: ackId, data: response } }, '*');
+        });
+      } else {
+        screenSocket.emit(event, data);
+      }
+    }
+  }
+
+  function handleControllerMessage(msg, player) {
+    if (msg.type === '_bridge:ready') {
+      player.ready = true;
+      player.iframe.contentWindow.postMessage({
+        type: '_bridge:init',
+        payload: {
+          side: 'player',
+          roomCode: roomCode,
+          players: getPlayerList(),
+          myIndex: player.playerIndex,
+        },
+      }, '*');
+      return;
+    }
+
+    if (msg.type === '_bridge:emit') {
+      var event = msg.payload.event;
+      var data = msg.payload.data;
+      var ackId = msg.payload.ackId;
+
+      // Phase tracking from controller messages
+      if (event === 'start-game' || event === 'start') {
+        setPhase('playing');
+      }
+      if (event === 'play-again' || event === 'restart') {
+        setPhase('lobby');
+      }
+
+      // Block smore:* events
+      if (event.startsWith('smore:')) return;
+
+      if (ackId) {
+        player.socket.emit(event, data, function(response) {
+          player.iframe.contentWindow.postMessage({ type: '_bridge:ack', payload: { ackId: ackId, data: response } }, '*');
+        });
+      } else {
+        player.socket.emit(event, data);
+      }
+    }
+  }
+
+  // ── End Game ──
+  function endGame() {
+    // Broadcast phase-change to ALL controllers (including phone) via server relay
+    screenSocket.emit('phase-change', { phase: 'lobby' });
+
+    // Reload screen iframe
+    if (screenIframe) {
+      screenReady = false;
+      screenIframe.src = SCREEN_URL;
+    }
+    // Reload local controller iframes (phone controllers get the broadcast above)
+    players.forEach(function(p) {
+      p.ready = false;
+      if (p.iframe) {
+        p.iframe.src = CONTROLLER_URL;
+      }
+    });
+    setPhase('lobby');
+  }
+
+  // ── Reset ──
+  function resetAll() {
+    // 1. Disconnect all local iframe player sockets
+    players.forEach(function(p) {
+      if (p.socket) p.socket.disconnect();
+    });
+    players = [];
+    serverPlayers = [];
+
+    // 2. Clear UI
+    updatePlayerCount();
+    controllerGrid.innerHTML = '';
+    updateEmptyState();
+    roomCode = '';
+    roomCodeEl.textContent = '----';
+    setPhase('lobby');
+
+    // 3. Remove old screen iframe
+    if (screenIframe) {
+      screenIframe.remove();
+      screenIframe = null;
+      screenReady = false;
+    }
+
+    // 4. Tell dev server to reset room (disconnects all phone player sockets)
+    //    Then disconnect host and re-initialize fresh
+    var oldSocket = screenSocket;
+    screenSocket = null;
+    if (oldSocket) {
+      oldSocket.emit('smore:reset-room', {}, function() {
+        oldSocket.disconnect();
+        initScreen(function() { addController(); });
+      });
+      // Fallback if callback doesn't fire
+      setTimeout(function() {
+        if (!screenSocket) {
+          oldSocket.disconnect();
+          initScreen(function() { addController(); });
+        }
+      }, 1000);
+    } else {
+      initScreen(function() { addController(); });
+    }
+  }
+
+  // ── Button handlers ──
+  addPlayerBtn.addEventListener('click', function() {
+    if (!addPlayerBtn.disabled) addController();
+  });
+
+  endGameBtn.addEventListener('click', endGame);
+  resetBtn.addEventListener('click', resetAll);
+
+  document.getElementById('phoneBtn').addEventListener('click', function() {
+    var phoneUrl = 'http://__LOCAL_IP__:' + __SERVER_PORT__ + '/controller';
+    document.getElementById('phoneUrl').textContent = phoneUrl;
+    // Note: QR code generation requires external service (api.qrserver.com)
+    // If offline, the URL text below can be manually entered on the phone
+    document.getElementById('qrImage').src =
+      'https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=' + encodeURIComponent(phoneUrl);
+    document.getElementById('qrImage').onerror = function() { this.style.display='none'; };
+    document.getElementById('phoneModal').classList.remove('hidden');
+  });
+
+  document.getElementById('closeModalBtn').addEventListener('click', function() {
+    document.getElementById('phoneModal').classList.add('hidden');
+  });
+
+  // ── Boot ──
+  initScreen();
+  setTimeout(function() { addController(); }, 500);
+})();
+<\/script>
+</body>
+</html>
+`,
+  };
+}
+
+export function devControllerPage(gameId) {
+  return {
+    "dev/controller.html": `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+  <title>S'MORE Controller</title>
+  <script src="/socket.io/socket.io.js"><\/script>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body {
+      width: 100%; height: 100vh; height: 100dvh;
+      background: #0f0f0f; color: #fff; font-family: sans-serif;
+      overflow: hidden; overscroll-behavior: none;
+    }
+    .container {
+      position: fixed; inset: 0;
+      padding: env(safe-area-inset-top) env(safe-area-inset-right)
+               env(safe-area-inset-bottom) env(safe-area-inset-left);
+      touch-action: manipulation; user-select: none;
+      -webkit-user-select: none; -webkit-touch-callout: none;
+      -webkit-tap-highlight-color: transparent;
+    }
+    .loading {
+      display: flex; flex-direction: column; align-items: center; justify-content: center;
+      height: 100%; gap: 16px;
+    }
+    .loading-text { font-size: 16px; color: #888; }
+    .loading .spinner {
+      width: 32px; height: 32px; border: 3px solid #333; border-top-color: #a78bfa;
+      border-radius: 50%; animation: spin 0.8s linear infinite;
+    }
+    @keyframes spin { to { transform: rotate(360deg); } }
+    iframe {
+      position: fixed; inset: 0; width: 100%; height: 100%;
+      border: none; background: #0f0f0f;
+    }
+    iframe.hidden { display: none; }
+  </style>
+</head>
+<body>
+
+<div class="container" id="loadingScreen">
+  <div class="loading">
+    <div class="spinner"></div>
+    <div class="loading-text">Connecting...</div>
+  </div>
+</div>
+
+<iframe id="controllerFrame" class="hidden" sandbox="allow-scripts allow-same-origin"></iframe>
+
+<script>
+(function() {
+  var CONTROLLER_URL = 'http://' + location.hostname + ':' + __CONTROLLER_PORT__;
+  var loadingScreen = document.getElementById('loadingScreen');
+  var iframe = document.getElementById('controllerFrame');
+
+  var socket = null;
+  var playerIndex = -1;
+  var sessionId = '';
+  var roomCode = '';
+  var players = [];
+  var iframeReady = false;
+
+  // Connect and join room
+  socket = io();
+
+  socket.on('connect', function() {
+    var nickname = 'Phone Player';
+    socket.emit('smore:join', { nickname: nickname }, function(res) {
+      if (!res || !res.success) return;
+      playerIndex = res.playerIndex;
+      sessionId = res.sessionId;
+      roomCode = res.roomCode;
+      players = (res.room && res.room.players) || [];
+
+      // Show iframe
+      iframe.src = CONTROLLER_URL;
+      iframe.classList.remove('hidden');
+      loadingScreen.style.display = 'none';
+    });
+  });
+
+  // Bridge: socket -> iframe (game events only)
+  socket.onAny(function(event) {
+    if (event.startsWith('smore:')) return;
+    var data = arguments[1];
+    if (iframe && iframeReady) {
+      iframe.contentWindow.postMessage({
+        type: '_bridge:event',
+        payload: { event: event, data: data },
+      }, '*');
+    }
+  });
+
+  // Forward system events to iframe
+  var sysEvents = [
+    'smore:game-over',
+    'smore:player-joined', 'smore:player-left', 'smore:player-disconnected', 'smore:player-reconnected',
+    'smore:player-character-updated', 'smore:rate-limited'
+  ];
+  sysEvents.forEach(function(sysEvent) {
+    socket.on(sysEvent, function(data) {
+      if (iframe && iframeReady) {
+        iframe.contentWindow.postMessage({
+          type: '_bridge:event',
+          payload: { event: sysEvent, data: data },
+        }, '*');
+      }
+      // Update local player list (production format: data.room.players)
+      if (data && data.room && data.room.players) {
+        players = data.room.players;
+      }
+    });
+  });
+
+  // Handle kicked (room reset by host)
+  socket.on('smore:kicked', function() {
+    // Stop reconnection
+    socket.io.opts.reconnection = false;
+    socket.disconnect();
+    // Replace page with disconnected screen
+    document.body.innerHTML = '<div style="position:fixed;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center;background:#0f0f0f;color:#fff;font-family:sans-serif;gap:16px;padding:24px;text-align:center;">' +
+      '<div style="font-size:48px;">👋</div>' +
+      '<div style="font-size:20px;font-weight:700;">Room Closed</div>' +
+      '<div style="font-size:14px;color:#888;">The host has reset the room.</div>' +
+      '</div>';
+  });
+
+  // Bridge: iframe -> socket (postMessage)
+  window.addEventListener('message', function(e) {
+    if (e.source !== iframe.contentWindow) return;
+    var msg = e.data;
+    if (!msg || typeof msg !== 'object' || typeof msg.type !== 'string') return;
+    if (!msg.type.startsWith('_bridge:')) return;
+
+    if (msg.type === '_bridge:ready') {
+      iframeReady = true;
+      iframe.contentWindow.postMessage({
+        type: '_bridge:init',
+        payload: {
+          side: 'player',
+          roomCode: roomCode,
+          players: players,
+          myIndex: playerIndex,
+        },
+      }, '*');
+    }
+
+    if (msg.type === '_bridge:emit') {
+      var event = msg.payload.event;
+      var data = msg.payload.data;
+      var ackId = msg.payload.ackId;
+
+      // Block smore:* events
+      if (event.startsWith('smore:')) return;
+
+      if (ackId) {
+        socket.emit(event, data, function(response) {
+          iframe.contentWindow.postMessage({ type: '_bridge:ack', payload: { ackId: ackId, data: response } }, '*');
+        });
+      } else {
+        socket.emit(event, data);
+      }
+    }
+  });
+})();
+<\/script>
+</body>
+</html>
+`,
+  };
+}