# Chinese New Year 2026 Celebration Package (cny26) - Specification

## Overview
A Python terminal application that celebrates Chinese New Year 2026 (Year of the Horse) with animated fireworks, a running horse, and festive text display. The package is designed to be run with `uvx cny26` and automatically published to PyPI.

## Key Features

### 1. Visual Elements
- **Fireworks**: 3D particle system with realistic physics and Chinese New Year themed colors
- **Horse Animation**: Realistic ASCII art horse running from left to right repeatedly
- **Text Display**: "The Year of Horse" displayed continuously at the center
- **Countdown**: Timer showing time until Chinese New Year 2026 (January 29, 2026)

### 2. Audio System
- Firework explosion sound effects
- Stereo positioning based on screen location
- Optional audio (graceful fallback if unavailable)

### 3. Performance
- 60 FPS animation loop
- High-performance BrailleCanvas rendering engine
- Cross-platform compatibility (Unix, Windows, macOS)

## Technical Requirements

### Dependencies
- `rich>=14.2.0` - Terminal UI and panels
- `numpy>=2.4.0` - Mathematical operations and sound generation
- `sounddevice>=0.5.3` - Audio playback (optional)

### Core Components

#### 1. BrailleCanvas Rendering Engine
- Uses Unicode Braille characters (U+2800-U+28FF) for 2x4 pixel patterns
- Supports 24-bit RGB colors and standard ANSI colors
- Optimized with bitwise operations for performance

#### 2. Particle System
- 3D particles with position, velocity, lifetime
- Realistic physics: gravity (50.0 pixels/s²), air resistance (0.97 damping)
- 450-750 particles per firework
- Perspective projection to 2D screen coordinates

#### 3. Horse Animation
- Multiple ASCII art frames for galloping motion
- Smooth left-to-right movement across screen
- Repeating animation loop
- Based on realistic horse anatomy

#### 4. Firework System
- Launch phase with calculated velocity
- 1-second wait at apex before explosion
- Chinese New Year color palette:
  - Red (#FF0000, #DC143C)
  - Gold (#FFD700, #FFA500)
  - Orange (#FF8C00, #FF6347)

#### 5. Text Display
- Large pixel art patterns for "The Year of Horse"
- Centered on screen using canvas dimensions
- Bright colors for visibility

#### 6. Countdown Logic
- Target date: January 29, 2026 (Chinese New Year)
- Local timezone calculation
- Format: "DD:HH:MM:SS" until CNY
- After CNY: display "Happy Chinese New Year 2026!"

#### 7. Sound System
- Generated explosion sounds with noise and low-pass filtering
- Thread-based audio mixing
- Stereo positioning based on firework location
- Graceful fallback if audio unavailable

## User Interface

### Controls
- `SPACE`: Trigger manual firework
- `ESC` or `Ctrl+C`: Exit application
- Auto-running fireworks in background

### Display Layout
```
┌─────────────────────────────────────┐
│         Fireworks Display          │
│                                     │
│         The Year of Horse          │
│                                     │
│    DD:HH:MM:SS until CNY 2026      │
│                                     │
│  🐎←←← Horse Running Animation →→→  │
└─────────────────────────────────────┘
```

## Package Structure

```
cny26/
├── pyproject.toml
├── README.md
├── LICENSE
├── .github/
│   └── workflows/
│       └── publish.yml
├── cny26/
│   ├── __init__.py
│   ├── main.py
│   ├── canvas.py
│   ├── particle.py
│   ├── firework.py
│   ├── horse.py
│   ├── sound.py
│   └── utils.py
└── tests/
    ├── __init__.py
    └── test_cny26.py
```

## Implementation Phases

### Phase 1: Core Infrastructure
1. Package structure with pyproject.toml
2. BrailleCanvas rendering engine
3. Basic particle system

### Phase 2: Visual Elements
1. Firework system with CNY colors
2. Horse animation frames
3. Text display system

### Phase 3: Integration & Polish
1. Main animation loop
2. Countdown logic
3. Sound system
4. Input handling

### Phase 4: Publishing
1. GitHub Actions workflow
2. Trusted publishing setup
3. Documentation and testing

## Cultural Considerations

### Chinese New Year 2026
- **Date**: January 29, 2026
- **Zodiac**: Year of the Horse
- **Element**: Fire Horse (energetic, dynamic)
- **Colors**: Red (luck, joy), Gold (wealth, prosperity)

### Horse Symbolism
- Represents success, speed, perseverance
- Chinese phrase "马到成功" (success arrives swiftly)
- Associated with victory and good fortune

## Performance Targets

- **Frame Rate**: 60 FPS
- **Latency**: <16ms per frame
- **Memory**: <100MB peak usage
- **CPU**: <10% on modern systems

## Compatibility

- **Python**: 3.9+
- **Platforms**: Linux, macOS, Windows
- **Terminals**: Unicode support required
- **Audio**: Optional, fallback to silent mode

## Testing Strategy

### Unit Tests
- Canvas rendering accuracy
- Particle physics calculations
- Horse animation frame timing

### Integration Tests
- Complete animation loop
- Cross-platform compatibility
- Audio system fallback

### Manual Tests
- Visual quality assessment
- Performance under load
- User experience validation

## Success Criteria

1. **Functional**: All features work as specified
2. **Performance**: Smooth 60 FPS animation
3. **Cultural**: Authentic Chinese New Year celebration
4. **Accessible**: Easy installation with `uvx cny26`
5. **Published**: Available on PyPI with automated publishing

## Future Enhancements

### Version 1.1
- Additional zodiac animals
- Customizable colors
- More firework patterns

### Version 1.2
- Interactive horse controls
- Music integration
- Multi-language support

## Risks & Mitigations

### Technical Risks
- **Unicode rendering issues**: Test on multiple terminals
- **Audio compatibility**: Graceful fallback implementation
- **Performance bottlenecks**: Optimize with profiling

### Cultural Risks
- **Inaccurate representation**: Research authentic CNY traditions
- **Offensive content**: Cultural sensitivity review

## Timeline

### Week 1: Core Infrastructure
- Package setup
- Canvas and particle systems

### Week 2: Visual Elements
- Fireworks and horse animation
- Text display integration

### Week 3: Polish & Publishing
- Sound system and input handling
- GitHub Actions and documentation

### Week 4: Testing & Release
- Comprehensive testing
- PyPI publication and promotion