create-airjam 0.1.0 → 0.1.2

package/dist/index.js

@@ -49,7 +49,12 @@ async function main() {
   console.log(kleur.cyan(`
 Creating project in ${targetDir}...
 `));
-  await fs.copy(templateDir, targetDir);
+  await fs.copy(templateDir, targetDir, {
+    filter: (src) => {
+      const relativePath = path.relative(templateDir, src);
+      return !relativePath.includes("node_modules") && !relativePath.endsWith("pnpm-lock.yaml") && !relativePath.endsWith(".npmrc");
+    }
+  });
   const pkgPath = path.join(targetDir, "package.json");
   if (fs.existsSync(pkgPath)) {
     const pkg = await fs.readJson(pkgPath);
@@ -59,8 +64,11 @@ Creating project in ${targetDir}...
   console.log(kleur.green("\u2713 Project created successfully!\n"));
   console.log("Next steps:\n");
   console.log(kleur.cyan(`  cd ${projectName}`));
-  console.log(kleur.cyan("  npm install"));
-  console.log(kleur.cyan("  npm run dev"));
+  console.log(kleur.cyan("  pnpm install"));
+  console.log(kleur.cyan("  cp env.example .env"));
+  console.log(kleur.cyan("  # Edit .env and set AIR_JAM_MASTER_KEY"));
+  console.log(kleur.cyan("  pnpm run dev:server  # Terminal 1 - Start server"));
+  console.log(kleur.cyan("  pnpm run dev         # Terminal 2 - Start game"));
   console.log("");
   console.log(
     kleur.dim("Then open http://localhost:5173 and scan the QR code with your phone!")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-airjam",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI to scaffold Air Jam game projects",
   "type": "module",
   "license": "MIT",
@@ -29,8 +29,10 @@
     "templates"
   ],
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch"
+    "extract-docs": "tsx scripts/extract-docs.ts",
+    "build": "pnpm extract-docs && tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "pnpm build"
   },
   "dependencies": {
     "commander": "^14.0.0",
@@ -42,6 +44,7 @@
     "@types/fs-extra": "^11.0.4",
     "@types/prompts": "^2.4.9",
     "tsup": "^8.5.1",
+    "tsx": "^4.19.2",
     "typescript": "~5.9.3"
   }
 }

package/templates/pong/.env.example

@@ -0,0 +1,11 @@
+# ============================================================================
+# Game Configuration
+# ============================================================================
+# Server URL - defaults to localhost:4000 in development
+# For production, set to your official Air Jam server URL: wss://api.air-jam.app
+VITE_AIR_JAM_SERVER_URL=http://localhost:4000
+
+# API Key - optional for local development (not required when using local server)
+# Required for production - get from Air Jam platform
+VITE_AIR_JAM_API_KEY=
+

package/templates/pong/.env.local

@@ -0,0 +1,10 @@
+# ============================================================================
+# Game Configuration
+# ============================================================================
+# Server URL - defaults to localhost:4000 in development
+# For production, set to your official Air Jam server URL: wss://api.air-jam.app
+VITE_AIR_JAM_SERVER_URL=http://localhost:4000
+
+# API Key - optional for local development (not required when using local server)
+# Required for production - get from Air Jam platform
+VITE_AIR_JAM_API_KEY=aj_live_972f8d8063e5413fa23d2981906d24fe

package/templates/pong/AI_INSTRUCTIONS.md

