# McRogueFace - Development Roadmap

## 🚨 URGENT PRIORITIES - July 9, 2025 🚨

### IMMEDIATE ACTION REQUIRED (Next 48 Hours)

**CRITICAL DEADLINE**: RoguelikeDev Tutorial Event starts July 15 - Need to advertise by July 11!

#### 1. Tutorial Emergency Plan (2 DAYS)
- [ ] **Day 1 (July 9)**: Parts 1-2 (Setup, Moving @, Drawing Map, Entities)
- [ ] **Day 2 (July 10)**: Parts 3-4 (FOV, Combat/AI)
- [ ] **July 11**: Announce on r/roguelikedev with 4 completed parts
- [ ] **July 12-14**: Complete remaining 10 parts before event starts

#### 1b. Sizzle Reel Demo (URGENT)
- [ ] **Expand animation_sizzle_reel_working.py** with Grid/Entity demos:
  - Grid scrolling and zooming animations
  - Entity movement patterns (patrol, chase, flee)
  - Particle effects using entity spawning
  - Tile animation demonstrations
  - Color cycling and transparency effects
  - Mass entity choreography (100+ entities)
  - Performance stress test with 1000+ entities

#### 2. TCOD Integration Sprint
- [ ] **UIGrid TCOD Integration** (8 hours)
  - Add TCODMap* to UIGrid constructor
  - Implement mcrfpy.libtcod.compute_fov()
  - Add batch operations for NumPy-style access
  - Create CellView for ergonomic .at((x,y)) access
- [ ] **UIEntity Pathfinding** (4 hours)
  - Add path_to(target) method using A*
  - Implement Dijkstra maps for multiple targets
  - Cache paths in UIEntity for performance

#### 3. Performance Critical Path
- [ ] **Implement SpatialHash** for 10,000+ entities (2 hours)
- [ ] **Add dirty flag system** to UIGrid (1 hour)
- [ ] **Batch update context managers** (2 hours)
- [ ] **Memory pool for entities** (2 hours)

#### 4. Bug Fixing Pipeline
- [ ] Set up GitHub Issues automation
- [ ] Create test for each bug before fixing
- [ ] Track: Memory leaks, Segfaults, Python/C++ boundary errors

---

## 🎯 STRATEGIC ARCHITECTURE VISION

### Three-Layer Grid Architecture (From Compass Research)
Following successful roguelike patterns (Caves of Qud, Cogmind, DCSS):

1. **Visual Layer** (UIGridPoint) - Sprites, colors, animations
2. **World State Layer** (TCODMap) - Walkability, transparency, physics
3. **Entity Perspective Layer** (UIGridPointState) - Per-entity FOV, knowledge

### Performance Architecture (Critical for 1000x1000 maps)
- **Spatial Hashing** for entity queries (not quadtrees!)
- **Batch Operations** with context managers (10-100x speedup)
- **Memory Pooling** for entities and components
- **Dirty Flag System** to avoid unnecessary updates
- **Zero-Copy NumPy Integration** via buffer protocol

### Key Insight from Research
"Minimizing Python/C++ boundary crossings matters more than individual function complexity"
- Batch everything possible
- Use context managers for logical operations
- Expose arrays, not individual cells
- Profile and optimize hot paths only

---

## Project Status: 🎉 ALPHA 0.1 RELEASE! 🎉

**Current State**: Documentation system complete, TCOD integration urgent  
**Latest Update**: Completed Phase 7 documentation infrastructure (2025-07-08)  
**Branch**: alpha_streamline_2  
**Open Issues**: ~46 remaining + URGENT TCOD/Tutorial work

---

## 📋 TCOD Integration Implementation Details

### Phase 1: Core UIGrid Integration (Day 1 Morning)
```cpp
// UIGrid.h additions
class UIGrid : public UIDrawable {
private:
    TCODMap* world_state;  // Add TCOD map
    std::unordered_map<int, UIGridPointState*> entity_perspectives;
    bool batch_mode = false;
    std::vector<CellUpdate> pending_updates;
```

