star-sdk 0.1.0 → 0.1.9

package/README.md

@@ -1,6 +1,6 @@
 # Star SDK
 
-Unified SDK for browser game development. Audio, canvas, and leaderboards.
+Browser game SDK with built-in leaderboards (no backend needed), mobile-safe audio, and multiplayer. Works on iOS Safari. Perfect for AI-generated games.
 
 ```javascript
 import Star from 'star-sdk';
@@ -10,6 +10,47 @@ Star.game(ctx => { ... });
 Star.leaderboard.submit(1500);
 ```
 
+## Why Star SDK?
+
+| Need | Without Star | With Star |
+|------|--------------|-----------|
+| **Leaderboards** | Build a backend, database, auth | `Star.leaderboard.submit(score)` |
+| **Mobile audio** | Handle unlock gestures, AudioContext resume | Just call `Star.audio.play()` |
+| **HiDPI canvas** | Manual DPR scaling, coordinate math | Automatic |
+| **iOS Safari** | Debug audio/touch issues for hours | It just works |
+
+### vs Phaser/PixiJS
+Star SDK is simpler. No scene system, no asset loader config. Built-in leaderboards mean you ship a complete game, not just a demo.
+
+### vs Kaboom.js
+Star SDK works on mobile out of the box. Leaderboards and multiplayer are included.
+
+### vs Vanilla Canvas
+Star SDK handles the annoying stuff: audio unlocking, DPR scaling, touch coordinates, game loop timing. You write game logic, not boilerplate.
+
+## One-Liner Game
+
+```bash
+npx star-sdk init && cat > index.html << 'EOF'
+<script type="module">
+import Star from 'https://esm.sh/star-sdk';
+Star.game(ctx => {
+  let score = 0;
+  Star.audio.preload({ coin: 'coin' });
+  ctx.loop(() => {
+    ctx.ctx.fillStyle = '#1a1a2e';
+    ctx.ctx.fillRect(0, 0, ctx.width, ctx.height);
+    ctx.ctx.fillStyle = '#fff';
+    ctx.ctx.font = '48px sans-serif';
+    ctx.ctx.fillText(score, ctx.width/2 - 20, ctx.height/2);
+  });
+  ctx.canvas.onclick = () => { score++; Star.audio.play('coin'); };
+});
+</script>
+EOF
+open index.html  # or: python -m http.server
+```
+
 ## Installation
 
 ```bash

package/dist/cli.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import "star-sdk-cli";

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";var u=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var O=Object.getOwnPropertyNames;var M=Object.prototype.hasOwnProperty;var x=(e,t)=>{for(var r in t)u(e,r,{get:t[r],enumerable:!0})},h=(e,t,r,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let s of O(t))!M.call(e,s)&&s!==r&&u(e,s,{get:()=>t[s],enumerable:!(o=b(t,s))||o.enumerable});return e};var G=e=>h(u({},"__esModule",{value:!0}),e);var I={};x(I,{Star:()=>c,audio:()=>f.createStarAudio,default:()=>A,game:()=>S.game,leaderboard:()=>g.createLeaderboard,multiplayer:()=>y.createMultiplayer});module.exports=G(I);var f=require("star-audio"),S=require("star-canvas"),g=require("star-leaderboard"),y=require("star-multiplayer"),p=null,l=null,i=null,d=()=>typeof window<"u",L=()=>typeof process<"u"&&process.versions?.node;function m(){if(d()||!L())return null;try{let e=require("fs"),r=require("path").join(process.cwd(),".starrc");if(!e.existsSync(r))return null;let o=e.readFileSync(r,"utf-8");return JSON.parse(o)}catch{return null}}function a(){if(!l&&d()){let{createStarAudio:e}=require("star-audio");l=e()}return l}function n(){if(!i){let e=p?.gameId,t=p?.apiBase;if(!e){let o=m();o?.gameId&&(e=o.gameId)}let{createLeaderboard:r}=require("star-leaderboard");i=r({gameId:e,apiBase:t})}return i}var c={init(e){p=e,i&&(i.destroy?.(),i=null)},audio:{play:(e,t)=>a().play(e,t),preload:e=>a().preload(e),music:{crossfadeTo:(e,t)=>a().music.crossfadeTo(e,t),stop:e=>a().music.stop(e)},setMusicVolume:e=>a().setMusicVolume(e),setSfxVolume:e=>a().setSfxVolume(e),setMute:e=>a().setMute(e),toggleMute:()=>a().toggleMute(),isMuted:()=>a().isMuted()},game(e,t){let{game:r}=require("star-canvas");r(e,t)},leaderboard:{submit:e=>n().submit(e),show:()=>n().show(),getScores:e=>n().getScores(e),share:e=>n().share(e)},multiplayer:{async create(e){let{createMultiplayer:t}=require("star-multiplayer"),r=t();return await r.start(e),r}},loadConfig:m,version:"0.1.0"},A=c;0&&(module.exports={Star,audio,game,leaderboard,multiplayer});
+"use strict";var p=Object.defineProperty;var h=Object.getOwnPropertyDescriptor;var G=Object.getOwnPropertyNames;var A=Object.prototype.hasOwnProperty;var L=(e,t)=>{for(var r in t)p(e,r,{get:t[r],enumerable:!0})},I=(e,t,r,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of G(t))!A.call(e,i)&&i!==r&&p(e,i,{get:()=>t[i],enumerable:!(s=h(t,i))||s.enumerable});return e};var w=e=>I(p({},"__esModule",{value:!0}),e);var v={};L(v,{Star:()=>g,audio:()=>b.createStarAudio,default:()=>B,game:()=>O.game,leaderboard:()=>M.createLeaderboard,multiplayer:()=>x.createMultiplayer});module.exports=w(v);var d=require("star-audio"),m=require("star-leaderboard"),c=require("star-canvas"),f=require("star-multiplayer"),b=require("star-audio"),O=require("star-canvas"),M=require("star-leaderboard"),x=require("star-multiplayer"),u=null,l=null,o=null,y=()=>typeof window<"u",C=()=>typeof process<"u"&&process.versions?.node;function S(){if(y()||!C())return null;try{let e=require("fs"),r=require("path").join(process.cwd(),".starrc");if(!e.existsSync(r))return null;let s=e.readFileSync(r,"utf-8");return JSON.parse(s)}catch{return null}}function a(){return!l&&y()&&(l=(0,d.createStarAudio)()),l}var P="https://buildwithstar.com";function n(){if(!o){let e=u?.gameId,t=u?.apiBase??P;if(!e){let r=S();r?.gameId&&(e=r.gameId)}o=(0,m.createLeaderboard)({gameId:e,apiBase:t})}return o}var g={init(e){u=e,o&&(o.destroy?.(),o=null)},audio:{play:(e,t)=>a().play(e,t),preload:e=>a().preload(e),music:{crossfadeTo:(e,t)=>a().music.crossfadeTo(e,t),stop:e=>a().music.stop(e)},setMusicVolume:e=>a().setMusicVolume(e),setSfxVolume:e=>a().setSfxVolume(e),setMute:e=>a().setMute(e),toggleMute:()=>a().toggleMute(),isMuted:()=>a().isMuted()},game(e,t){(0,c.game)(e,t)},leaderboard:{submit:e=>n().submit(e),show:()=>n().show(),getScores:e=>n().getScores(e),share:e=>n().share(e)},multiplayer:{async create(e){let t=(0,f.createMultiplayer)();return await t.start(e),t}},loadConfig:S,version:"0.1.0"},B=g;0&&(module.exports={Star,audio,game,leaderboard,multiplayer});

package/dist/index.mjs

@@ -1 +1 @@
-var o=(e=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(e,{get:(t,r)=>(typeof require<"u"?require:t)[r]}):e)(function(e){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+e+'" is not supported')});import{createStarAudio as b}from"star-audio";import{game as M}from"star-canvas";import{createLeaderboard as h}from"star-leaderboard";import{createMultiplayer as L}from"star-multiplayer";var l=null,u=null,i=null,p=()=>typeof window<"u",m=()=>typeof process<"u"&&process.versions?.node;function d(){if(p()||!m())return null;try{let e=o("fs"),r=o("path").join(process.cwd(),".starrc");if(!e.existsSync(r))return null;let s=e.readFileSync(r,"utf-8");return JSON.parse(s)}catch{return null}}function a(){if(!u&&p()){let{createStarAudio:e}=o("star-audio");u=e()}return u}function n(){if(!i){let e=l?.gameId,t=l?.apiBase;if(!e){let s=d();s?.gameId&&(e=s.gameId)}let{createLeaderboard:r}=o("star-leaderboard");i=r({gameId:e,apiBase:t})}return i}var c={init(e){l=e,i&&(i.destroy?.(),i=null)},audio:{play:(e,t)=>a().play(e,t),preload:e=>a().preload(e),music:{crossfadeTo:(e,t)=>a().music.crossfadeTo(e,t),stop:e=>a().music.stop(e)},setMusicVolume:e=>a().setMusicVolume(e),setSfxVolume:e=>a().setSfxVolume(e),setMute:e=>a().setMute(e),toggleMute:()=>a().toggleMute(),isMuted:()=>a().isMuted()},game(e,t){let{game:r}=o("star-canvas");r(e,t)},leaderboard:{submit:e=>n().submit(e),show:()=>n().show(),getScores:e=>n().getScores(e),share:e=>n().share(e)},multiplayer:{async create(e){let{createMultiplayer:t}=o("star-multiplayer"),r=t();return await r.start(e),r}},loadConfig:d,version:"0.1.0"},S=c;export{c as Star,b as audio,S as default,M as game,h as leaderboard,L as multiplayer};
+var p=(e=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(e,{get:(t,a)=>(typeof require<"u"?require:t)[a]}):e)(function(e){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+e+'" is not supported')});import{createStarAudio as m}from"star-audio";import{createLeaderboard as c}from"star-leaderboard";import{game as f}from"star-canvas";import{createMultiplayer as y}from"star-multiplayer";import{createStarAudio as w}from"star-audio";import{game as P}from"star-canvas";import{createLeaderboard as v}from"star-leaderboard";import{createMultiplayer as F}from"star-multiplayer";var n=null,s=null,o=null,l=()=>typeof window<"u",S=()=>typeof process<"u"&&process.versions?.node;function u(){if(l()||!S())return null;try{let e=p("fs"),a=p("path").join(process.cwd(),".starrc");if(!e.existsSync(a))return null;let d=e.readFileSync(a,"utf-8");return JSON.parse(d)}catch{return null}}function r(){return!s&&l()&&(s=m()),s}var g="https://buildwithstar.com";function i(){if(!o){let e=n?.gameId,t=n?.apiBase??g;if(!e){let a=u();a?.gameId&&(e=a.gameId)}o=c({gameId:e,apiBase:t})}return o}var b={init(e){n=e,o&&(o.destroy?.(),o=null)},audio:{play:(e,t)=>r().play(e,t),preload:e=>r().preload(e),music:{crossfadeTo:(e,t)=>r().music.crossfadeTo(e,t),stop:e=>r().music.stop(e)},setMusicVolume:e=>r().setMusicVolume(e),setSfxVolume:e=>r().setSfxVolume(e),setMute:e=>r().setMute(e),toggleMute:()=>r().toggleMute(),isMuted:()=>r().isMuted()},game(e,t){f(e,t)},leaderboard:{submit:e=>i().submit(e),show:()=>i().show(),getScores:e=>i().getScores(e),share:e=>i().share(e)},multiplayer:{async create(e){let t=y();return await t.start(e),t}},loadConfig:u,version:"0.1.0"},A=b;export{b as Star,w as audio,A as default,P as game,v as leaderboard,F as multiplayer};

package/package.json

@@ -1,17 +1,25 @@
 {
   "name": "star-sdk",
-  "version": "0.1.0",
+  "version": "0.1.9",
   "private": false,
-  "description": "Unified Star SDK for game development. Audio, canvas, leaderboards, multiplayer.",
+  "description": "Browser game SDK with built-in leaderboards (no backend needed) and mobile-safe audio. Works on iOS Safari. Perfect for AI-generated games.",
   "type": "module",
   "sideEffects": false,
+  "bin": {
+    "star-sdk": "./dist/cli.mjs"
+  },
   "starSdk": {
     "internalImport": "import Star from '/star-sdk/v1/star.js';",
     "publicImport": "import Star from 'star-sdk';",
-    "outputs": [{ "src": "dist/index.mjs", "dest": "v1/star.js" }],
+    "outputs": [
+      {
+        "src": "dist/index.mjs",
+        "dest": "v1/star.js"
+      }
+    ],
     "skill": {
       "name": "star-sdk",
-      "description": "Unified Star SDK for game development. Audio, canvas, leaderboards, multiplayer."
+      "description": "Browser game SDK with built-in leaderboards (no backend needed) and mobile-safe audio. Works on iOS Safari. Perfect for AI-generated games."
     }
   },
   "exports": {
@@ -25,7 +33,8 @@
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "build": "tsup",
@@ -38,14 +47,14 @@
     "web",
     "audio",
     "canvas",
-    "leaderboard",
-    "multiplayer"
+    "leaderboard"
   ],
   "dependencies": {
     "star-audio": "*",
     "star-canvas": "*",
     "star-leaderboard": "*",
-    "star-multiplayer": "*"
+    "star-multiplayer": "*",
+    "star-sdk-cli": "*"
   },
   "devDependencies": {
     "tsup": "^8.0.0",

package/skills/star-sdk/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: star-sdk
+description: Use when you need a game that works on mobile without audio issues, has leaderboards without building a backend, or needs canvas rendering without DPR/sizing bugs. Handles iOS Safari audio unlocking, DPR scaling, and coordinate conversion automatically.
+---
+
+# Star SDK
+
+Browser game development SDK with audio, canvas, and leaderboards.
+
+## 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) |
+
+## 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 = '#111827';
+    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');
+  };
+});
+```
+
+## Initialization (Required for Leaderboards)
+
+If using leaderboards outside the Star platform (local dev, self-hosted), initialize with your game ID:
+
+```javascript
+import Star from 'star-sdk';
+
+// Get your gameId from .starrc (created by: npx star-sdk init "Game Name")
+Star.init({ gameId: 'your-game-id-here' });
+```
+
+## Common Patterns
+
+### Game Over -> Submit Score -> Show Leaderboard
+
+```javascript
+function gameOver(finalScore) {
+  Star.leaderboard.submit(finalScore);
+  Star.leaderboard.show();
+}
+```
+
+### Audio (It Just Works)
+
+Star.audio handles mobile audio unlocking automatically. Just call `play()` - no special handling needed.
+
+```javascript
+Star.audio.preload({ coin: 'coin', jump: 'jump' });
+Star.audio.play('coin');  // Works on mobile, desktop, everywhere
+```
+
+### 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';
+
+// Initialize for leaderboard support (get gameId from .starrc)
+Star.init({ gameId: 'your-game-id' });
+
+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 = '#111827';
+    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 = '#3b82f6';
+    c.beginPath();
+    c.arc(50, playerY, 15, 0, Math.PI * 2);
+    c.fill();
+
+    // Draw obstacles
+    c.fillStyle = '#a855f7';
+    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.