@@ -0,0 +1,44 @@
+---
+description: Universal project rules and tech stack standards
+globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx, **/*.json"
+alwaysApply: true
+---
+# Identity & Goals
+- You are a senior frontend architect and full-stack engineer.
+- Focus on modern, type-safe, and functional programming patterns.
+- Prioritize maintainability and strict type safety over brevity.
+- Use airjam-docs for documentation on the Air Jam SDK.
+
+# Tech Stack (Strict)
+- **Manager**: pnpm (monorepo structure)
+- **Framework**: React (Frontend), Vite (Build)
+- **Language**: TypeScript (Strict mode)
+- **Styling**: Tailwind CSS + Shadcn UI
+- **State**: Zustand (Global)
+
+# Coding Conventions
+- **Naming**:
+  - `camelCase` for variables and functions.
+  - `PascalCase` for React components and Type definitions.
+  - `kebab-case` for all file names (e.g., `user-profile-card.tsx`).
+- **Component Syntax**: Use `const Component = (props: Props) => {}`. Avoid `React.FC`.
+- **Exports**: Use named exports. Do NOT use default exports.
+- **Direct Access**: Do NOT pass props (prop drilling) if data is available via Zustand store or React Context.
+
+# Type Safety & Linting & State Management
+- **Zod First**: Define schema validation with Zod before implementing logic.
+- **No Any**: `any` are strictly forbidden. Use generic types or specific interfaces.
+- **TSC**: Code must pass `tsc` check without errors.
+- **JSDoc**: Use JSDoc for utility functions to describe behavior (omit @param/@returns unless complex).
+- **Zustand**: Use atomic selectors when consuming state to prevent unnecessary re-renders.
+
+# File Structure & Refactoring
+- **Co-location**:
+  - If a component is used only once, keep it in the same file as the parent.
+  - If a component is used >1 time, extract to `components/` folder.
+- **Shared Code**: All shared schemas/types must reside in the `packages/shared` workspace.
+
+# Agent Behavior
+- **Dependencies**: Always use `pnpm add` to install new packages.
+- **Verification**: Verify file paths before creation. Ensure imports match the `kebab-case` filename convention.
+- **Cleanliness**: Remove unused imports and dead code immediately; do not comment them out.

package/templates/pong/README.md

@@ -0,0 +1,111 @@
+# Air Jam Game Template - Pong
+
+A starter template for building multiplayer games with Air Jam. This template includes a simple Pong game that demonstrates the core Air Jam features.
+
+## Getting Started
+
+### Installation
+
+1. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+2. Configure environment variables (optional - defaults work for local dev):
+   ```bash
+   mv .env.example .env.local
+   ```
+   
+   Then edit `.env.local` with your settings if needed.
+
+## Local Development
+
+### Option 1: Run Server and Game Separately (Recommended)
+
+**Terminal 1 - Start the local server:**
+```bash
+pnpm run dev:server
+```
+
+The server will start on `http://localhost:4000` in development mode (no authentication required).
+
+**Terminal 2 - Start the game:**
+```bash
+pnpm run dev
+```
+
+The game will be available at `http://localhost:5173` (or the port Vite assigns).
+
+### Option 2: Use the Official Air Jam Server
+
+If you prefer to use the official Air Jam server instead of running locally:
+
+1. Get your API key from the [Air Jam Platform](https://air-jam.app)
+2. Set in `.env.local`:
+   ```bash
+   VITE_AIR_JAM_SERVER_URL=https://api.air-jam.app
+   VITE_AIR_JAM_API_KEY=your-api-key-here
+   ```
+3. Run only the game:
+   ```bash
+   pnpm run dev
+   ```
+
+## Playing the Game
+
+1. Open the game URL in your browser (host view)
+2. Scan the QR code with your phone to open the controller / open the controller view in your browser
+3. Use the controller to play Pong!
+
+## Project Structure
+
+```
+src/
+  ├── App.tsx              # Main app component with routing
+  ├── host-view.tsx        # Game host view (runs the game)
+  ├── controller-view.tsx  # Controller view (mobile interface)
+  ├── types.ts             # Game input schema and types
+  ├── store.ts             # Shared networked state store
+  └── main.tsx             # Entry point
+```
+
+## Environment Variables
+
+See `.env.example` for all available environment variables. Key variables:
+
+- `VITE_AIR_JAM_SERVER_URL` - Server URL (defaults to localhost:4000 for local dev)
+- `VITE_AIR_JAM_API_KEY` - API key (optional for local dev, required for production)
+
+## Production Deployment
+
+### Deploying to Vercel
+
+1. Set environment variables in Vercel:
+   - `VITE_AIR_JAM_SERVER_URL` - Your official Air Jam server URL
+   - `VITE_AIR_JAM_API_KEY` - Your API key from the Air Jam platform
+
+2. Deploy:
+   ```bash
+   vercel
+   ```
+
+The game will connect to the official Air Jam server - no local server needed!
+
+### Building for Production
+
+```bash
+pnpm run build
+```
+
+The built files will be in the `dist/` directory.
+
+## Learn More
+
+- [Air Jam Documentation](https://air-jam.app/docs)
+- [Platform](https://air-jam.app)
+- [Examples](https://github.com/vucinatim/air-jam/tree/main/apps)
+
+## License
+
+MIT
+

package/templates/pong/airjam-docs/getting-started/architecture/page.md

@@ -0,0 +1,165 @@
+# Architecture
+
+Air Jam consists of four main components in a monorepo structure. This page explains how they work together to enable multiplayer gaming with smartphone controllers.
+
+## System Overview
+
+## Components
+
+### 1. Platform (`apps/platform`)
+
+**Role:** Central hub for the Air Jam ecosystem
+
+**Technology:** Next.js 15, TypeScript, tRPC, BetterAuth, PostgreSQL (Drizzle ORM)
+
+**Key Features:**
+- **Developer Portal** - Account management, API key generation, analytics
+- **Game Catalog** - Submit, manage, and discover Air Jam games
+- **Arcade Mode** - Browse and launch games from a unified interface
+- **Controller Shell** - Persistent mobile wrapper that loads game controllers
+
+**Arcade Mode Flow:**
+```
+1. Player scans QR on arcade screen
+2. Platform loads controller shell on phone
+3. Player browses games using phone as remote
+4. Game launches → controller switches to game's joypad
+5. Game ends → returns to arcade browser
+```
+
+### 2. Server (`packages/server`)
+
+**Role:** Real-time communication backbone
+
+**Technology:** Node.js, Express, Socket.IO, PostgreSQL
+
+**Core Services:**
+
+**Socket Events:**
+
+### 3. SDK (`packages/sdk`)
+
+**Role:** Developer toolkit for building Air Jam games
+
+**Technology:** React, TypeScript, Socket.IO Client, Zustand, Zod
+
+**Architecture:**
+
+**Key Design Decisions:**
+
+1. **Provider Pattern** - Single provider for configuration, multiple hooks for access
+2. **Lightweight Hooks** - `useGetInput`, `useSendSignal` don't trigger re-renders
+3. **Input Latching** - Ensures rapid button taps are never missed
+4. **Schema Validation** - Type-safe input with runtime validation
+
+### 4. Prototype Game (`apps/prototype-game`)
+
+**Role:** Reference implementation showcasing SDK capabilities
+
+**Technology:** React, Vite, React Three Fiber, Rapier Physics
+
+**Demonstrates:**
+- Host-side game logic with physics
+- Controller UI with joystick and buttons
+- Player spawning/despawning on join/leave
+- Haptic feedback on collisions
+- Multiple game modes (CTF, survival)
+
+## Run Modes
+
+The SDK automatically detects and adapts to different deployment scenarios:
+
+### Standalone Mode
+
+Your game runs independently with direct WebSocket connection.
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│  Your Game   │◀───▶│  AirJam      │◀───▶│  Controller  │
+│  (Host)      │     │  Server      │     │  (Phone)     │
+└──────────────┘     └──────────────┘     └──────────────┘
+```
+
+**Use case:** Self-hosted games, development, custom deployments
+
+### Arcade Mode
+
+Game runs inside an iframe on the Air Jam Platform.
+
+```
+┌─────────────────────────────────────────┐
+│  Air Jam Platform (Parent)              │
+│  ┌───────────────────────────────────┐  │
+│  │  Your Game (iframe)               │  │
+│  │  • Receives join token            │  │
+│  │  • Controlled player routing      │  │
+│  └───────────────────────────────────┘  │
+└─────────────────────────────────────────┘
+```
+
+**Use case:** Featured on Air Jam arcade, game discovery
+
+### Bridge Mode
+
+Controller runs inside platform's shell (iframe communication).
+
+```
+┌─────────────────────────────────────────┐
+│  Platform Controller Shell (Parent)     │
+│  ┌───────────────────────────────────┐  │
+│  │  Your Controller UI (iframe)      │  │
+│  │  • Input via postMessage          │  │
+│  │  • Seamless game switching        │  │
+│  └───────────────────────────────────┘  │
+└─────────────────────────────────────────┘
+```
+
+**Use case:** Arcade mode controllers, persistent session
+
+## Data Flow
+
+### Input Path (Controller → Game)
+
+```
+1. Player moves joystick on phone
+2. Controller calls sendInput({ vector: {x, y}, action: false })
+3. SDK sends controller:input event to server
+4. Server routes to host socket
+5. Host SDK's InputManager receives input
+6. InputManager validates with Zod schema
+7. InputManager applies latching if configured
+8. Game calls getInput(playerId) in game loop
+9. Returns typed, validated, latched input
+```
+
+### Signal Path (Game → Controller)
+
+```
+1. Game detects collision
+2. Host calls sendSignal("HAPTIC", { pattern: "heavy" }, playerId)
+3. SDK sends host:signal event to server
+4. Server routes to target controller(s)
+5. Controller SDK receives signal
+6. SDK triggers navigator.vibrate() with pattern
+7. Player feels haptic feedback
+```
+
+## Security
+
+### API Key Authentication
+
+- Games must provide valid API key for production
+- Keys are validated against platform database
+- Rate limiting prevents abuse
+
+### Room Isolation
+
+- Each room has unique 4-character code
+- Controllers can only join with correct code
+- Input is only routed to the designated host
+
+### Input Validation
+
+- Zod schemas validate all incoming input
+- Invalid input is rejected with console warning
+- Protects game logic from malformed data

package/templates/pong/airjam-docs/getting-started/game-ideas/page.md

@@ -0,0 +1,114 @@
+# Game Ideas for Air Jam
+
+A collection of game concepts that leverage Air Jam's unique architecture: **High-Frequency Input Streams** (Socket.IO) + **Reliable Shared State** (AirJam Store).
+
+---
+
+## Tier 1: Arcade Classics (Easy)
+
+### Neon Tanks
+
+- Top-down arena shooter (4-8 players)
+- Dual stick controls: movement + turret aiming
+- Tap to fire
+- **Key Feature:** Demonstrates dual stick capability on touchscreen
+
+### Super Sumo Balls
+
+- Rolling balls on tilting platform
+- Use phone gyroscope/accelerometer to tilt
+- Haptic feedback on collisions
+- **Key Feature:** Phone sensors + haptic signals
+
+---
+
+## Tier 2: Party & Social Games (Medium)
+
+### The Traitor (Among Us style)
+
+- 8 players: 6 crew, 2 traitors
+- Hidden roles shown only on phone
+- Task minigames on controller
+- Voting UI on phone
+- **Key Feature:** Secret information per player (killer app for phone controllers)
+
+### Sketchy Business (Pictionary style)
+
+- Draw prompts on phone canvas
+- Drawings appear on TV
+- **Key Feature:** Touchscreen as natural drawing pad
+
+### Quiz Show Royale
+
+- Fastest finger first trivia
+- Personalized feedback (green/red + vibration)
+- **Key Feature:** Input timestamping for speed
+
+---
+
+## Tier 3: Co-op Chaos (Medium-Hard)
+
+### Starship Bridge Simulator
+
+- 4 players with different roles
+- Each player gets different UI on phone
+- Asymmetrical gameplay
+- **Key Feature:** Different React components per controller
+
+### Ghost Hunter
+
+- 1 vs 3 asymmetrical gameplay
+- Ghost sees minimap on phone only
+- Hunters use joysticks on TV
+- **Key Feature:** Private screen advantage
+
+---
+
+## Tier 4: Strategy & Card Games (Hard)
+
+### Poker Night / Blackjack
+
+- Private cards on phone
+- Betting UI on phone
+- Public table on TV
+- **Key Feature:** Hidden information per player
+
+### Artillery Wars (Worms style)
+
+- Turn-based tank battle
+- Aiming interface on phone (angle/power sliders)
+- Weapon selection on phone
+- **Key Feature:** Complex menus on touchscreen
+
+---
+
+## Tier 5: Experimental (Advanced)
+
+### The Crowd Pixel (r/place style)
+
+- 50+ players
+- Each controls a pixel/cursor
+- Collaborative painting
+- **Key Feature:** Tests scalability
+
+### Minority Report UI
+
+- Phone as trackpad
+- Gesture controls
+- **Key Feature:** Phone as input device
+
+---
+
+## Key Mechanics Enabled
+
+```
+| Mechanic          | Example           | Technical Feature                       |
+|-------------------|-------------------|-----------------------------------------|
+| Secret Roles      | Mafia / Traitor   | `useSharedState` (filter by `playerId`) |
+| Private Inventory | RPG / Poker       | Shared Store + React UI on Phone        |
+| Motion Steering   | Racing / Rolling  | Device Accelerometer → Input Stream     |
+| Fastest Finger    | Quiz Show         | Input Latching (Timestamps)             |
+| Physical Feedback | Fighting / Action | `host.sendSignal("HAPTIC")`             |
+| Drawing           | Pictionary        | Canvas API + Data Packet                |
+| Asymmetry         | Ghost Hunter      | Different Views per Role                |
+```

package/templates/pong/airjam-docs/getting-started/introduction/page.md

@@ -0,0 +1,122 @@
+# Introduction
+
+Air Jam is a platform for building **"AirConsole-style" multiplayer games** where a computer/TV acts as the host display and smartphones become game controllers. The platform enables developers to create interactive games with minimal setup while providing players with an intuitive, scan-and-play experience.
+
+## Key Features
+
+- **Zero App Download**: Players join by scanning a QR code—no app store required
+- **Instant Multiplayer**: Seamlessly connect up to 8 smartphones as controllers
+- **Developer Friendly**: Built with modern web technologies (React, TypeScript)
+- **Type Safe**: End-to-end type safety with Zod schema validation
+- **Performance Optimized**: Latching system ensures no input is ever missed
+- **Haptic Feedback**: Send vibration patterns to controllers for game events
+
+## How It Works
+
+## Quick Start
+
+### 1. Install the SDK
+
+```bash
+pnpm add @air-jam/sdk
+```
+
+### 2. Wrap Your App
+
+```tsx filename="src/App.tsx"
+import { AirJamProvider } from "@air-jam/sdk";
+import { z } from "zod";
+
+// Define your input schema
+const gameInputSchema = z.object({
+  vector: z.object({ x: z.number(), y: z.number() }),
+  action: z.boolean(),
+  ability: z.boolean(),
+  timestamp: z.number(),
+});
+
+export const App = () => (
+  <AirJamProvider
+    input={{
+      schema: gameInputSchema,
+      latch: {
+        booleanFields: ["action", "ability"],
+        vectorFields: ["vector"],
+      },
+    }}
+  >
+    <Routes>
+      <Route path="/" element={<HostView />} />
+      <Route path="/joypad" element={<ControllerView />} />
+    </Routes>
+  </AirJamProvider>
+);
+```
+
+### 3. Create Your Host View
+
+```tsx filename="src/components/HostView.tsx"
+import { useAirJamHost } from "@air-jam/sdk";
+import { QRCode } from "./QRCode";
+
+const HostView = () => {
+  const host = useAirJamHost({
+    onPlayerJoin: (player) => {
+      console.log(`${player.label} joined!`);
+      spawnPlayer(player.id, player.color);
+    },
+    onPlayerLeave: (id) => {
+      console.log(`Player ${id} left`);
+      removePlayer(id);
+    },
+  });
+
+  return (
+    <div>
+      <h1>Room: {host.roomId}</h1>
+      <QRCode value={host.joinUrl} />
+      <p>Players: {host.players.length}</p>
+      
+      {/* Your game canvas */}
+      <GameCanvas players={host.players} getInput={host.getInput} />
+    </div>
+  );
+};
+```
+
+### 4. Create Your Controller View
+
+```tsx filename="src/components/ControllerView.tsx"
+import { useAirJamController } from "@air-jam/sdk";
+import { Joystick, Button } from "./ui";
+
+const ControllerView = () => {
+  const controller = useAirJamController();
+  
+  const handleInput = (vector: { x: number; y: number }, action: boolean) => {
+    controller.sendInput({
+      vector,
+      action,
+      ability: false,
+      timestamp: Date.now(),
+    });
+  };
+
+  if (controller.connectionStatus !== "connected") {
+    return <div>Connecting to room {controller.roomId}...</div>;
+  }
+
+  return (
+    <div>
+      <Joystick onMove={(x, y) => handleInput({ x, y }, false)} />
+      <Button onPress={() => handleInput({ x: 0, y: 0 }, true)}>Fire</Button>
+    </div>
+  );
+};
+```
+
+## Next Steps
+
+- [Architecture](/docs/getting-started/architecture) - Understand the system design
+- [Hooks Reference](/docs/sdk/hooks) - Complete API documentation
+- [Input System](/docs/sdk/input-system) - Learn about latching and validation