### Phase 2: Python Bindings (Day 1 Afternoon)
```python
# New API surface
grid = mcrfpy.Grid(100, 100)
grid.compute_fov(player.x, player.y, radius=10)  # Returns visible cells
grid.at((x, y)).walkable = False  # Ergonomic access
with grid.batch_update():  # Context manager for performance
    # All updates batched
```

### Phase 3: Entity Integration (Day 2 Morning)
```python
# UIEntity additions
entity.path_to(target_x, target_y)  # A* pathfinding
entity.flee_from(threat)  # Dijkstra map
entity.can_see(other_entity)  # FOV check
```

### Critical Success Factors:
1. **Batch everything** - Never update single cells in loops
2. **Lazy evaluation** - Only compute FOV for entities that need it
3. **Sparse storage** - Don't store full grids per entity
4. **Profile early** - Find the 20% of code taking 80% of time

---

## Recent Achievements

### 2025-07-08: PyArgHelpers Infrastructure Complete! 🔧
**Standardized Python API Argument Parsing**
- Unified position handling: (x, y) tuples or separate x, y args
- Consistent size parsing: (w, h) tuples or width, height args
- Grid-specific helpers for tile-based positioning
- Proper conflict detection between positional and keyword args
- All UI components migrated: Frame, Caption, Sprite, Grid, Entity
- Improved error messages: "Value must be a number (int or float)"
- Foundation for Phase 7 documentation efforts

