Pepper Scorer Web App Developer
Expert assistant for developing and maintaining the Pepper Scorer web application - an Astro-based scoring system for the card game Pepper with real-time state management, comprehensive award tracking, and series support.
Project Overview
Pepper Scorer is an Astro-based web application for scoring the card game Pepper. It features:
Real-time game state managementComprehensive award tracking (23+ awards)Multi-game series supportlocalStorage persistenceAdvanced statistics system with dynamic award calculationsArchitecture
Core Game Logic (`src/lib/`)
**gameState.ts**: Central game state management with `GameManager` class
Handles hand encoding, score calculation, series management, and undo functionalityHeart of the application's game logic**game.ts**: UI controller and main gameplay orchestration
Complex UI update logicConfetti effects and victory celebration handlingImports and manages all other game components**pepper-awards.ts**: Comprehensive award system
23+ different awards for individual games and seriesAward definitions, evaluation logic, and selection algorithms**statistics-util.ts**: Advanced statistical analysis and HTML generation for game summaries
State Management
Game state managed through `GameManager` class with immutable operationsPersistent storage via `localStorage` with JSON serializationSupport for both single games and multi-game seriesComplex undo system that handles different game phases appropriatelyGame Phases
The game follows a structured progression:
1. **bidder**: Select who won the bid (or throw-in)
2. **bid**: Enter the bid value (4, 5, 6, Moon, Double Moon)
3. **trump**: Select trump suit (or no-trump)
4. **decision**: Defending team decides to play or fold (with optional free tricks)
5. **tricks**: Enter number of tricks won by defending team
Award System
Sophisticated award tracking that analyzes completed games/series:
**Team awards**: Defensive prowess, bidding specialization, comeback achievements**Player awards**: Individual performance metrics, clutch plays, specializations**Dubious awards**: Humorous recognition for poor strategic decisionsAwards are dynamically selected to ensure variety and relevance to game events.
Development Instructions
Build Commands
```bash
Install dependencies
npm install
Start dev server at localhost:4321 (DO NOT run - dev server is always running)
npm run dev
Build production site to ./dist/
npm run build
Preview production build locally
npm run preview
```
Code Quality Checks
```bash
Run ESLint checks on TypeScript files
npx eslint src/**/*.ts
Check TypeScript types
npx tsc --noEmit
```
Pre-Commit Quality Assurance
Run these commands before committing to prevent linting issues and type errors:
```bash
npx tsc --noEmit && npx eslint src/**/*.ts
```
Common issues to watch for:
Unused variables (disable ESLint warnings only when variable will be used later)Possible undefined values when accessing object properties or array indicesMissing type annotations for function parameters and return valuesLaTeX Commands (in rules directory)
```bash
Generate PDF from LaTeX
pdflatex rules.tex
Compile LaTeX with dependencies
latexmk -pdf rules.tex
Convert LaTeX to Markdown
pandoc -o rules.md rules.tex
```
Important Development Patterns
Game State Management
Always use `GameManager.fromJSON()` to restore game state from localStorageCall `updateUI()` after any state changes to keep interface synchronizedUse `gameManager.undo()` for safe state rollback that handles all game phasesState is encoded as compact string arrays for efficient storage and undo operationsUI Updates and Event Handling
The `game.ts` file controls all UI updates through the main `updateUI()` functionButton event handlers are set up once in `setupEventListeners()` and persist throughout gameplayDynamic HTML is generated at runtime for victory celebrations and awards (Astro components can't be used post-build)Always call `hideAllControls()` before showing phase-specific controlsWorking with Awards and Statistics
Award data is generated by `trackAwardData()` in statistics-util.tsUse `selectGameAwards()` and `selectSeriesAwards()` to pick relevant awardsAward evaluation happens dynamically based on actual game performanceStatistics HTML is generated server-side style but executed in the browserPepper Round Logic
First 4 hands of each game are "pepper rounds" with special bidding rulesUse `isPepperRound(handIndex)` to check if special rules applyPepper rounds have automatic bidding progression and forced play/fold decisionsCode Style Guidelines
**TypeScript**: Use strict typing with interfaces/types for all data structures**Imports**: Group external libraries first, then local modules with blank line separator**Path Aliases**: Use `@/` for imports from src directory (configured in astro.config.mjs)**Naming**: camelCase for variables/functions, PascalCase for classes/interfaces/types**Error Handling**: Use null checks before accessing properties, especially for DOM elements**State Management**: Persist critical data in localStorage, pass transient state via props**Comments**: Add comments for complex game logic or non-obvious implementationsProject Organization
`/src/lib/` - Core application logic and utility functions`/src/components/` - Reusable Astro UI components`/src/layouts/` - Page layout templates`/src/pages/` - Page routes (index.astro for setup, game.astro for gameplay)`/rules/` - Game rules documentation in LaTeX and generated MarkdownDevelopment Best Practices
Remember to run tests often when making changes to the codebaseAlways run pre-commit quality checks before committingTest state management thoroughly, especially undo functionalityVerify localStorage persistence after state changesTest award calculation logic with various game scenariosWhen Working on This Project
1. **Read existing code first** - Never propose changes to code you haven't read
2. **Run quality checks** - Always run `npx tsc --noEmit && npx eslint src/**/*.ts` before committing
3. **Test state management** - Verify localStorage and undo functionality after changes
4. **Update UI synchronously** - Always call `updateUI()` after state changes
5. **Maintain type safety** - Use strict TypeScript typing throughout
6. **Follow game phase logic** - Respect the structured progression through game phases
7. **Test award system** - Verify awards are correctly evaluated and selected