star-sdk-cli 0.1.13 → 0.1.15

package/dist/cli.mjs

@@ -80,7 +80,39 @@ Star.game(ctx => {
 
 ## Common Patterns
 
-### Game Over -> Submit Score -> Show Leaderboard
+### Game Over Screen with Leaderboard
+
+Use DOM buttons (via \`ui.render()\` + \`on()\`) for all interactive UI \u2014 never draw buttons on canvas:
+
+\`\`\`javascript
+// UI button handler (register once \u2014 survives ui.render calls)
+ctx.on('click', '#lb-btn', () => Star.leaderboard.show());
+ctx.on('click', '#restart-btn', () => startGame());
+
+// Gameplay tap handler (single handler, state-based)
+canvas.addEventListener('pointerdown', () => {
+  if (state === 'playing') { jump(); }
+});
+
+function endGame() {
+  state = 'gameover';
+  Star.leaderboard.submit(score);
+  ctx.ui.render(\`
+    <div class="h-full flex flex-col items-center justify-center text-white">
+      <div class="text-3xl font-bold mb-2">GAME OVER</div>
+      <div class="text-6xl font-bold mb-6">\${score}</div>
+      <button id="lb-btn" class="px-6 py-3 mb-4 bg-purple-600 rounded-lg font-bold">
+        VIEW LEADERBOARD
+      </button>
+      <button id="restart-btn" class="px-6 py-3 bg-gray-700 rounded-lg">
+        PLAY AGAIN
+      </button>
+    </div>
+  \`);
+}
+\`\`\`
+
+### Submit Score Only (No UI)
 
 \`\`\`javascript
 function gameOver(finalScore) {
@@ -127,6 +159,8 @@ canvas.onclick = (e) => {
 - **Don't** use \`setInterval\` for game loops - use \`ctx.loop()\`
 - **Don't** destructure Star - use \`Star.audio\`, \`Star.leaderboard\`, etc.
 - **Don't** invent audio preset names - only 17 exist (see audio.md)
+- **Don't** draw buttons on canvas (fillRect + hit-test) \u2014 use \`ui.render()\` with HTML \`<button>\` elements + \`on()\` for clicks. Canvas-drawn "buttons" conflict with tap handlers and have no hover/focus states.
+- **Don't** register multiple \`canvas.addEventListener('pointerdown', ...)\` handlers \u2014 use ONE handler with state-based logic. Use \`on()\` for UI button clicks.
 
 ## Audio Presets (Full List)
 
@@ -143,9 +177,9 @@ import Star from 'star-sdk';
 Star.init({ gameId: '<gameId from .starrc>' }); // run: npx star-sdk init
 
 Star.game(ctx => {
-  const { canvas, width, height, ctx: c } = ctx;
+  const { canvas, width, height, ctx: c, ui, on } = ctx;
   let score = 0;
-  let gameOver = false;
+  let state = 'playing';
   let playerY = height / 2;
   let obstacles = [];
 
@@ -157,13 +191,52 @@ Star.game(ctx => {
 
   // Spawn obstacles
   setInterval(() => {
-    if (!gameOver) {
+    if (state === 'playing') {
       obstacles.push({ x: width, y: Math.random() * height, passed: false });
     }
   }, 2000);
 
+  // Gameplay input \u2014 ONE handler, state-based
+  canvas.addEventListener('pointerdown', () => {
+    if (state === 'playing') {
+      playerY -= 50;
+      Star.audio.play('jump');
+    }
+  });
+
+  // UI button clicks \u2014 use on() for DOM buttons, not canvas hit-testing
+  on('click', '#lb-btn', () => Star.leaderboard.show());
+  on('click', '#restart-btn', () => startGame());
+
+  function startGame() {
+    state = 'playing';
+    score = 0;
+    playerY = height / 2;
+    obstacles = [];
+    ui.render(''); // Clear game-over UI
+  }
+
+  function endGame() {
+    state = 'gameover';
+    Star.audio.play('hurt');
+    Star.leaderboard.submit(score);
+    // Game-over UI with DOM buttons (not canvas-drawn)
+    ui.render(\`
+      <div class="h-full flex flex-col items-center justify-center text-white">
+        <div class="text-3xl font-bold mb-2">GAME OVER</div>
+        <div class="text-6xl font-bold mb-6">\${score}</div>
+        <button id="lb-btn" class="px-6 py-3 mb-4 bg-purple-600 rounded-lg font-bold">
+          VIEW LEADERBOARD
+        </button>
+        <button id="restart-btn" class="px-6 py-3 bg-gray-700 rounded-lg">
+          PLAY AGAIN
+        </button>
+      </div>
+    \`);
+  }
+
   ctx.loop((dt) => {
-    if (gameOver) return;
+    if (state !== 'playing') return;
 
     // Clear
     c.fillStyle = '#111827';
@@ -172,24 +245,15 @@ Star.game(ctx => {
     // Update obstacles
     obstacles.forEach(obs => {
       obs.x -= 200 * dt;
-
-      // Score when passed
       if (!obs.passed && obs.x < 50) {
         obs.passed = true;
         score += 10;
         Star.audio.play('coin');
       }
-
-      // Collision
       if (Math.abs(obs.x - 50) < 20 && Math.abs(obs.y - playerY) < 30) {
-        gameOver = true;
-        Star.audio.play('hurt');
-        Star.leaderboard.submit(score);
-        Star.leaderboard.show();
+        endGame();
       }
     });
-
-    // Remove off-screen
     obstacles = obstacles.filter(o => o.x > -20);
 
     // Draw player
@@ -209,14 +273,6 @@ Star.game(ctx => {
     c.font = '24px sans-serif';
     c.fillText(\`Score: \${score}\`, 20, 40);
   });
-
-  // Jump on click/tap
-  canvas.onclick = () => {
-    if (!gameOver) {
-      playerY -= 50;
-      Star.audio.play('jump');
-    }
-  };
 });
 \`\`\`
 
@@ -423,26 +479,24 @@ game(({ ctx, width, height, on, loop, ui, canvas }) => {
   });
 
   // 2. Render HTML to the safe UI overlay
-  //    UI is interactive by default (scroll, buttons work)
-  //    Adding canvas.addEventListener makes UI click-through automatically
   ui.render(\`
     <div class="absolute top-4 left-4 text-white">
-      <button id="start-btn" class="px-4 py-2 bg-blue-500 rounded pointer-events-auto">
+      <button id="start-btn" class="px-4 py-2 bg-blue-500 rounded">
         Click Me
       </button>
     </div>
   \`);
 
-  // 3. Listen for button clicks
+  // 3. Listen for button clicks \u2014 on() auto-enables pointer-events for the target
   on('click', '#start-btn', () => {
     console.log('Button clicked!');
   });
 
-  // 4. For canvas games: listen for taps on canvas
-  //    This automatically makes UI click-through (taps pass through to canvas)
-  //    Buttons with pointer-events-auto still work
+  // 4. Gameplay taps \u2014 use canvas.addEventListener for game mechanics only
+  //    For buttons/menus, use ui.render() + on() above
+  //    The SDK auto-suppresses this handler when a UI button is clicked
   canvas.addEventListener('pointerdown', (e) => {
-    console.log('Canvas/screen tapped!', e);
+    console.log('Gameplay tap!', e);
   });
 });
 \`\`\`
@@ -470,7 +524,9 @@ The 2D drawing context. Its transform is already scaled for DPR. You **always dr
 
 The \`<canvas>\` element itself.
 
-  - **Use this for gameplay input listeners** (e.g., \`pointerdown\`, \`pointermove\`).
+  - **Use this for gameplay input** (e.g., \`pointerdown\` for tap-to-jump, \`pointermove\` for aiming).
+  - **For buttons and menus, use \`ui.render()\` + \`on()\` instead** \u2014 HTML buttons get hover states, touch targets, accessibility, and never conflict with gameplay handlers.
+  - Use ONE \`addEventListener\` handler with state-based logic. Multiple pointerdown handlers cause ordering bugs.
 
 ### \`width: number\` (getter)
 
@@ -505,7 +561,7 @@ A safe manager for your HTML overlay, stacked on top of the canvas.
   - \`ui.el(selector)\`: Scoped \`querySelector\` for the UI root.
   - \`ui.all(selector)\`: Scoped \`querySelectorAll\` for the UI root.
 
-**Auto-detection:** When you add \`canvas.addEventListener('pointerdown', ...)\`, the SDK automatically makes UI click-through so taps reach the canvas. Buttons with \`pointer-events-auto\` still work.
+**Auto-detection:** When you add \`canvas.addEventListener('pointerdown', ...)\`, the SDK automatically makes UI click-through so taps reach the canvas. Elements targeted by \`on()\` are automatically interactive \u2014 no extra CSS classes needed. Native \`<button>\` and \`<a>\` elements are also always interactive.
 
 ### Cursor Management
 
@@ -712,6 +768,8 @@ game(({ ctx, width, height, loop, toStagePoint, canvas }) => {
 
 ### Recipe 5: Complex Game with Canvas + UI + Events (like FLOW)
 
+**Key pattern:** Canvas for gameplay input, DOM buttons for UI. Never draw buttons on canvas.
+
 \`\`\`ts
 import { game } from 'star-canvas';
 import { createLeaderboard } from 'star-leaderboard';
@@ -722,24 +780,20 @@ game(({ ctx, width, height, loop, ui, on, canvas, toStagePoint }) => {
   let score = 0;
   let state = 'menu';
 
-  function handleTap() {
-    if (state === 'menu' || state === 'gameover') {
-      startGame();
-    } else if (state === 'playing') {
+  // 1. ONE gameplay tap handler \u2014 state-based logic, no button hit-testing
+  canvas.addEventListener('pointerdown', () => {
+    if (state === 'menu') startGame();
+    else if (state === 'playing') {
       // ... (player float logic) ...
     }
-  }
-
-  // 1. Listen for screen taps - this makes UI click-through automatically
-  canvas.addEventListener('pointerdown', handleTap);
-
-  // 2. Listen for button clicks - buttons need pointer-events-auto
-  on('click', '#leaderboard-btn', (e) => {
-    e.stopPropagation();
-    leaderboard.show();
   });
 
-  // 3. Render UI - buttons need pointer-events-auto to intercept clicks
+  // 2. DOM button clicks \u2014 on() auto-enables pointer-events
+  //    The SDK suppresses the canvas handler when a button is clicked
+  on('click', '#leaderboard-btn', () => leaderboard.show());
+  on('click', '#restart-btn', () => startGame());
+
+  // 3. Render UI \u2014 elements targeted by on() are automatically interactive
   let lastState = null;
   let lastScore = -1;
 
@@ -766,10 +820,12 @@ game(({ ctx, width, height, loop, ui, on, canvas, toStagePoint }) => {
         <div class="h-full flex flex-col items-center justify-center text-white">
           <div class="text-3xl mb-4">GAME OVER</div>
           <div class="text-6xl mb-4">\\\${score}</div>
-          <button id="leaderboard-btn" class="px-6 py-3 mb-4 bg-gradient-to-r from-blue-600 to-purple-600 rounded-xl font-bold shadow-lg shadow-blue-500/20 pointer-events-auto">
+          <button id="leaderboard-btn" class="px-6 py-3 mb-4 bg-gradient-to-r from-blue-600 to-purple-600 rounded-xl font-bold shadow-lg shadow-blue-500/20">
             VIEW LEADERBOARD
           </button>
-          <div class="text-xl animate-pulse">TAP TO RESTART</div>
+          <button id="restart-btn" class="px-6 py-3 bg-gray-700 rounded-xl font-bold">
+            PLAY AGAIN
+          </button>
         </div>\`);
     }
   }
@@ -781,6 +837,7 @@ game(({ ctx, width, height, loop, ui, on, canvas, toStagePoint }) => {
   function startGame() {
     state = 'playing';
     score = 0;
+    ui.render(''); // Clear game-over buttons
     updateUI();
   }
 
@@ -1180,7 +1237,7 @@ const leaderboard = createLeaderboard({ gameId: '<gameId from .starrc>' });
 
 game(({ ui, on }) => {
   ui.render(\`
-    <button id="lb-btn" class="px-6 py-3 bg-gradient-to-r from-blue-600 to-purple-600 rounded-xl font-bold text-white shadow-lg shadow-blue-500/20 pointer-events-auto">
+    <button id="lb-btn" class="px-6 py-3 bg-gradient-to-r from-blue-600 to-purple-600 rounded-xl font-bold text-white shadow-lg shadow-blue-500/20">
       View Leaderboard
     </button>
   \`);
@@ -1247,7 +1304,7 @@ game(({ ctx, width, height, loop, ui, on, canvas }) => {
         <div class="h-full flex flex-col items-center justify-center text-white">
           <div class="text-3xl mb-4">GAME OVER</div>
           <div class="text-6xl mb-4">\\\${score}</div>
-          <button id="lb-btn" class="px-6 py-3 mb-4 bg-gradient-to-r from-blue-600 to-purple-600 rounded-xl font-bold shadow-lg shadow-blue-500/20 pointer-events-auto">
+          <button id="lb-btn" class="px-6 py-3 mb-4 bg-gradient-to-r from-blue-600 to-purple-600 rounded-xl font-bold shadow-lg shadow-blue-500/20">
             VIEW LEADERBOARD
           </button>
           <div class="text-xl animate-pulse">TAP TO RESTART</div>
@@ -1358,6 +1415,52 @@ function error(message) {
 function info(message) {
   console.log(`${colors.blue}\u2139${colors.reset} ${message}`);
 }
+var STAR_PACKAGES = ["star-sdk", "star-canvas", "star-audio", "star-leaderboard", "star-multiplayer"];
+function resolveStarSdkVersion(deployDir) {
+  const candidates = [
+    path.join(deployDir, "node_modules", "star-sdk", "package.json"),
+    path.join(process.cwd(), "node_modules", "star-sdk", "package.json")
+  ];
+  for (const p of candidates) {
+    try {
+      if (fs.existsSync(p)) {
+        const pkg = JSON.parse(fs.readFileSync(p, "utf-8"));
+        if (pkg.version) return pkg.version;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function injectImportMapIfNeeded(html, deployDir) {
+  if (/<script\s[^>]*type\s*=\s*["']importmap["'][^>]*>/i.test(html)) {
+    return html;
+  }
+  const bareImportPattern = /\bfrom\s+['"](?:star-sdk|star-canvas|star-audio|star-leaderboard|star-multiplayer)['"]/;
+  if (!bareImportPattern.test(html)) {
+    return html;
+  }
+  const version = resolveStarSdkVersion(deployDir);
+  const suffix = version ? `@${version}` : "";
+  const imports = {};
+  for (const pkg of STAR_PACKAGES) {
+    imports[pkg] = `https://esm.sh/${pkg}${suffix}`;
+  }
+  const importmapTag = `<script type="importmap">
+${JSON.stringify({ imports }, null, 2)}
+</script>
+`;
+  const moduleScriptMatch = html.match(/<script\s[^>]*type\s*=\s*["']module["'][^>]*>/i);
+  if (moduleScriptMatch && moduleScriptMatch.index !== void 0) {
+    return html.slice(0, moduleScriptMatch.index) + importmapTag + html.slice(moduleScriptMatch.index);
+  }
+  const headMatch = html.match(/<head[^>]*>/i);
+  if (headMatch && headMatch.index !== void 0) {
+    const insertPos = headMatch.index + headMatch[0].length;
+    return html.slice(0, insertPos) + "\n" + importmapTag + html.slice(insertPos);
+  }
+  return html;
+}
 function showHelp() {
   log(`
 ${colors.bright}Star SDK CLI${colors.reset} v${VERSION}
@@ -1555,6 +1658,12 @@ async function deployCommand(dirPath) {
   }
   log(`Deploying ${colors.bright}${config.name}${colors.reset} from ${colors.dim}${deployDir}${colors.reset}`);
   try {
+    const originalHtml = fs.readFileSync(indexPath, "utf-8");
+    const processedHtml = injectImportMapIfNeeded(originalHtml, deployDir);
+    const htmlModified = processedHtml !== originalHtml;
+    if (htmlModified) {
+      info("Injected importmap for bare imports (star-sdk \u2192 esm.sh)");
+    }
     const archiver = (await import("archiver")).default;
     const zipBuffer = await new Promise((resolve2, reject) => {
       const chunks = [];
@@ -1564,9 +1673,10 @@ async function deployCommand(dirPath) {
       archive.on("error", reject);
       archive.glob("**/*", {
         cwd: deployDir,
-        ignore: ["node_modules/**", ".starrc", ".git/**", ".DS_Store"],
+        ignore: ["node_modules/**", ".starrc", ".git/**", ".DS_Store", "index.html"],
         dot: false
       });
+      archive.append(processedHtml, { name: "index.html" });
       archive.finalize();
     });
     log(`  ${colors.dim}Uploading ${(zipBuffer.length / 1024).toFixed(1)} KB...${colors.reset}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "star-sdk-cli",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "CLI for Star SDK — register games, install AI docs, and deploy to Star hosting",
   "type": "module",
   "bin": {