### 2025-07-05: ALPHA 0.1 ACHIEVED! 🎊🍾
**All Alpha Blockers Resolved!**
- Z-order rendering with performance optimization (Issue #63)
- Python Sequence Protocol for collections (Issue #69)
- Comprehensive Animation System (Issue #59)
- Moved RenderTexture to Beta (not needed for Alpha)
- **McRogueFace is ready for Alpha release!**

### 2025-07-05: Z-order Rendering Complete! 🎉
**Issue #63 Resolved**: Consistent z-order rendering with performance optimization
- Dirty flag pattern prevents unnecessary per-frame sorting
- Lazy sorting for both Scene elements and Frame children
- Frame children now respect z_index (fixed inconsistency)
- Automatic dirty marking on z_index changes and collection modifications
- Performance: O(1) check for static scenes vs O(n log n) every frame

### 2025-07-05: Python Sequence Protocol Complete! 🎉
**Issue #69 Resolved**: Full sequence protocol implementation for collections
- Complete __setitem__, __delitem__, __contains__ support
- Slice operations with extended slice support (step != 1)
- Concatenation (+) and in-place concatenation (+=) with validation
- Negative indexing throughout, index() and count() methods
- Type safety: UICollection (Frame/Caption/Sprite/Grid), EntityCollection (Entity only)
- Default value support: None for texture/font parameters uses engine defaults

### 2025-07-05: Animation System Complete! 🎉
**Issue #59 Resolved**: Comprehensive animation system with 30+ easing functions
- Property-based animations for all UI classes (Frame, Caption, Sprite, Grid, Entity)
- Individual color component animation (r/g/b/a)
- Sprite sequence animation and text typewriter effects
- Pure C++ execution without Python callbacks
- Delta animation support for relative values

### 2025-01-03: Major Stability Update
**Major Cleanup**: Removed deprecated registerPyAction system (-180 lines)
**Bug Fixes**: 12 critical issues including Grid segfault, Issue #78 (middle click), Entity setters
**New Features**: Entity.index() (#73), EntityCollection.extend() (#27), Sprite validation (#33)
**Test Coverage**: Comprehensive test suite with timer callback pattern established

---

## 🔧 CURRENT WORK: Alpha Streamline 2 - Major Architecture Improvements

### Recent Completions:
- ✅ **Phase 1-4 Complete** - Foundation, API Polish, Entity Lifecycle, Visibility/Performance
- ✅ **Phase 5 Complete** - Window/Scene Architecture fully implemented!
  - Window singleton with properties (#34)
  - OOP Scene support with lifecycle methods (#61)
  - Window resize events (#1)
  - Scene transitions with animations (#105)
- ✅ **Phase 6 Complete** - Rendering Revolution achieved!
  - Grid background colors (#50) ✅
  - RenderTexture overhaul (#6) ✅
  - UIFrame clipping support ✅
  - Viewport-based rendering (#8) ✅

### Active Development:
- **Branch**: alpha_streamline_2
- **Current Phase**: Phase 7 - Documentation & Distribution
- **Achievement**: PyArgHelpers infrastructure complete - standardized Python API
- **Strategic Vision**: See STRATEGIC_VISION.md for platform roadmap
- **Latest**: All UI components now use consistent argument parsing patterns!

### 🏗️ Architectural Dependencies Map

```
Foundation Layer:
├── #71 Base Class (_Drawable) 
│   ├── #10 Visibility System (needs AABB from base)
│   ├── #87 visible property
│   └── #88 opacity property
│
├── #7 Safe Constructors (affects all classes)
│   └── Blocks any new class creation until resolved
│
└── #30 Entity/Grid Integration (lifecycle management)
    └── Enables reliable entity management

Window/Scene Layer:
├── #34 Window Object
│   ├── #61 Scene Object (depends on Window)
│   ├── #14 SFML Exposure (helps implement Window)
│   └── Future: Multi-window support

Rendering Layer:
└── #6 RenderTexture Overhaul
    ├── Enables clipping
    ├── Off-screen rendering
    └── Post-processing effects
```

## 🚀 Alpha Streamline 2 - Comprehensive Phase Plan

### Phase 1: Foundation Stabilization (1-2 weeks)
**Goal**: Safe, predictable base for all future work
```
1. #7 - Audit and fix unsafe constructors (CRITICAL - do first!)
   - Find all manually implemented no-arg constructors
   - Verify map compatibility requirements
   - Make pointer-safe or remove
   
2. #71 - _Drawable base class implementation
   - Common properties: x, y, w, h, visible, opacity
   - Virtual methods: get_bounds(), render()
   - Proper Python inheritance setup
   
3. #87 - visible property
   - Add to base class
   - Update all render methods to check
   
4. #88 - opacity property (depends on #87)
   - 0.0-1.0 float range
   - Apply in render methods
   
5. #89 - get_bounds() method
   - Virtual method returning (x, y, w, h)
   - Override in each UI class
   
6. #98 - move()/resize() convenience methods
   - move(dx, dy) - relative movement
   - resize(w, h) - absolute sizing
```
*Rationale*: Can't build on unsafe foundations. Base class enables all UI improvements.

### Phase 2: Constructor & API Polish (1 week)
**Goal**: Pythonic, intuitive API
```
1. #101 - Standardize (0,0) defaults for all positions
2. #38 - Frame children parameter: Frame(children=[...])
3. #42 - Click handler in __init__: Button(click=callback)
4. #90 - Grid size tuple: Grid(grid_size=(10, 10))
5. #19 - Sprite texture swapping: sprite.texture = new_texture
6. #52 - Grid skip out-of-bounds entities (performance)
```
*Rationale*: Quick wins that make the API more pleasant before bigger changes.

### Phase 3: Entity Lifecycle Management (1 week)
**Goal**: Bulletproof entity/grid relationships
```
1. #30 - Entity.die() and grid association
   - Grid.entities.append(e) sets e.grid = self
   - Grid.entities.remove(e) sets e.grid = None
   - Entity.die() calls self.grid.remove(self)
   - Entity can only be in 0 or 1 grid
   
2. #93 - Vector arithmetic methods
   - add, subtract, multiply, divide
   - distance, normalize, dot product
   
3. #94 - Color helper methods
   - from_hex("#FF0000"), to_hex()
   - lerp(other_color, t) for interpolation
   
4. #103 - Timer objects
   timer = mcrfpy.Timer("my_timer", callback, 1000)
   timer.pause()
   timer.resume()
   timer.cancel()
```
*Rationale*: Games need reliable entity management. Timer objects enable entity AI.

### Phase 4: Visibility & Performance (1-2 weeks)
**Goal**: Only render/process what's needed
```
1. #10 - [UNSCHEDULED] Full visibility system with AABB
   - Postponed: UIDrawables can exist in multiple collections
   - Cannot reliably determine screen position due to multiple render contexts
   - Needs architectural solution for parent-child relationships
   
2. #52 - Grid culling (COMPLETED in Phase 2)
   
3. #39/40/41 - Name system for finding elements
   - name="button1" property on all UIDrawables
   - only_one=True for unique names
   - scene.find("button1") returns element
   - collection.find("enemy*") returns list
   
4. #104 - Basic profiling/metrics
   - Frame time tracking
   - Draw call counting
   - Python vs C++ time split
```
*Rationale*: Performance is feature. Finding elements by name is huge QoL.

### Phase 5: Window/Scene Architecture ✅ COMPLETE! (2025-07-06)
**Goal**: Modern, flexible architecture
```
1. ✅ #34 - Window object (singleton first)
   window = mcrfpy.Window.get()
   window.resolution = (1920, 1080)
   window.fullscreen = True
   window.vsync = True
   
2. ✅ #1 - Window resize events
   scene.on_resize(self, width, height) callback implemented
   
3. ✅ #61 - Scene object (OOP scenes)
   class MenuScene(mcrfpy.Scene):
       def on_keypress(self, key, state):
           # handle input
       def on_enter(self):
           # setup UI
       def on_exit(self):
           # cleanup
       def update(self, dt):
           # frame update
           
4. ✅ #14 - SFML exposure research
   - Completed comprehensive analysis
   - Recommendation: Direct integration as mcrfpy.sfml
   - SFML 3.0 migration deferred to late 2025
   
5. ✅ #105 - Scene transitions
   mcrfpy.setScene("menu", "fade", 1.0)
   # Supports: fade, slide_left, slide_right, slide_up, slide_down
```
*Result*: Entire window/scene system modernized with OOP design!

### Phase 6: Rendering Revolution (3-4 weeks) ✅ COMPLETE!
**Goal**: Professional rendering capabilities
```
1. ✅ #50 - Grid background colors [COMPLETED]
   grid.background_color = mcrfpy.Color(50, 50, 50)
   - Added background_color property with animation support
   - Default dark gray background (8, 8, 8, 255)
   
2. ✅ #6 - RenderTexture overhaul [COMPLETED]
   ✅ Base infrastructure in UIDrawable
   ✅ UIFrame clip_children property
   ✅ Dirty flag optimization system
   ✅ Nested clipping support
   ✅ UIGrid already has appropriate RenderTexture implementation
   ❌ UICaption/UISprite clipping not needed (no children)
   
3. ✅ #8 - Viewport-based rendering [COMPLETED]
   - Fixed game resolution (window.game_resolution)
   - Three scaling modes: "center", "stretch", "fit"
   - Window to game coordinate transformation
   - Mouse input properly scaled with windowToGameCoords()
   - Python API fully integrated
   - Tests: test_viewport_simple.py, test_viewport_visual.py, test_viewport_scaling.py
   
4. #106 - Shader support [DEFERRED TO POST-PHASE 7]
   sprite.shader = mcrfpy.Shader.load("glow.frag")
   frame.shader_params = {"intensity": 0.5}
   
5. #107 - Particle system [DEFERRED TO POST-PHASE 7]
   emitter = mcrfpy.ParticleEmitter()
   emitter.texture = spark_texture
   emitter.emission_rate = 100
   emitter.lifetime = (0.5, 2.0)
```

**Phase 6 Achievement Summary**:
- Grid backgrounds (#50) ✅ - Customizable background colors with animation
- RenderTexture overhaul (#6) ✅ - UIFrame clipping with opt-in architecture
- Viewport rendering (#8) ✅ - Three scaling modes with coordinate transformation
- UIGrid already had optimal RenderTexture implementation for its use case
- UICaption/UISprite clipping unnecessary (no children to clip)
- Performance optimized with dirty flag system
- Backward compatibility preserved throughout
- Effects/Shader/Particle systems deferred for focused delivery

*Rationale*: This unlocks professional visual effects but is complex.

### Phase 7: Documentation & Distribution (1-2 weeks)
**Goal**: Ready for the world
```
1. ✅ #85 - Replace all "docstring" placeholders [COMPLETED 2025-07-08]
2. ✅ #86 - Add parameter documentation [COMPLETED 2025-07-08]
3. ✅ #108 - Generate .pyi type stubs for IDE support [COMPLETED 2025-07-08]
4. ❌ #70 - PyPI wheel preparation [CANCELLED - Architectural mismatch]
5. API reference generator tool
```

## 📋 Critical Path & Parallel Tracks

### 🔴 **Critical Path** (Must do in order)
**Safe Constructors (#7)** → **Base Class (#71)** → **Visibility (#10)** → **Window (#34)** → **Scene (#61)**

### 🟡 **Parallel Tracks** (Can be done alongside critical path)

**Track A: Entity Systems**
- Entity/Grid integration (#30)
- Timer objects (#103)
- Vector/Color helpers (#93, #94)

**Track B: API Polish**  
- Constructor improvements (#101, #38, #42, #90)
- Sprite texture swap (#19)
- Name/search system (#39/40/41)

**Track C: Performance**
- Grid culling (#52)
- Visibility culling (part of #10)
- Profiling tools (#104)

### 💎 **Quick Wins to Sprinkle Throughout**
1. Color helpers (#94) - 1 hour
2. Vector methods (#93) - 1 hour  
3. Grid backgrounds (#50) - 30 minutes
4. Default positions (#101) - 30 minutes

### 🎯 **Recommended Execution Order**

**Week 1-2**: Foundation (Critical constructors + base class)  
**Week 3**: Entity lifecycle + API polish  
**Week 4**: Visibility system + performance  
**Week 5-6**: Window/Scene architecture  
**Week 7-9**: Rendering revolution (or defer to gamma)  
**Week 10**: Documentation + release prep

### 🆕 **New Issues to Create/Track**

1. [x] **Timer Objects** - Pythonic timer management (#103) - *Completed Phase 3*
2. [ ] **Event System Enhancement** - Mouse enter/leave, drag, right-click  
3. [ ] **Resource Manager** - Centralized asset loading
4. [ ] **Serialization System** - Save/load game state
5. [x] **Scene Transitions** - Fade, slide, custom effects (#105) - *Completed Phase 5*
6. [x] **Profiling Tools** - Performance metrics (#104) - *Completed Phase 4*
7. [ ] **Particle System** - Visual effects framework (#107)
8. [ ] **Shader Support** - Custom rendering effects (#106)

---

## 📋 Phase 6 Implementation Strategy

### RenderTexture Overhaul (#6) - Technical Approach

**Current State**:
- UIGrid already uses RenderTexture for entity rendering
- Scene transitions use RenderTextures for smooth animations
- Direct rendering to window for Frame, Caption, Sprite

**Implementation Plan**:
1. **Base Infrastructure**:
   - Add `sf::RenderTexture* target` to UIDrawable base
   - Modify `render()` to check if target exists
   - If target: render to texture, then draw texture to parent
   - If no target: render directly (backward compatible)

2. **Clipping Support**:
   - Frame enforces bounds on children via RenderTexture
   - Children outside bounds are automatically clipped
   - Nested frames create render texture hierarchy

3. **Performance Optimization**:
   - Lazy RenderTexture creation (only when needed)
   - Dirty flag system (only re-render when changed)
   - Texture pooling for commonly used sizes

4. **Integration Points**:
   - Scene transitions already working with RenderTextures
   - UIGrid can be reference implementation
   - Test with deeply nested UI structures

**Quick Wins Before Core Work**:
1. **Grid Background (#50)** - 30 min implementation
   - Add `background_color` and `background_texture` properties
   - Render before entities in UIGrid::render()
   - Good warm-up before tackling RenderTexture

2. **Research Tasks**:
   - Study UIGrid's current RenderTexture usage
   - Profile scene transition performance
   - Identify potential texture size limits

---

## 🚀 NEXT PHASE: Beta Features & Polish

### Alpha Complete! Moving to Beta Priorities:
1. ~~**#69** - Python Sequence Protocol for collections~~ - *Completed! (2025-07-05)*
2. ~~**#63** - Z-order rendering for UIDrawables~~ - *Completed! (2025-07-05)*
3. ~~**#59** - Animation system~~ - *Completed! (2025-07-05)*
4. **#6** - RenderTexture concept - *Extensive Overhaul*
5. ~~**#47** - New README.md for Alpha release~~ - *Completed*
- [x] **#78** - Middle Mouse Click sends "C" keyboard event - *Fixed*
- [x] **#77** - Fix error message copy/paste bug - *Fixed*
- [x] **#74** - Add missing `Grid.grid_y` property - *Fixed*  
- [ ] **#37** - Fix Windows build module import from "scripts" directory - *Isolated Fix*
      Issue #37 is **on hold** until we have a Windows build environment available. I actually suspect this is already fixed by the updates to the makefile, anyway.
- [x] **Entity Property Setters** - Fix "new style getargs format" error - *Fixed*
- [x] **Sprite Texture Setter** - Fix "error return without exception set" - *Fixed*
- [x] **keypressScene() Validation** - Add proper error handling - *Fixed*

### 🔄 Complete Iterator System
**Status**: Core iterators complete (#72 closed), Grid point iterators still pending

- [ ] **Grid Point Iterator Implementation** - Complete the remaining grid iteration work
- [x] **#73** - Add `entity.index()` method for collection removal - *Fixed*
- [x] **#69** ⚠️ **Alpha Blocker** - Refactor all collections to use Python Sequence Protocol - *Completed! (2025-07-05)*

**Dependencies**: Grid point iterators → #73 entity.index() → #69 Sequence Protocol overhaul

---

## 🗂 ISSUE TRIAGE BY SYSTEM (78 Total Issues)

### 🎮 Core Engine Systems

#### Iterator/Collection System (2 issues)
- [x] **#73** - Entity index() method for removal - *Fixed*
- [x] **#69** ⚠️ **Alpha Blocker** - Sequence Protocol refactor - *Completed! (2025-07-05)*

#### Python/C++ Integration (7 issues)  
- [x] **#76** - UIEntity derived type preservation in collections - *Multiple Integrations*
- [ ] **#71** - Drawable base class hierarchy - *Extensive Overhaul*
- [ ] **#70** - PyPI wheel distribution - *Extensive Overhaul*
- [~] **#32** - Executable behave like `python` command - *Extensive Overhaul* *(90% Complete: -h, -V, -c, -m, -i, script execution, sys.argv, --exec all implemented. Only stdin (-) support missing)*
- [ ] **#35** - TCOD as built-in module - *Extensive Overhaul*  
- [~] **#14** - Expose SFML as built-in module - *Research Complete, Implementation Pending*
- [ ] **#46** - Subinterpreter threading tests - *Multiple Integrations*

#### UI/Rendering System (12 issues)
- [x] **#63** ⚠️ **Alpha Blocker** - Z-order for UIDrawables - *Multiple Integrations*
- [x] **#59** ⚠️ **Alpha Blocker** - Animation system - *Completed! (2025-07-05)*  
- [ ] **#6** ⚠️ **Alpha Blocker** - RenderTexture for all UIDrawables - *Extensive Overhaul*
- [ ] **#10** - UIDrawable visibility/AABB system - *Extensive Overhaul*
- [ ] **#8** - UIGrid RenderTexture viewport sizing - *Multiple Integrations*
- [x] **#9** - UIGrid RenderTexture resize handling - *Multiple Integrations*
- [ ] **#52** - UIGrid skip out-of-bounds entities - *Isolated Fix*
- [ ] **#50** - UIGrid background color field - *Isolated Fix*
- [ ] **#19** - Sprite get/set texture methods - *Multiple Integrations*
- [ ] **#17** - Move UISprite position into sf::Sprite - *Isolated Fix*
- [x] **#33** - Sprite index validation against texture range - *Fixed*

#### Grid/Entity System (6 issues)
- [ ] **#30** - Entity/Grid association management (.die() method) - *Extensive Overhaul*
- [ ] **#16** - Grid strict mode for entity knowledge/visibility - *Extensive Overhaul*  
- [ ] **#67** - Grid stitching for infinite worlds - *Extensive Overhaul*
- [ ] **#15** - UIGridPointState cleanup and standardization - *Multiple Integrations*
- [ ] **#20** - UIGrid get_grid_size standardization - *Multiple Integrations*
- [x] **#12** - GridPoint/GridPointState forbid direct init - *Isolated Fix*

#### Scene/Window Management (5 issues) 
- [x] **#61** - Scene object encapsulating key callbacks - *Completed Phase 5*
- [x] **#34** - Window object for resolution/scaling - *Completed Phase 5*
- [ ] **#62** - Multiple windows support - *Extensive Overhaul*  
- [ ] **#49** - Window resolution & viewport controls - *Multiple Integrations*
- [x] **#1** - Scene resize event handling - *Completed Phase 5*

### 🔧 Quality of Life Features

#### UI Enhancement Features (8 issues)
- [ ] **#39** - Name field on UIDrawables - *Multiple Integrations*
- [ ] **#40** - `only_one` arg for unique naming - *Multiple Integrations*
- [ ] **#41** - `.find(name)` method for collections - *Multiple Integrations*
- [ ] **#38** - `children` arg for Frame initialization - *Isolated Fix*
- [ ] **#42** - Click callback arg for UIDrawable init - *Isolated Fix*  
- [x] **#27** - UIEntityCollection.extend() method - *Fixed*
- [ ] **#28** - UICollectionIter for scene ui iteration - *Isolated Fix*
- [ ] **#26** - UIEntityCollectionIter implementation - *Isolated Fix*

### 🧹 Refactoring & Cleanup

#### Code Cleanup (7 issues)
- [x] **#3** ⚠️ **Alpha Blocker** - Remove `McRFPy_API::player_input` - *Completed*
- [x] **#2** ⚠️ **Alpha Blocker** - Review `registerPyAction` necessity - *Completed*
- [ ] **#7** - Remove unsafe no-argument constructors - *Multiple Integrations*
- [ ] **#21** - PyUIGrid dealloc cleanup - *Isolated Fix*
- [ ] **#75** - REPL thread separation from SFML window - *Multiple Integrations*

### 📚 Demo & Documentation

#### Documentation (2 issues)
- [x] **#47** ⚠️ **Alpha Blocker** - Alpha release README.md - *Isolated Fix*
- [ ] **#48** - Dependency compilation documentation - *Isolated Fix*

#### Demo Projects (6 issues)  
- [ ] **#54** - Jupyter notebook integration demo - *Multiple Integrations*
- [ ] **#55** - Hunt the Wumpus AI demo - *Multiple Integrations*
- [ ] **#53** - Web interface input demo - *Multiple Integrations* *(New automation API could help)*
- [ ] **#45** - Accessibility mode demos - *Multiple Integrations* *(New automation API could help test)*
- [ ] **#36** - Dear ImGui integration tests - *Extensive Overhaul*
- [ ] **#65** - Python Explorer scene (replaces uitest) - *Extensive Overhaul*

---

## 🎮 STRATEGIC DIRECTION

### Engine Philosophy Maintained
- **C++ First**: Performance-critical code stays in C++
- **Python Close Behind**: Rich scripting without frame-rate impact  
- **Game-Ready**: Each improvement should benefit actual game development

### Architecture Goals
1. **Clean Inheritance**: Drawable → UI components, proper type preservation
2. **Collection Consistency**: Uniform iteration, indexing, and search patterns
3. **Resource Management**: RAII everywhere, proper lifecycle handling
4. **Multi-Platform**: Windows/Linux feature parity maintained

---

## 📚 REFERENCES & CONTEXT

**Issue Dependencies** (Key Chains):
- Iterator System: Grid points → #73 → #69 (Alpha Blocker)
- UI Hierarchy: #71 → #63 (Alpha Blocker) 
- Rendering: #6 (Alpha Blocker) → #8, #9 → #10
- Entity System: #30 → #16 → #67
- Window Management: #34 → #49, #61 → #62

**Commit References**:
- 167636c: Iterator improvements (UICollection/UIEntityCollection complete)
- Recent work: 7DRL 2025 completion, RPATH updates, console improvements

**Architecture Files**:
- Iterator patterns: src/UICollection.cpp, src/UIGrid.cpp
- Python integration: src/McRFPy_API.cpp, src/PyObjectUtils.h
- Game implementation: src/scripts/ (Crypt of Sokoban complete game)

---

## 🔮 FUTURE VISION: Pure Python Extension Architecture

### Concept: McRogueFace as a Traditional Python Package
**Status**: Unscheduled - Long-term vision
**Complexity**: Major architectural overhaul

Instead of being a C++ application that embeds Python, McRogueFace could be redesigned as a pure Python extension module that can be installed via `pip install mcrogueface`.

### Technical Approach
1. **Separate Core Engine from Python Embedding**
   - Extract SFML rendering, audio, and input into C++ extension modules
   - Remove embedded CPython interpreter
   - Use Python's C API to expose functionality

2. **Module Structure**
   ```
   mcrfpy/
   ├── __init__.py          # Pure Python coordinator
   ├── _core.so             # C++ rendering/game loop extension
   ├── _sfml.so             # SFML bindings
   ├── _audio.so            # Audio system bindings
   └── engine.py            # Python game engine logic
   ```

3. **Inverted Control Flow**
   - Python drives the main loop instead of C++
   - C++ extensions handle performance-critical operations
   - Python manages game logic, scenes, and entity systems

### Benefits
- **Standard Python Packaging**: `pip install mcrogueface`
- **Virtual Environment Support**: Works with venv, conda, poetry
- **Better IDE Integration**: Standard Python development workflow  
- **Easier Testing**: Use pytest, standard Python testing tools
- **Cross-Python Compatibility**: Support multiple Python versions
- **Modular Architecture**: Users can import only what they need

### Challenges
- **Major Refactoring**: Complete restructure of codebase
- **Performance Considerations**: Python-driven main loop overhead
- **Build Complexity**: Multiple extension modules to compile
- **Platform Support**: Need wheels for many platform/Python combinations
- **API Stability**: Would need careful design to maintain compatibility

### Implementation Phases (If Pursued)
1. **Proof of Concept**: Simple SFML binding as Python extension
2. **Core Extraction**: Separate rendering from Python embedding
3. **Module Design**: Define clean API boundaries
4. **Incremental Migration**: Move systems one at a time
5. **Compatibility Layer**: Support existing games during transition

### Example Usage (Future Vision)
```python
import mcrfpy
from mcrfpy import Scene, Frame, Sprite, Grid

# Create game directly in Python
game = mcrfpy.Game(width=1024, height=768)

# Define scenes using Python classes
class MainMenu(Scene):
    def on_enter(self):
        self.ui.append(Frame(100, 100, 200, 50))
        self.ui.append(Sprite("logo.png", x=400, y=100))
    
    def on_keypress(self, key, pressed):
        if key == "ENTER" and pressed:
            self.game.set_scene("game")

# Run the game
game.add_scene("menu", MainMenu())
game.run()
```

This architecture would make McRogueFace a first-class Python citizen, following standard Python packaging conventions while maintaining high performance through C++ extensions.

---

## 🚀 IMMEDIATE NEXT STEPS (Priority Order)

### Today (July 9) - EXECUTE NOW:
1. **Start Tutorial Part 1** - Basic setup and @ movement (2 hours)
2. **Implement UIGrid.at((x,y))** - CellView pattern (1 hour)
3. **Create Grid demo** for sizzle reel (1 hour)
4. **Fix any blocking bugs** discovered during tutorial writing

### Tomorrow (July 10) - CRITICAL PATH:
1. **Tutorial Parts 2-4** - Map drawing, entities, FOV, combat
2. **Implement compute_fov()** in UIGrid
3. **Add batch_update context manager**
4. **Expand sizzle reel** with entity choreography

### July 11 - ANNOUNCEMENT DAY:
1. **Polish 4 tutorial parts**
2. **Create announcement post** for r/roguelikedev
3. **Record sizzle reel video**
4. **Submit announcement** by end of day

### Architecture Decision Log:
- **DECIDED**: Use three-layer architecture (visual/world/perspective)
- **DECIDED**: Spatial hashing over quadtrees for entities
- **DECIDED**: Batch operations are mandatory, not optional
- **DECIDED**: TCOD integration as mcrfpy.libtcod submodule
- **DECIDED**: Tutorial must showcase McRogueFace strengths, not mimic TCOD

### Risk Mitigation:
- **If TCOD integration delays**: Use pure Python FOV for tutorial
- **If performance issues**: Focus on <100x100 maps for demos
- **If tutorial incomplete**: Ship with 4 solid parts + roadmap
- **If bugs block progress**: Document as "known issues" and continue

---

*Last Updated: 2025-07-09 (URGENT SPRINT MODE)*
*Next Review: July 11 after announcement*