Corpán Development Rules

# Corpán Development Rules

## Project Structure

This is a monorepo for Corpán, a language learning platform. Key directories:

- `corpan-app/` - Main Tauri desktop/mobile app
- `packs/` - Game packs and SDK (games are a type of pack)
  - `packs/sdk/` - Pack SDK for development
  - `packs/hover-runner/` - 3D vocabulary runner game
  - `packs/hanzipan/` - Chinese character handwriting game (reference for UI polish)
  - `packs/juice-squeeze/` - Sentence building puzzle game
- `games/` - Legacy location (games have moved to packs/)
- `dja/` - Django backend with language data (27k phrases, 27 languages)

## Pack Development Guidelines

### Pack Structure (follow hover-runner and hanzipan patterns)

Each pack in `packs/` should have:
- `manifest.json` - Pack metadata and configuration
- `package.json` - Dependencies and build scripts  
- `src/` - TypeScript source code
- `dist/` - Built output (git-ignored)
- `scripts/dev-corpan.mjs` - Hot reload dev script
- Uses Vite for bundling
- Uses Babylon.js for 3D games

### manifest.json Format
```json
{
  "id": "pack_id",
  "name": "Pack Name",
  "version": "0.1.0",
  "entry": "dist/app.js",
  "styles": ["dist/app.css"],
  "entryType": "script",
  "sdkVersion": "0.1.0"
}
```

### Development Workflow
1. From pack directory: `npm run dev:corpan`
   - Starts Vite in watch mode
   - Starts HTTP server on port 8989
   - Auto-updates manifest devRevision on changes
2. Load in Corpán via developer mode (tap version 7x)
3. Install from URL: `http://localhost:8989/[pack-name]/manifest.json`

### Integration with Corpán
Packs receive vocabulary data from Corpán's database via HostApi:
- `hostApi.getRandomEntry()` - Get random phrase with translations
- `hostApi.speak()` - TTS for phrases
- `hostApi.getStackConfig()` - User's language settings
- Should support all 27 languages Corpán supports

### UI/UX Reference
**Look at `packs/hanzipan/styles.css` for design patterns:**
- CSS variables for theming (--bg, --ink, --accent, etc.)
- Warm color palette (#f5efe4 background, #0b6b6f accent)
- Glassmorphism cards with backdrop-filter
- Responsive sizing with clamp()
- Subtle animations

### Code Style
- TypeScript for all pack code
- Functional, modular architecture
- Clear separation: game logic, rendering, data
- Zustand for state management

## Current Context
- Latest version: Corpán 0.8.x
- Active packs: hover-runner, hanzipan, juice-squeeze
- 27 languages, 27k+ phrases in database