star-sdk-cli 0.1.1 → 0.1.2

package/dist/cli.mjs

@@ -3,6 +3,1628 @@
 // src/cli.ts
 import * as fs from "fs";
 import * as path from "path";
+import * as os from "os";
+
+// src/skills.ts
+var SKILL_CONTENT = `---
+name: star-sdk
+description: Star SDK for browser game development. Use when building games, adding audio/sound effects, canvas rendering, leaderboards, or multiplayer. Covers Star.game(), Star.audio, Star.leaderboard, and Star.multiplayer APIs.
+---
+
+# Star SDK
+
+Browser game development SDK with audio, canvas, leaderboards, and multiplayer.
+
+## Import
+
+\`\`\`javascript
+import Star from 'star-sdk';
+\`\`\`
+
+**CRITICAL:** Always use \`import Star from 'star-sdk'\` - not destructured imports.
+
+## API Overview
+
+| API | Use When | Docs |
+|-----|----------|------|
+| \`Star.game()\` | Game loop, canvas, UI, input | [canvas.md](./canvas.md) |
+| \`Star.audio\` | Sound effects, music | [audio.md](./audio.md) |
+| \`Star.leaderboard\` | Scores, rankings | [leaderboard.md](./leaderboard.md) |
+| \`Star.multiplayer\` | Real-time multiplayer | [multiplayer.md](./multiplayer.md) |
+
+## Quick Start
+
+\`\`\`javascript
+import Star from 'star-sdk';
+
+Star.game(ctx => {
+  const { canvas, width, height, ctx: c } = ctx;
+  let score = 0;
+
+  // Preload audio
+  Star.audio.preload({ coin: 'coin', jump: 'jump' });
+
+  // Game loop
+  ctx.loop((dt) => {
+    c.fillStyle = '#1a1a2e';
+    c.fillRect(0, 0, width, height);
+    c.fillStyle = '#fff';
+    c.font = '24px sans-serif';
+    c.fillText(\`Score: \${score}\`, 20, 40);
+  });
+
+  // Input
+  canvas.onclick = () => {
+    score += 10;
+    Star.audio.play('coin');
+  };
+});
+\`\`\`
+
+## Common Patterns
+
+### Game Over -> Submit Score -> Show Leaderboard
+
+\`\`\`javascript
+function gameOver(finalScore) {
+  Star.leaderboard.submit(finalScore);
+  Star.leaderboard.show();
+}
+\`\`\`
+
+### Mobile Audio (IMPORTANT)
+
+Audio on mobile requires user interaction first. Star.audio handles unlocking automatically - just make sure the first \`play()\` call happens after a user interaction (click/tap).
+
+### Coordinate Handling
+
+\`\`\`javascript
+canvas.onclick = (e) => {
+  const point = ctx.toStagePoint(e);  // Correct coordinates
+  console.log(point.x, point.y);
+};
+\`\`\`
+
+## Don't Do This
+
+- **Don't** create canvas manually - use \`Star.game()\`
+- **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)
+
+## Audio Presets (Full List)
+
+Only these 17 presets exist:
+- UI: \`beep\`, \`click\`, \`select\`, \`error\`, \`success\`
+- Actions: \`jump\`, \`swoosh\`, \`shoot\`, \`laser\`, \`explosion\`
+- Combat: \`hit\`, \`hurt\`
+- Collection: \`coin\`, \`pickup\`, \`bonus\`, \`unlock\`, \`powerup\`
+
+## Full Game Example
+
+\`\`\`javascript
+import Star from 'star-sdk';
+
+Star.game(ctx => {
+  const { canvas, width, height, ctx: c } = ctx;
+  let score = 0;
+  let gameOver = false;
+  let playerY = height / 2;
+  let obstacles = [];
+
+  Star.audio.preload({
+    jump: 'jump',
+    coin: 'coin',
+    hurt: 'hurt'
+  });
+
+  // Spawn obstacles
+  setInterval(() => {
+    if (!gameOver) {
+      obstacles.push({ x: width, y: Math.random() * height, passed: false });
+    }
+  }, 2000);
+
+  ctx.loop((dt) => {
+    if (gameOver) return;
+
+    // Clear
+    c.fillStyle = '#1a1a2e';
+    c.fillRect(0, 0, width, height);
+
+    // 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();
+      }
+    });
+
+    // Remove off-screen
+    obstacles = obstacles.filter(o => o.x > -20);
+
+    // Draw player
+    c.fillStyle = '#e94560';
+    c.beginPath();
+    c.arc(50, playerY, 15, 0, Math.PI * 2);
+    c.fill();
+
+    // Draw obstacles
+    c.fillStyle = '#0f4c75';
+    obstacles.forEach(obs => {
+      c.fillRect(obs.x - 10, obs.y - 25, 20, 50);
+    });
+
+    // Draw score
+    c.fillStyle = '#fff';
+    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');
+    }
+  };
+});
+\`\`\`
+
+For detailed API documentation, see the linked files above.
+`;
+var AUDIO_DOCS = `**Installation**
+
+First, add the package to your project:
+\` \` \`bash
+yarn add star-audio
+\` \` \`
+
+### Star Audio SDK
+
+**Mobile-first, bulletproof audio for web games.** Works on iOS/Android out of the box. Missing files won't crash your game.
+
+**Import:**
+\` \` \`javascript
+import createAudio from 'star-audio';
+const audio = createAudio();
+\` \` \`
+
+**CRITICAL:** Import in JavaScript - don't add \`<script src="/star-sdk/audio.js">\` tags.
+
+**Why Star Audio?**
+- \u2705 **Mobile-first** - Works on iOS/Android, handles audio unlock automatically, plays even in silent mode
+- \u2705 **Never throws** - Missing audio files? Game keeps running with clear warnings
+- \u2705 **Zero-config** - Works on first play, no setup needed
+- \u2705 **No try/catch needed** - Fire-and-forget API, perfect for AI-generated games
+
+---
+
+**Quick Start:**
+
+\` \` \`javascript
+const audio = createAudio();
+
+// CRITICAL: Preload presets before playing them
+// You can set per-sound volumes in preload
+audio.preload({
+  jump: { synth: 'jump', volume: 0.5 },      // Quieter jump
+  shoot: { synth: 'shoot', volume: 0.8 },    // Loud shoot
+  coin: { synth: 'coin', volume: 0.6 },
+  explosion: { synth: 'explosion', volume: 1.0 }
+});
+
+// Now play them - volumes are already set
+audio.play('jump');
+audio.play('shoot');
+\` \` \`
+
+**ONLY THESE 17 PRESETS EXIST - DO NOT INVENT NAMES:**
+- UI: \`beep\`, \`click\`, \`select\`, \`error\`, \`success\`
+- Actions: \`jump\`, \`swoosh\`, \`shoot\`, \`laser\`, \`explosion\`
+- Combat: \`hit\`, \`hurt\`
+- Collection: \`coin\`, \`pickup\`, \`bonus\`, \`unlock\`, \`powerup\`
+
+**If you need a sound that's not in this list, use custom synth or generate audio.**
+
+**CRITICAL:** Preload all presets before use. Set volumes in preload:
+\` \` \`javascript
+audio.preload({
+  jump: { synth: 'jump', volume: 0.5 },  // With custom volume
+  coin: 'coin',                           // Default volume
+  explosion: 'explosion'                  // For crashes/impacts
+});
+\` \` \`
+
+---
+
+**Custom synth (advanced):**
+
+\` \` \`javascript
+audio.preload({
+  'sfx.charge': {
+    waveform: 'triangle',
+    frequency: [200, 300, 450, 650, 900],  // Rising charge-up
+    duration: 0.40,
+    volume: 0.38
+  }
+});
+\` \` \`
+
+**Make sounds feel good:**
+- **Use frequency arrays** - Sweeps/arpeggios are more satisfying than single tones
+- **Rising = positive** - Ascending pitches for rewards (coin, jump, powerup)
+- **Descending = impact** - Falling pitches for actions (shoot, hurt, explosion)
+- **More notes = richer** - 3-6 frequencies sound fuller than 1-2
+- **Musical intervals** - Use harmonious ratios (octaves, fifths, major chords)
+
+**Waveform choice:**
+- \`sine\` - Pure, pleasant (UI, bells, rewards)
+- \`triangle\` - Warm, full (jumps, explosions, success)
+- \`square\` - Retro, characterful (powerups, beeps, chiptune)
+- \`sawtooth\` - Harsh, aggressive (lasers, damage, errors)
+
+**Frequency guide:**
+- High (800-2000 Hz): Bright, attention-grabbing (UI, coins)
+- Mid (200-800 Hz): Game actions (jumps, shoots)
+- Low (30-200 Hz): Impacts, bass (explosions, rumbles)
+- Arrays: 3-4 notes for melodies, 6+ for noise-like effects
+
+---
+
+**Audio files:**
+
+\` \` \`javascript
+audio.preload({
+  'sfx.boom': 'assets/boom.mp3',
+  'bgm.theme': 'assets/music.mp3'
+});
+audio.play('sfx.boom');
+audio.music.crossfadeTo('bgm.theme', { duration: 1.5 });
+\` \` \`
+
+---
+
+**Controls:**
+
+\` \` \`javascript
+audio.setMusicVolume(0.5);
+audio.setSfxVolume(0.8);
+audio.toggleMute();
+\` \` \``;
+var CANVAS_DOCS = `**Installation**
+
+First, add the package to your project:
+
+\`\`\`bash
+yarn add star-dom
+\`\`\`
+
+### Star DOM SDK
+
+Use the **Star DOM SDK** to initialize games reliably.
+It prevents the most common bugs:
+
+  - \u2705 No "cannot read addEventListener of null"
+  - \u2705 No canvas sizing/DPR/blur issues
+  - \u2705 No accidentally wiping the canvas with \`innerHTML\`
+  - \u2705 Games work identically on ALL devices (fixed 16:9 with letterboxing)
+
+-----
+
+### Fixed 16:9 Resolution
+
+**Default: 640\xD7360 (landscape) or 360\xD7640 (portrait).** Games work identically on every device.
+
+The SDK uses letterboxing to maintain the exact game area. This means:
+- Positions like \`x: 320, y: 180\` always mean the exact center
+- Two objects at \`x: 100\` and \`x: 540\` are always the same distance apart
+- No "works on my screen, breaks on mobile" bugs
+
+\`\`\`ts
+// These values work identically on ALL devices:
+const player = { x: 320, y: 300 };        // Center-bottom area
+const enemy = { x: 600, y: 50 };          // Top-right area
+const playerSize = 32;                     // Always 32px
+const speed = 200;                         // Always 200px/sec
+\`\`\`
+
+-----
+
+### Golden Path (How to Use)
+
+Import \`game\` and wrap your code in it. The \`game\` function handles DOM readiness, creates a canvas and a UI overlay, and gives you a safe context to build.
+
+\`\`\`ts
+import { game } from 'star-canvas';
+
+game(({ ctx, width, height, on, loop, ui, canvas }) => {
+  // ctx: The 2D canvas context
+  // width, height: The logical size (CSS pixels) - READ-ONLY
+  // on: Safe, delegated event listener
+  // loop: Stable game loop (with dt)
+  // ui: Safe overlay for HTML
+  // canvas: The <canvas> element
+
+  // 1. Draw on the canvas
+  loop((dt) => {
+    ctx.clearRect(0, 0, width, height);
+    ctx.fillStyle = '#22d3ee'; // cyan-400
+    ctx.fillRect(width / 2 - 25, height / 2 - 25, 50, 50);
+  });
+
+  // 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">
+        Click Me
+      </button>
+    </div>
+  \`);
+
+  // 3. Listen for button clicks
+  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
+  canvas.addEventListener('pointerdown', (e) => {
+    console.log('Canvas/screen tapped!', e);
+  });
+});
+\`\`\`
+
+> **CRITICAL:** Always import the SDK in your JavaScript/TypeScript.
+> **Do not** add a \`<script src="/star-sdk/dom.js">\` tag in HTML.
+>
+> **Recommended Import:**
+>
+> \`\`\`ts
+> import { game } from 'star-canvas';
+> \`\`\`
+
+-----
+
+## Core API: \`game(setup, options?)\`
+
+The \`setup\` function receives one argument: a \`GameContext\` object with the following properties:
+
+### \`ctx: CanvasRenderingContext2D\`
+
+The 2D drawing context. Its transform is already scaled for DPR. You **always draw in logical CSS pixels**.
+
+### \`canvas: HTMLCanvasElement\`
+
+The \`<canvas>\` element itself.
+
+  - **Use this for gameplay input listeners** (e.g., \`pointerdown\`, \`pointermove\`).
+
+### \`width: number\` (getter)
+
+### \`height: number\` (getter)
+
+The logical CSS pixel width and height of the stage. **Use these for all game logic and drawing.** They are getters, so they are always up-to-date.
+
+### \`on(type, selector, handler, options?)\`
+
+Attaches a **delegated event listener** to the document.
+
+  - \u2705 **Use this for UI elements** (buttons, menus) inside your \`ui.render()\` HTML.
+  - \u2705 Survives \`ui.render()\` calls.
+  - Returns an \`off()\` function to unsubscribe.
+
+### \`loop(tick)\`
+
+Starts a \`requestAnimationFrame\` loop.
+
+  - \`tick\` function receives \`(dt, now)\`, where \`dt\` is **delta time in seconds**.
+  - **ALWAYS** multiply movement by \`dt\` (e.g., \`player.x += speed * dt\`).
+  - Returns \`{ start(), stop(), running }\`. The loop starts automatically.
+
+### \`ui: GameUI\`
+
+A safe manager for your HTML overlay, stacked on top of the canvas.
+
+  - \`ui.root\`: The \`<div>\` element for your UI. It is **interactive by default** (standard HTML behavior - scroll, buttons work).
+  - \`ui.render(html: string)\`: **Use this** to set your UI. It's safe and won't destroy the canvas.
+    - Automatically skips updates if HTML is unchanged (safe to call in loop for static content)
+    - For best performance with dynamic content (score), only call when values actually change
+  - \`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.
+
+### Cursor Management
+
+**CRITICAL:** Choose cursor based on how players interact. Update cursor when state changes (e.g., menu \u2192 playing \u2192 gameover).
+
+\`\`\`ts
+// MOUSE-BASED GAMES (click/point-and-click/puzzle/clicker/strategy/constellation)
+if (state === 'playing') canvas.style.cursor = 'pointer';  // Show where to click
+if (state === 'menu' || state === 'gameover') canvas.style.cursor = 'pointer';  // Keep visible
+
+// PRECISION AIMING (shooter/drawing/building)
+if (state === 'playing') canvas.style.cursor = 'crosshair';
+if (state === 'menu' || state === 'gameover') canvas.style.cursor = 'auto';
+
+// KEYBOARD/TOUCH ONLY (platformer/WASD/rhythm/endless runner)
+if (state === 'playing') canvas.style.cursor = 'none';  // Hide (doesn't matter)
+if (state === 'menu' || state === 'gameover') canvas.style.cursor = 'auto';  // Show for menus!
+\`\`\`
+
+**Decision:** Does player click on game objects? \u2192 \`'pointer'\` | Aim precisely? \u2192 \`'crosshair'\` | WASD/touch only? \u2192 \`'none'\` during play, \`'auto'\` for menus
+
+### \`toStagePoint(event)\`
+
+Converts \`MouseEvent\` or \`PointerEvent\` client coordinates to the stage's logical coordinates.
+
+  - **USE THIS** for all canvas pointer input.
+
+### \`createDrag()\`
+
+Creates a drag state helper that handles coordinate conversion and offset tracking automatically.
+
+\`\`\`ts
+const drag = createDrag();
+
+canvas.addEventListener('pointerdown', (e) => {
+  canvas.setPointerCapture(e.pointerId);  // IMPORTANT: Capture for reliable drags
+  const { x, y } = drag.point(e);         // Convert coordinates
+  const hit = pieces.find(p => /* hit test */);
+  if (hit) drag.grab(e, hit);             // Start drag with offset
+});
+
+canvas.addEventListener('pointermove', (e) => drag.move(e));  // Updates position
+canvas.addEventListener('pointerup', () => {
+  const dropped = drag.release();  // Returns dropped object (or null)
+});
+\`\`\`
+
+**API:**
+- \`point(e)\` - Pure coordinate conversion, no side effects
+- \`grab(e, obj)\` - Start dragging an object, computing offset from cursor
+- \`move(e)\` - Update dragged object's position
+- \`release()\` - End drag, returns dropped object or null
+- \`dragging\` - The currently dragged object (or null)
+
+### \`GameOptions\` (optional)
+
+Pass an options object as the second argument to \`game()\`:
+
+  - \`preset?: 'landscape' | 'portrait' | 'responsive'\`: Game orientation preset.
+    - \`'landscape'\` (default): 640\xD7360 - for platformers, shooters, racing
+    - \`'portrait'\`: 360\xD7640 - for puzzle, cards, match-3, mobile-style
+    - \`'responsive'\`: Fills container, no fixed dimensions (legacy - gameplay varies by device)
+  - \`width?: number\`: Override width (default: 640 for landscape, 360 for portrait)
+  - \`height?: number\`: Override height (default: 360 for landscape, 640 for portrait)
+  - \`fit?: 'contain' | 'cover' | 'stretch'\`: How game fits container (default: \`'contain'\` with letterboxing)
+  - \`pixelRatio?: 'device' | number\`: (default: \`'device'\`)
+  - \`maxPixelRatio?: number\`: (default: \`2\`)
+  - \`preventContextMenu?: boolean\`: Prevent right-click context menu on canvas (default: \`true\`)
+
+**Default behavior:** Fixed 640\xD7360 (16:9) with letterboxing. Games work identically on all devices.
+
+-----
+
+## Recipes
+
+### Recipe 1: UI-Only Game (e.g., Clicker)
+
+Use \`game\`, \`on\`, and \`ui\`.
+
+\`\`\`ts
+import { game } from 'star-canvas';
+
+game(({ on, ui }) => {
+  let score = 0;
+
+  function render() {
+    // UI is interactive by default - buttons, scroll, forms all work
+    ui.render(\`
+      <div class="min-h-[100dvh] grid place-items-center bg-purple-900 text-white">
+        <div class="text-center space-y-4">
+          <h1 class="text-4xl font-bold">Score: \\\${score}</h1>
+          <button id="clickBtn" class="px-8 py-4 rounded-xl bg-cyan-400 text-slate-900 font-bold">
+            Click Me!
+          </button>
+        </div>
+      </div>
+    \`);
+  }
+
+  // Button clicks work by default
+  on('click', '#clickBtn', () => {
+    score++;
+    render();
+  });
+
+  render();
+});
+\`\`\`
+
+### Recipe 2: Canvas Game (Landscape)
+
+Default pattern - fixed 640\xD7360 resolution. Games work identically on all devices.
+
+\`\`\`ts
+import { game } from 'star-canvas';
+
+game(({ ctx, width, height, loop }) => {
+  // width = 640, height = 360 (always, with letterboxing)
+  const playerSize = 32;
+  const speed = 200;  // 200px per second
+
+  const player = { x: 64, y: 180 };  // Fixed positions work everywhere
+
+  loop((dt) => {
+    player.x += speed * dt;
+    if (player.x > width) player.x = -playerSize;
+
+    ctx.fillStyle = '#0f172a';
+    ctx.fillRect(0, 0, width, height);
+
+    ctx.fillStyle = '#22d3ee';
+    ctx.fillRect(player.x, player.y - playerSize/2, playerSize, playerSize);
+  });
+});
+// Default: 640\xD7360 landscape with letterboxing
+\`\`\`
+
+### Recipe 3: Canvas Game (Portrait)
+
+For puzzle games, card games, match-3, mobile-style games - use portrait preset.
+
+\`\`\`ts
+import { game } from 'star-canvas';
+
+game(({ ctx, width, height, loop, canvas, toStagePoint }) => {
+  // width = 360, height = 640 (always, with letterboxing)
+  const cellSize = 40;
+  const gridCols = 8;
+  const gridRows = 12;
+
+  // Center the grid
+  const gridWidth = gridCols * cellSize;
+  const gridX = (width - gridWidth) / 2;
+  const gridY = 80;
+
+  canvas.addEventListener('pointerdown', (e) => {
+    const { x, y } = toStagePoint(e);
+    // Handle tap on grid...
+  });
+
+  loop((dt) => {
+    ctx.fillStyle = '#1e1b4b';
+    ctx.fillRect(0, 0, width, height);
+
+    ctx.strokeStyle = '#4338ca';
+    for (let row = 0; row < gridRows; row++) {
+      for (let col = 0; col < gridCols; col++) {
+        ctx.strokeRect(
+          gridX + col * cellSize,
+          gridY + row * cellSize,
+          cellSize, cellSize
+        );
+      }
+    }
+  });
+}, { preset: 'portrait' });  // 360\xD7640 portrait with letterboxing
+\`\`\`
+
+### Recipe 4: Custom Resolution
+
+For games that need different dimensions (e.g., pixel art at 320\xD7180).
+
+\`\`\`ts
+import { game } from 'star-canvas';
+
+game(({ ctx, width, height, loop, toStagePoint, canvas }) => {
+  // Custom 320\xD7180 resolution (retro pixel art style)
+  const player = { x: 160, y: 90 };  // Center
+
+  canvas.addEventListener('pointerdown', (e) => {
+    const { x, y } = toStagePoint(e);
+    console.log('Tapped at:', x, y);  // Always 0-320, 0-180
+  });
+
+  loop((dt) => {
+    ctx.fillStyle = '#0f172a';
+    ctx.fillRect(0, 0, width, height);
+
+    ctx.fillStyle = '#22d3ee';
+    ctx.fillRect(player.x - 8, player.y - 8, 16, 16);
+  });
+}, { width: 320, height: 180 });  // Custom resolution with letterboxing
+\`\`\`
+
+### Recipe 5: Complex Game with Canvas + UI + Events (like FLOW)
+
+\`\`\`ts
+import { game } from 'star-canvas';
+import { createLeaderboard } from '/star-sdk/v1/leaderboard.js';
+
+const leaderboard = createLeaderboard();
+
+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') {
+      // ... (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
+  let lastState = null;
+  let lastScore = -1;
+
+  function updateUI() {
+    // CRITICAL: Only render when state/score changes, NOT every frame
+    // Calling ui.render() in the loop breaks buttons (DOM recreation)
+    if (state === lastState && score === lastScore) return;
+    lastState = state;
+    lastScore = score;
+
+    if (state === 'menu') {
+      ui.render(\`
+        <div class="h-full flex flex-col items-center justify-center text-white">
+          <h1 class="text-6xl font-bold mb-4">FLOW</h1>
+          <div class="text-2xl animate-pulse">TAP TO START</div>
+        </div>\`);
+    } else if (state === 'playing') {
+      ui.render(\`
+        <div class="absolute top-8 left-1/2 -translate-x-1/2 text-white">
+          <div class="text-5xl font-bold">\\\${score}</div>
+        </div>\`);
+    } else if (state === 'gameover') {
+      ui.render(\`
+        <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-purple-600 rounded-lg pointer-events-auto">
+            VIEW LEADERBOARD
+          </button>
+          <div class="text-xl animate-pulse">TAP TO RESTART</div>
+        </div>\`);
+    }
+  }
+
+  // 4. Call updateUI when state changes (NOT every frame)
+  updateUI();
+
+  // Update when state transitions happen
+  function startGame() {
+    state = 'playing';
+    score = 0;
+    updateUI();
+  }
+
+  function endGame() {
+    state = 'gameover';
+    // Submit score to leaderboard
+    leaderboard.submit(score);
+    updateUI();
+  }
+});
+\`\`\`
+
+### Recipe 6: Safe Canvas Transforms (scoped)
+
+When applying temporary transforms (translate, rotate, scale), use \`scoped()\` to automatically restore the context state:
+
+\`\`\`ts
+import { game } from 'star-canvas';
+
+game(({ ctx, scoped, loop }) => {
+  const cards = [
+    { x: 100, y: 100, angle: 0.1, visible: true },
+    { x: 200, y: 150, angle: -0.2, visible: true },
+  ];
+
+  function drawCard(card) {
+    scoped(() => {
+      ctx.translate(card.x, card.y);
+      ctx.rotate(card.angle);
+      if (!card.visible) return; // Safe! restore() still happens
+      ctx.fillStyle = '#3b82f6';
+      ctx.fillRect(-40, -60, 80, 120);
+    });
+  }
+
+  loop(() => {
+    ctx.clearRect(0, 0, 800, 600);
+    cards.forEach(drawCard);
+  });
+});
+\`\`\`
+
+**Why use \`scoped()\`:** Prevents transform stack corruption from early returns, exceptions, or forgetting \`ctx.restore()\`. The context is always restored, even if the function exits early.
+
+### Recipe 7: Drag and Drop with createDrag() (RECOMMENDED)
+
+Use the \`createDrag()\` helper - it handles coordinate conversion and offset tracking automatically.
+
+\`\`\`ts
+import { game } from 'star-canvas';
+
+game(({ ctx, width, height, loop, canvas, createDrag }) => {
+  // Size relative to height for consistency
+  const pieceSize = height * 0.15;
+
+  const pieces = [
+    { x: width * 0.2, y: height * 0.3, color: '#ef4444' },
+    { x: width * 0.4, y: height * 0.4, color: '#22c55e' },
+    { x: width * 0.6, y: height * 0.3, color: '#3b82f6' },
+  ];
+
+  // Create drag helper - handles coordinate conversion automatically
+  const drag = createDrag();
+
+  function hitTest(x, y) {
+    for (let i = pieces.length - 1; i >= 0; i--) {
+      const p = pieces[i];
+      if (x >= p.x && x < p.x + pieceSize && y >= p.y && y < p.y + pieceSize) {
+        return p;
+      }
+    }
+    return null;
+  }
+
+  canvas.addEventListener('pointerdown', (e) => {
+    canvas.setPointerCapture(e.pointerId); // IMPORTANT: Ensures drag works outside canvas
+    const { x, y } = drag.point(e);        // Convert coordinates
+    const hit = hitTest(x, y);
+    if (hit) {
+      drag.grab(e, hit);                   // Start drag with offset from cursor
+      canvas.style.cursor = 'grabbing';
+    }
+  });
+
+  canvas.addEventListener('pointermove', (e) => {
+    drag.move(e);                          // Updates grabbed object position
+    if (!drag.dragging) {
+      const { x, y } = drag.point(e);
+      canvas.style.cursor = hitTest(x, y) ? 'grab' : 'default';
+    }
+  });
+
+  canvas.addEventListener('pointerup', () => {
+    const dropped = drag.release();        // Returns dropped object (or null)
+    if (dropped) {
+      console.log('Dropped:', dropped);
+    }
+    canvas.style.cursor = 'default';
+  });
+
+  loop(() => {
+    ctx.fillStyle = '#1e293b';
+    ctx.fillRect(0, 0, width, height);
+
+    for (const p of pieces) {
+      ctx.fillStyle = drag.dragging === p ? '#fbbf24' : p.color;
+      ctx.fillRect(p.x, p.y, pieceSize, pieceSize);
+    }
+  });
+});
+\`\`\`
+
+**CRITICAL: Always use \`setPointerCapture()\`** - This ensures drags work even when the pointer moves outside the canvas. Without it, fast drags can leave objects stuck mid-drag.
+
+### Recipe 8: Drag and Drop (Manual Pattern)
+
+If you need more control, here's the manual approach with \`toStagePoint()\`.
+
+\`\`\`ts
+import { game } from 'star-canvas';
+
+game(({ ctx, width, height, loop, canvas, toStagePoint }) => {
+  const pieceSize = height * 0.15;
+  const pieces = [
+    { x: width * 0.2, y: height * 0.3, color: '#ef4444' },
+    { x: width * 0.4, y: height * 0.4, color: '#22c55e' },
+  ];
+
+  // Manual drag state
+  let dragging = null;
+  let dragOffsetX = 0;
+  let dragOffsetY = 0;
+
+  function hitTest(px, py) {
+    for (let i = pieces.length - 1; i >= 0; i--) {
+      const p = pieces[i];
+      if (px >= p.x && px < p.x + pieceSize && py >= p.y && py < p.y + pieceSize) {
+        return p;
+      }
+    }
+    return null;
+  }
+
+  canvas.addEventListener('pointerdown', (e) => {
+    canvas.setPointerCapture(e.pointerId);  // Ensures drag works outside canvas
+    const { x, y } = toStagePoint(e);       // CRITICAL: Convert coordinates!
+    const hit = hitTest(x, y);
+    if (hit) {
+      dragging = hit;
+      dragOffsetX = x - hit.x;              // Store offset
+      dragOffsetY = y - hit.y;
+      canvas.style.cursor = 'grabbing';
+    }
+  });
+
+  canvas.addEventListener('pointermove', (e) => {
+    const { x, y } = toStagePoint(e);  // CRITICAL: Convert here too!
+    if (dragging) {
+      dragging.x = x - dragOffsetX;
+      dragging.y = y - dragOffsetY;
+    } else {
+      canvas.style.cursor = hitTest(x, y) ? 'grab' : 'default';
+    }
+  });
+
+  canvas.addEventListener('pointerup', () => {
+    dragging = null;
+    canvas.style.cursor = 'default';
+  });
+
+  loop(() => {
+    ctx.fillStyle = '#1e293b';
+    ctx.fillRect(0, 0, width, height);
+
+    for (const p of pieces) {
+      ctx.fillStyle = dragging === p ? '#fbbf24' : p.color;
+      ctx.fillRect(p.x, p.y, pieceSize, pieceSize);
+    }
+  });
+});
+\`\`\`
+
+**Common Drag-Drop Mistakes:**
+
+1. \u274C Forgetting \`toStagePoint()\` in pointermove \u2192 \`createDrag()\` fixes this
+2. \u274C No drag offset (piece "jumps" to cursor) \u2192 \`createDrag()\` fixes this
+3. \u274C Using \`e.clientX/clientY\` directly \u2192 \`createDrag()\` fixes this
+4. \u274C Not clearing state on pointerup \u2192 \`createDrag()\` fixes this
+5. \u274C Missing \`setPointerCapture()\` (drags break outside canvas) \u2192 **You must add this!**
+
+**Recommendation:** Use \`createDrag()\` + \`setPointerCapture()\` for bulletproof drag-and-drop.`;
+var LEADERBOARD_DOCS = `**Installation**
+
+\`\`\`bash
+yarn add star-leaderboard
+\`\`\`
+
+### Star Leaderboard SDK
+
+**Simple leaderboards for Star games.** Submit scores, show rankings, share results. Never crashes your game.
+
+**Import:**
+\`\`\`javascript
+import { createLeaderboard } from 'star-leaderboard';
+const leaderboard = createLeaderboard();
+\`\`\`
+
+**CRITICAL:** Import in JavaScript - don't add \`<script>\` tags.
+
+---
+
+**Quick Start:**
+
+\`\`\`javascript
+import { createLeaderboard } from 'star-leaderboard';
+import { game } from '/star-sdk/v1/dom.js';
+
+const leaderboard = createLeaderboard();
+
+game(({ ctx, width, height, loop, ui, on, canvas }) => {
+  let score = 0;
+  let state = 'playing';
+
+  function endGame() {
+    state = 'gameover';
+    // Submit score and show leaderboard
+    leaderboard.submit(score);
+    leaderboard.show();
+  }
+
+  // Game logic...
+});
+\`\`\`
+
+**That's it!** The SDK handles:
+- Score submission (works for guests and logged-in users)
+- Platform leaderboard UI (modal with rankings)
+- Weekly/all-time timeframes
+- AI-detected scoring (score/time/moves - higher or lower is better)
+
+---
+
+**API Reference:**
+
+**Core Methods:**
+\`\`\`javascript
+leaderboard.submit(score)       // Submit score, returns Promise<{ success, rank, scoreId }>
+leaderboard.show()              // Show platform leaderboard UI
+leaderboard.getScores(options)  // Fetch scores for custom UI
+leaderboard.share(options)      // Generate shareable link
+\`\`\`
+
+**Properties:**
+\`\`\`javascript
+leaderboard.ready    // true when SDK is initialized
+leaderboard.gameId   // Current game ID (auto-detected on platform)
+\`\`\`
+
+**Aliases (for discoverability):**
+\`\`\`javascript
+leaderboard.submitScore(score)  // Same as submit()
+leaderboard.showLeaderboard()   // Same as show()
+\`\`\`
+
+---
+
+**Patterns:**
+
+### Pattern 1: Submit and Show (Most Common)
+
+\`\`\`javascript
+import { createLeaderboard } from 'star-leaderboard';
+
+const leaderboard = createLeaderboard();
+
+function gameOver(finalScore) {
+  // Fire and forget - simplest approach
+  leaderboard.submit(finalScore);
+  leaderboard.show();
+}
+\`\`\`
+
+### Pattern 2: With Rank Feedback
+
+\`\`\`javascript
+import { createLeaderboard } from 'star-leaderboard';
+
+const leaderboard = createLeaderboard();
+
+async function gameOver(finalScore) {
+  const { success, rank } = await leaderboard.submit(finalScore);
+
+  if (success && rank) {
+    console.log(\`You ranked #\${rank}!\`);
+  }
+
+  leaderboard.show();
+}
+\`\`\`
+
+### Pattern 3: Leaderboard Button
+
+\`\`\`javascript
+import { createLeaderboard } from 'star-leaderboard';
+import { game } from '/star-sdk/v1/dom.js';
+
+const leaderboard = createLeaderboard();
+
+game(({ ui, on }) => {
+  ui.render(\`
+    <button id="lb-btn" class="pointer-events-auto">
+      View Leaderboard
+    </button>
+  \`);
+
+  on('click', '#lb-btn', (e) => {
+    e.stopPropagation();
+    leaderboard.show();
+  });
+});
+\`\`\`
+
+### Pattern 4: Custom Leaderboard UI
+
+\`\`\`javascript
+import { createLeaderboard } from 'star-leaderboard';
+
+const leaderboard = createLeaderboard();
+
+async function showCustomLeaderboard() {
+  const { scores, you, config } = await leaderboard.getScores({
+    timeframe: 'weekly',  // or 'all_time'
+    limit: 10
+  });
+
+  // Render your own UI
+  scores.forEach(entry => {
+    console.log(\`#\${entry.rank} \${entry.playerName}: \${entry.score}\`);
+  });
+
+  if (you) {
+    console.log(\`Your rank: #\${you.rank}\`);
+  }
+}
+\`\`\`
+
+### Pattern 5: Full Game Example
+
+\`\`\`javascript
+import { createLeaderboard } from 'star-leaderboard';
+import { game } from '/star-sdk/v1/dom.js';
+
+const leaderboard = createLeaderboard();
+
+game(({ ctx, width, height, loop, ui, on, canvas }) => {
+  let score = 0;
+  let state = 'menu';
+
+  function startGame() {
+    state = 'playing';
+    score = 0;
+    updateUI();
+  }
+
+  function endGame() {
+    state = 'gameover';
+    leaderboard.submit(score);
+    updateUI();
+  }
+
+  // UI with leaderboard button
+  function updateUI() {
+    if (state === 'gameover') {
+      ui.render(\`
+        <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-purple-600 rounded-lg pointer-events-auto">
+            VIEW LEADERBOARD
+          </button>
+          <div class="text-xl animate-pulse">TAP TO RESTART</div>
+        </div>
+      \`);
+    }
+  }
+
+  on('click', '#lb-btn', (e) => {
+    e.stopPropagation();
+    leaderboard.show();
+  });
+
+  canvas.addEventListener('pointerdown', () => {
+    if (state === 'menu' || state === 'gameover') startGame();
+  });
+
+  loop((dt) => {
+    // Game logic...
+  });
+});
+\`\`\`
+
+---
+
+**Options:**
+
+\`\`\`javascript
+// Default - auto-detects gameId on Star platform
+const leaderboard = createLeaderboard();
+
+// Standalone use (outside Star platform)
+const leaderboard = createLeaderboard({
+  gameId: 'your-game-uuid',
+  apiBase: 'https://buildwithstar.com'
+});
+\`\`\`
+
+---
+
+**getScores Options:**
+
+\`\`\`javascript
+const data = await leaderboard.getScores({
+  timeframe: 'weekly',  // 'weekly' (default) or 'all_time'
+  limit: 10             // Number of scores (default: 10)
+});
+
+// Returns:
+{
+  scores: [{ id, playerName, score, rank, submittedAt }],
+  config: { sort: 'DESC', valueType: 'score' },
+  timeframe: 'weekly',
+  you: { ... } | null,      // Your score if outside top scores
+  weekResetTime: 1234567890 // Unix ms when weekly resets
+}
+\`\`\`
+
+---
+
+**Tips:**
+
+1. **Call \`submit()\` before \`show()\`** - Ensures your score appears immediately in the leaderboard.
+
+2. **Fire and forget is fine** - \`submit()\` returns a Promise but you don't need to await it.
+
+3. **Use \`show()\` for platform UI** - It's the easiest way. Use \`getScores()\` only if you need custom rendering.
+
+4. **Don't store leaderboard state** - Just call the SDK methods when needed. The platform handles caching.
+
+5. **Works for guests** - Guests get a generated name like "Guest1234". They can sign in later to claim scores.`;
+var MULTIPLAYER_DOCS = `**Installation**
+
+\`\`\`bash
+yarn add star-multiplayer
+\`\`\`
+
+### Star Multiplayer SDK
+
+**Real-time multiplayer for Star games.** Host-authoritative state sync with automatic room management.
+
+**Import:**
+\`\`\`javascript
+import { createMultiplayer } from 'star-multiplayer';
+const mp = createMultiplayer();
+\`\`\`
+
+**CRITICAL:** Import in JavaScript - don't add \`<script>\` tags.
+
+**Features:**
+- **Host-authoritative** - One player runs game logic, others receive state
+- **Room-based** - Create/join rooms with 6-character invite codes
+- **Auto host migration** - If host leaves, another player becomes host
+- **Built-in lobby UI** - No need to build your own
+- **Works in iframes** - Uses postMessage relay to parent window
+
+---
+
+**Quick Start:**
+
+\`\`\`javascript
+import { createMultiplayer } from 'star-multiplayer';
+import { game } from '/star-sdk/v1/dom.js';
+
+const mp = createMultiplayer();
+
+game(async ({ ctx, width, height, loop, canvas }) => {
+  // 1. Start - auto-finds or creates room, starts immediately
+  await mp.start();
+
+  // 2. Game state
+  let state = { players: {}, ball: { x: width/2, y: height/2, vx: 200, vy: 150 } };
+
+  // 3. Receive state updates - update shared objects, keep local player prediction
+  mp.onState((s) => {
+    state.ball = s.ball;
+    for (const [id, p] of Object.entries(s.players)) {
+      if (id !== mp.localPlayerId) {
+        state.players[id] = p;
+      }
+    }
+  });
+
+  // 4. Handle inputs (runs locally for prediction, on host for authoritative state)
+  mp.onInput((playerId, input) => {
+    if (!state.players[playerId]) {
+      state.players[playerId] = { y: height/2 };
+    }
+    state.players[playerId].y = input.y;
+  });
+
+  // 5. Game loop
+  loop((dt) => {
+    // Host: run physics + broadcast state (auto-throttled to 20Hz)
+    mp.hostTick(dt, () => {
+      state.ball.x += state.ball.vx * dt;
+      state.ball.y += state.ball.vy * dt;
+      if (state.ball.y < 0 || state.ball.y > height) state.ball.vy *= -1;
+      return state;
+    });
+
+    // Everyone: render with interpolation for smooth movement
+    const renderState = mp.getInterpolatedState(dt, state);
+    ctx.fillStyle = '#0f172a';
+    ctx.fillRect(0, 0, width, height);
+    for (const p of Object.values(renderState.players)) {
+      ctx.fillStyle = '#22d3ee';
+      ctx.fillRect(20, p.y - 40, 10, 80);
+    }
+    ctx.beginPath();
+    ctx.arc(renderState.ball.x, renderState.ball.y, 10, 0, Math.PI * 2);
+    ctx.fill();
+  });
+
+  // 6. Input - works for EVERYONE (applied locally for instant feedback)
+  canvas.onpointermove = (e) => {
+    const rect = canvas.getBoundingClientRect();
+    mp.input({ y: ((e.clientY - rect.top) / rect.height) * height });
+  };
+});
+\`\`\`
+
+**That's it!** The SDK handles:
+- Auto-matchmaking (finds open room or creates one)
+- URL detection (\`?room=CODE\` \u2192 joins specific room)
+- Throttling state broadcasts to 20Hz
+- Routing host's inputs to their own handler
+
+---
+
+**Architecture:**
+
+\`\`\`
+Host (Player 1)          Server           Client (Player 2)
+     \u2502                     \u2502                     \u2502
+     \u2502 \u2500\u2500 state \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2502\u2500\u2500 state \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25B6\u2502
+     \u2502                     \u2502                     \u2502
+     \u2502\u25C0\u2500\u2500 input \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2502\u2500\u2500 input \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2502
+     \u2502                     \u2502                     \u2502
+     \u2502   (runs game logic) \u2502  (dumb relay)       \u2502 (renders state)
+\`\`\`
+
+---
+
+**API Reference:**
+
+**State (read-only):**
+\`\`\`javascript
+mp.isHost          // true if you're the host
+mp.isReady         // true if game has started
+mp.players         // Array of { id: string }
+mp.localPlayerId   // Your player ID
+mp.roomCode        // Current room code
+\`\`\`
+
+**Setup:**
+\`\`\`javascript
+await mp.start();  // Uses all defaults - auto-matchmaking, 8 players
+
+// Or customize:
+await mp.start({
+  maxPlayers: 8,      // default: 8 (max players per room)
+  mode: 'auto',       // default: 'auto' - finds/creates rooms automatically
+                      // 'private' - shows lobby with shareable code
+  showLobby: true,    // default: true (only used in 'private' mode)
+  tickRate: 50,       // default: 50ms (20Hz state broadcasts)
+  prediction: true    // default: true (client-side prediction for instant input)
+});
+
+// Examples:
+await mp.start({ maxPlayers: 2 });                    // 1v1 game
+await mp.start({ maxPlayers: 100 });                  // Battle royale
+await mp.start({ mode: 'private' });                  // Friends-only with invite code
+await mp.start({ mode: 'private', maxPlayers: 4 });   // Small private game
+\`\`\`
+
+**Sync:**
+\`\`\`javascript
+mp.onState((state) => { ... })              // Receive state (returns unsubscribe)
+mp.onInput((playerId, input) => { ... })    // Handle continuous input (position, aim)
+mp.hostTick(dt, () => state)                // Run on host, broadcast returned state
+mp.input(data)                              // Send continuous input (position, aim)
+mp.getInterpolatedState(dt, state)          // Get smoothly interpolated state for rendering
+\`\`\`
+
+**Discrete Events (shooting, jumping, using items):**
+\`\`\`javascript
+mp.event(type, data)                        // Send event - guaranteed delivery
+mp.onEvent((playerId, type, data) => { })   // Handle events (HOST ONLY, authoritative)
+\`\`\`
+
+**Player Updates:**
+\`\`\`javascript
+mp.onLocalPlayerUpdate((player, prevPlayer) => { ... })  // Local player changed
+mp.onPlayerUpdate(playerId, (player, prevPlayer) => { ... })  // Specific player changed
+\`\`\`
+
+**Lifecycle Events:**
+\`\`\`javascript
+mp.onPlayers((players) => { ... })  // Player list changed
+mp.onPlayerJoin((player) => { ... })  // Another player joined (use to init their state)
+mp.onPlayerLeave((player) => { ... }) // A player left
+mp.onHost((isHost) => { ... })      // Host status changed (for host migration)
+mp.onError((message) => { ... })    // Error occurred
+\`\`\`
+
+**Cleanup:**
+\`\`\`javascript
+mp.leave()    // Leave room
+mp.destroy()  // Full cleanup
+\`\`\`
+
+---
+
+**Tips:**
+
+1. **Use \`hostTick()\`** - It handles host detection and throttling. Don't use \`setInterval\`.
+
+2. **\`input()\` works on host** - Host's \`input()\` calls their \`onInput\` handler directly. Same code for everyone.
+
+3. **Handle host migration** - If host leaves, \`onHost(true)\` fires on new host. They should start running physics.
+
+4. **State design** - Only sync what changes: positions, scores, game objects. Not constants or textures.
+
+5. **Auto mode is default** - Players join instantly without friction. Use \`mode: 'private'\` only if you need invite codes.
+
+6. **Scale with maxPlayers** - Set \`maxPlayers: 2\` for 1v1, \`maxPlayers: 50\` for larger games. Default is 8.
+
+7. **Built-in prediction** - Your \`onInput\` handler runs immediately for local player input, eliminating input lag. Use \`mp.getInterpolatedState(dt, state)\` for smooth rendering of all players.
+
+8. **State pattern** - In \`onState\`, update shared objects (ball, score) but don't overwrite local player (keep your prediction). The SDK handles interpolation for other players.
+
+9. **Player count** - Use \`mp.players.length\` for player count in UI. Don't use \`Object.keys(state.players).length\` - that only counts players who've sent input.
+
+10. **Use \`mp.event()\` for discrete actions** - \`mp.input()\` is for continuous state (position, aim). Use \`mp.event('shoot', data)\` for discrete actions (shooting, jumping) - SDK guarantees delivery.
+
+---
+
+**Where Code Runs (Important!):**
+
+| Code Type | Where | Why |
+|-----------|-------|-----|
+| Physics, collision | Host (\`hostTick\`) | Single source of truth |
+| Hit detection, damage | Host (\`onInput\`) | Prevents cheating |
+| State changes (health, score) | Host | Authoritative |
+| UI updates, messages | **Everyone** (\`onState\` or \`loop\`) | Each player sees their own |
+| Visual/sound effects | **Everyone** | Local feedback |
+| Input sending | **Everyone** (\`mp.input()\`) | All players send inputs |
+
+**Golden rule:**
+- **CHANGES state** \u2192 host only
+- **REACTS to state** \u2192 everyone locally
+
+\`\`\`javascript
+// \u274C WRONG - UI in host-only code
+mp.hostTick(dt, () => {
+  if (player.health <= 0) showDeathMessage(); // Only host sees!
+  return state;
+});
+
+// \u2705 RIGHT - React to state on every client
+mp.onState((state) => {
+  const wasAlive = localPlayer.health > 0;
+  localPlayer.health = state.players[mp.localPlayerId].health;
+  if (wasAlive && localPlayer.health <= 0) {
+    showDeathMessage(); // Everyone sees their own death!
+  }
+});
+\`\`\`
+
+---
+
+**Common Patterns:**
+
+### Player Initialization (Important!)
+
+Initialize player state when they join, not when they first send input:
+
+\`\`\`javascript
+// \u274C WRONG - Players invisible until they move
+mp.onInput((playerId, input) => {
+  if (!state.players[playerId]) {
+    state.players[playerId] = { x: 0, y: 0, health: 100 };  // Too late!
+  }
+});
+
+// \u2705 RIGHT - Initialize on join
+mp.onPlayerJoin((player) => {
+  state.players[player.id] = {
+    x: Math.random() * width,
+    y: Math.random() * height,
+    health: 100
+  };
+});
+
+mp.onPlayerLeave((player) => {
+  delete state.players[player.id];
+});
+\`\`\`
+
+**Why this matters:** Without \`onPlayerJoin\`, a spectating player (not sending input) would be invisible to everyone.
+
+### Position Sync (3D/Complex Games)
+
+Clients send position, host tracks all players:
+
+\`\`\`javascript
+// Everyone: Send position every frame
+mp.input({
+  pos: [localPlayer.x, localPlayer.y, localPlayer.z],
+  yaw: localPlayer.yaw
+});
+
+// Host: Track in onInput
+const remotePlayers = {};
+mp.onInput((playerId, input) => {
+  if (!remotePlayers[playerId]) remotePlayers[playerId] = { health: 100 };
+  if (input.pos) {
+    remotePlayers[playerId].pos = input.pos;
+    remotePlayers[playerId].yaw = input.yaw;
+  }
+});
+\`\`\`
+
+### Actions (Shooting, Jumping, Items) - Use \`mp.event()\`
+
+**For discrete actions, use \`mp.event()\` instead of \`mp.input()\`.** The SDK guarantees delivery, deduplication, and preserves each event's data.
+
+**The Pattern:**
+
+\`\`\`javascript
+// \u274C WRONG - mp.input() loses rapid discrete actions (30Hz throttling)
+mp.input({ shoot: true }); // 3 rapid clicks = 1 shot!
+
+// \u2705 RIGHT - Two parts: cosmetic (instant) + authoritative (host)
+
+// PART 1: At the trigger point (EVERYONE runs this)
+if (shooting && canShoot(localPlayer)) {
+  // Cosmetic feedback - instant, local only
+  audio.play('shoot');
+  particles.muzzleFlash(localPlayer.pos);
+
+  // Send event to host for authoritative processing
+  mp.event('shoot', {
+    origin: [x, y, z],
+    dir: [dx, dy, dz]
+  });
+}
+
+// PART 2: Authoritative handler (HOST ONLY processes this)
+mp.onEvent((playerId, type, data) => {
+  if (type === 'shoot') {
+    // This creates the REAL bullet in game state
+    state.bullets.push({
+      owner: playerId,
+      pos: data.origin,
+      dir: data.dir
+    });
+  }
+});
+\`\`\`
+
+**Why two parts?**
+
+| Part | Who runs it | What it does |
+|------|-------------|--------------|
+| Cosmetic (at call site) | Everyone | Instant feedback: sound, particles, animations |
+| Authoritative (\`onEvent\`) | Host only | State changes: spawn bullets, apply damage |
+
+**This separation is intentional:**
+- **Cosmetic:** Your own shots feel instant (no network latency)
+- **Authoritative:** Game state is consistent (host is source of truth)
+- **Other players' bullets:** Appear in state broadcast, ~50ms later (acceptable for casual games)
+
+**Hearing other players' shots (optional):**
+\`\`\`javascript
+const seenBullets = new Set();
+mp.onState((state) => {
+  for (const bullet of state.bullets || []) {
+    if (!seenBullets.has(bullet.id) && bullet.owner !== mp.localPlayerId) {
+      audio.play('shoot');  // Hear remote player's shot
+      seenBullets.add(bullet.id);
+    }
+  }
+});
+\`\`\`
+
+**When to use which:**
+| Action Type | Method | Example |
+|-------------|--------|---------|
+| Continuous state | \`mp.input()\` | Position, aim direction, movement |
+| Discrete action | \`mp.event()\` | Shooting, jumping, using items, emotes |
+
+### Health (Host-Authoritative)
+
+Host owns health. Clients accept and react:
+
+\`\`\`javascript
+// \u274C WRONG - Client sends health (cheatable!)
+mp.input({ health: localPlayer.health });
+
+// \u2705 RIGHT - Host applies damage
+mp.onInput((playerId, input) => {
+  if (hit.playerId) remotePlayers[hit.playerId].health -= 25;
+});
+
+// \u2705 RIGHT - Client accepts AND reacts
+mp.onState((state) => {
+  const myHealth = state.players[mp.localPlayerId]?.health;
+  if (myHealth !== undefined) {
+    if (localPlayer.health > 0 && myHealth <= 0) showDeathMessage();
+    localPlayer.health = myHealth;
+  }
+});
+\`\`\`
+
+### Reacting to Player State Changes (Death, Score, etc.)
+
+Use \`onLocalPlayerUpdate\` to react when your player's state changes - the SDK tracks previous state for you:
+
+\`\`\`javascript
+mp.onLocalPlayerUpdate((player, prevPlayer) => {
+  // Detect death
+  if (prevPlayer.health > 0 && player.health <= 0) {
+    showDeathScreen();
+  }
+
+  // Detect respawn
+  if (prevPlayer.health <= 0 && player.health > 0) {
+    hideDeathScreen();
+  }
+
+  // Detect score increase
+  if (player.score > (prevPlayer.score || 0)) {
+    showScorePopup(player.score - prevPlayer.score);
+  }
+});
+\`\`\`
+
+For remote player effects (death animations, etc.):
+
+\`\`\`javascript
+// Subscribe to each remote player's updates
+for (const p of mp.players) {
+  if (p.id !== mp.localPlayerId) {
+    mp.onPlayerUpdate(p.id, (player, prev) => {
+      if (prev.health > 0 && player.health <= 0) {
+        playDeathAnimation(p.id);
+      }
+    });
+  }
+}
+\`\`\`
+
+---
+
+**Anti-Patterns:**
+
+### Using \`mp.input()\` for Discrete Actions
+
+**Problem**: Using \`mp.input({ shoot: true })\` for shooting, jumping, or any discrete action.
+
+**Why it breaks**: \`mp.input()\` is throttled to 30Hz. Multiple rapid clicks collapse into a single value, losing inputs.
+
+\`\`\`javascript
+// \u274C BAD - mp.input() loses rapid discrete actions
+mp.input({ shoot: true }); // 3 rapid clicks = 1 shot!
+
+// \u274C ALSO BAD - counters in mp.input() still have issues
+mp.input({ shootCount: count }); // Bursts all shots at once, loses timing
+
+// \u2705 GOOD - Use mp.event() for discrete actions
+mp.event('shoot', { origin, dir }); // Each event preserved with its data
+\`\`\`
+
+**The rule is simple:**
+
+| Action Type | Method | Why |
+|-------------|--------|-----|
+| **Continuous** (position, aim) | \`mp.input()\` | Last value is correct, throttling is fine |
+| **Discrete** (shoot, jump, use item) | \`mp.event()\` | Each action must be delivered with its data |`;
+
+// src/cli.ts
 var VERSION = "0.1.0";
 var API_BASE = process.env.STAR_API_BASE || "https://buildwithstar.com";
 var CONFIG_FILE = ".starrc";