package/skills/star-sdk/audio.md

@@ -0,0 +1,119 @@
+**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?**
+- ✅ **Mobile-first** - Works on iOS/Android, handles audio unlock automatically, plays even in silent mode
+- ✅ **Never throws** - Missing audio files? Game keeps running with clear warnings
+- ✅ **Zero-config** - Works on first play, no setup needed
+- ✅ **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();
+` ` `

package/skills/star-sdk/canvas.md

@@ -0,0 +1,611 @@
+**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:
+
+  - ✅ No "cannot read addEventListener of null"
+  - ✅ No canvas sizing/DPR/blur issues
+  - ✅ No accidentally wiping the canvas with `innerHTML`
+  - ✅ Games work identically on ALL devices (fixed 16:9 with letterboxing)
+
+-----
+
+### Fixed 16:9 Resolution
+
+**Default: 640×360 (landscape) or 360×640 (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.
+
+  - ✅ **Use this for UI elements** (buttons, menus) inside your `ui.render()` HTML.
+  - ✅ 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 → playing → 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? → `'pointer'` | Aim precisely? → `'crosshair'` | WASD/touch only? → `'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×360 - for platformers, shooters, racing
+    - `'portrait'`: 360×640 - 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×360 (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×360 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×360 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×640 portrait with letterboxing
+```
+
+### Recipe 4: Custom Resolution
+
+For games that need different dimensions (e.g., pixel art at 320×180).
+
+```ts
+import { game } from 'star-canvas';
+
+game(({ ctx, width, height, loop, toStagePoint, canvas }) => {
+  // Custom 320×180 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. ❌ Forgetting `toStagePoint()` in pointermove → `createDrag()` fixes this
+2. ❌ No drag offset (piece "jumps" to cursor) → `createDrag()` fixes this
+3. ❌ Using `e.clientX/clientY` directly → `createDrag()` fixes this
+4. ❌ Not clearing state on pointerup → `createDrag()` fixes this
+5. ❌ Missing `setPointerCapture()` (drags break outside canvas) → **You must add this!**
+
+**Recommendation:** Use `createDrag()` + `setPointerCapture()` for bulletproof drag-and-drop.

package/skills/star-sdk/leaderboard.md

@@ -0,0 +1,258 @@
+**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.