@@ -34,10 +1656,13 @@ ${colors.bright}Star SDK CLI${colors.reset} v${VERSION}
 
 ${colors.dim}Commands:${colors.reset}
   ${colors.cyan}init <name>${colors.reset}     Register a new game
+  ${colors.cyan}install${colors.reset}         Install Star SDK skill for Claude Code
+  ${colors.cyan}docs [topic]${colors.reset}    Print API documentation (topics: audio, canvas, leaderboard, multiplayer)
   ${colors.cyan}whoami${colors.reset}          Show current configuration
 
 ${colors.dim}Options:${colors.reset}
   --email <email>   Email for higher rate limits (optional)
+  --project         Install skill to project instead of personal (~/.claude)
   --help            Show this help message
   --version         Show version
 
@@ -45,11 +1670,12 @@ ${colors.dim}Examples:${colors.reset}
   ${colors.dim}# Register a new game${colors.reset}
   npx star-sdk init "My Awesome Game"
 
-  ${colors.dim}# Register with email for higher limits${colors.reset}
-  npx star-sdk init "My Awesome Game" --email user@example.com
+  ${colors.dim}# Install SDK skill for Claude Code${colors.reset}
+  npx star-sdk install
 
-  ${colors.dim}# Using environment variable${colors.reset}
-  STAR_EMAIL=user@example.com npx star-sdk init "My Awesome Game"
+  ${colors.dim}# Print API documentation${colors.reset}
+  npx star-sdk docs
+  npx star-sdk docs audio
 
 ${colors.dim}Learn more:${colors.reset} https://buildwithstar.com/docs/sdk
 `);
@@ -130,6 +1756,14 @@ async function initCommand(name, email) {
     log(`  ${colors.cyan}import Star from 'star-sdk';${colors.reset}`);
     log(`  ${colors.cyan}Star.leaderboard.submit(1500);${colors.reset}`);
     log("");
+    if (process.env.CLAUDE_SESSION_ID) {
+      info(`Claude Code detected! Run ${colors.cyan}npx star-sdk install${colors.reset} to enable auto-discovery.`);
+      log("");
+    }
+    log(`${colors.dim}Documentation:${colors.reset}`);
+    log(`  ${colors.dim}Full docs:${colors.reset}  ${colors.cyan}https://buildwithstar.com/docs/sdk${colors.reset}`);
+    log(`  ${colors.dim}CLI docs:${colors.reset}   ${colors.cyan}npx star-sdk docs${colors.reset}`);
+    log("");
   } catch (err) {
     if (err.code === "ECONNREFUSED" || err.code === "ENOTFOUND") {
       error("Could not connect to Star API. Check your internet connection.");
@@ -160,6 +1794,50 @@ function whoamiCommand() {
   }
   log("");
 }
+function installCommand(scope = "personal") {
+  const skillDir = scope === "personal" ? path.join(os.homedir(), ".claude", "skills", "star-sdk") : path.join(process.cwd(), ".claude", "skills", "star-sdk");
+  try {
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(path.join(skillDir, "SKILL.md"), SKILL_CONTENT);
+    fs.writeFileSync(path.join(skillDir, "audio.md"), AUDIO_DOCS);
+    fs.writeFileSync(path.join(skillDir, "canvas.md"), CANVAS_DOCS);
+    fs.writeFileSync(path.join(skillDir, "leaderboard.md"), LEADERBOARD_DOCS);
+    fs.writeFileSync(path.join(skillDir, "multiplayer.md"), MULTIPLAYER_DOCS);
+    log("");
+    success(`Star SDK skill installed to ${skillDir}`);
+    log("");
+    log(`${colors.dim}Claude Code will now auto-discover the Star SDK when you work on games.${colors.reset}`);
+    log("");
+    log(`${colors.dim}Installed files:${colors.reset}`);
+    log(`  SKILL.md        ${colors.dim}Main skill entry point${colors.reset}`);
+    log(`  audio.md        ${colors.dim}Star.audio API docs${colors.reset}`);
+    log(`  canvas.md       ${colors.dim}Star.game() API docs${colors.reset}`);
+    log(`  leaderboard.md  ${colors.dim}Star.leaderboard API docs${colors.reset}`);
+    log(`  multiplayer.md  ${colors.dim}Star.multiplayer API docs${colors.reset}`);
+    log("");
+  } catch (err) {
+    error(`Failed to install skill: ${err.message}`);
+    process.exit(1);
+  }
+}
+function docsCommand(topic) {
+  const docs = {
+    audio: AUDIO_DOCS,
+    canvas: CANVAS_DOCS,
+    leaderboard: LEADERBOARD_DOCS,
+    multiplayer: MULTIPLAYER_DOCS
+  };
+  if (!topic) {
+    console.log(SKILL_CONTENT);
+  } else if (docs[topic]) {
+    console.log(docs[topic]);
+  } else {
+    error(`Unknown topic: ${topic}`);
+    log("");
+    log("Available topics: audio, canvas, leaderboard, multiplayer");
+    process.exit(1);
+  }
+}
 function parseArgs(args) {
   const flags = {};
   const positional = [];
@@ -199,6 +1877,14 @@ async function main() {
     case "init":
       await initCommand(positional[0], email);
       break;
+    case "install":
+      installCommand(flags.project ? "project" : "personal");
+      break;
+    case "docs":
+    case "skill":
+    case "prompt":
+      docsCommand(positional[0]);
+      break;
     case "whoami":
       whoamiCommand();
       break;