docs: comprehensive alpha_streamline_2 plan and strategic vision

- Add 7-phase development plan for alpha_streamline_2 branch - Define architectural dependencies and critical path - Identify new issues needed (Timer objects, event system, etc.) - Add strategic vision document with 3 transformative directions - Timeline: 10-12 weeks to solid Beta foundation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-07-05 22:16:52 -04:00 · 2025-07-05 22:16:52 -04:00 · a88ce0e259
parent 5b6b0cc8ff
commit a88ce0e259
2 changed files with 777 additions and 0 deletions
--- a/ROADMAP.md
+++ b/ROADMAP.md
@ -0,0 +1,551 @@
+# McRogueFace - Development Roadmap
+
+## Project Status: 🎉 ALPHA 0.1 RELEASE! 🎉
+
+**Current State**: Alpha release achieved! All critical blockers resolved!  
+**Latest Update**: Moved RenderTexture (#6) to Beta - Alpha is READY! (2025-07-05)  
+**Branch**: interpreter_mode (ready for alpha release merge)  
+**Open Issues**: ~46 remaining (non-blocking quality-of-life improvements)
+
+---
+
+## Recent Achievements
+
+### 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:
+- ✅ **ISSUE_FIX_PLAN.md merged** - Fixed 10+ critical issues
+- ✅ **Grid.at() flexible arguments** - Tuple, keyword, and pos support
+- ✅ **Alpha 0.1 Release achieved** - All blockers resolved!
+
+### Active Development:
+- **Branch**: alpha_streamline_2
+- **Goal**: Complete architectural improvements for solid Beta foundation
+- **Timeline**: 10-12 weeks comprehensive plan
+- **Strategic Vision**: See STRATEGIC_VISION.md for platform roadmap
+
+### 🏗️ 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. NEW - 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 - Full visibility system with AABB
+   - bool visible() - False if outside view or hidden
+   - bool hidden - internal visibility toggle
+   - AABB() considers parent offsets recursively
+   - Non-visible elements can't be clicked
+   
+2. #52 - Grid culling (if not done 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. NEW - 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 (2-3 weeks)
+**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 = lambda w, h: handle_resize(w, h)
+   
+3. #61 - Scene object (OOP scenes)
+   class MenuScene(mcrfpy.Scene):
+       def on_keypress(self, key):
+           # handle input
+       def on_enter(self):
+           # setup UI
+           
+4. #14 - SFML exposure research
+   - Option 1: Use existing pysfml
+   - Option 2: mcrfpy.sfml submodule
+   - Option 3: Direct integration
+   
+5. NEW - Scene transitions
+   scene.fade_to(next_scene, duration=1.0)
+   scene.slide_out(direction="left")
+```
+*Rationale*: This is the "big leap" - modernizes the entire API.
+
+### Phase 6: Rendering Revolution (3-4 weeks) 
+**Goal**: Professional rendering capabilities
+```
+1. #6 - RenderTexture overhaul
+   - All UIDrawables render to RenderTexture
+   - Enables clipping to parent bounds
+   - Off-screen rendering for effects
+   
+2. #8 - Viewport-based rendering
+   - RenderTexture matches viewport
+   - Proper scaling/letterboxing
+   
+3. #50 - Grid background colors
+   grid.background_color = mcrfpy.Color(50, 50, 50)
+   
+4. NEW - Shader support (stretch goal)
+   sprite.shader = "glow.frag"
+   
+5. NEW - Particle system (stretch goal)
+   particles = mcrfpy.ParticleEmitter()
+```
+*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
+2. #86 - Add parameter documentation
+3. Generate .pyi type stubs for IDE support
+4. #70 - PyPI wheel preparation
+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 (NEW)
+- 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 (NEW)
+
+### 💎 **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**
+
+1. **Timer Objects** - Pythonic timer management
+2. **Event System Enhancement** - Mouse enter/leave, drag, right-click
+3. **Resource Manager** - Centralized asset loading
+4. **Serialization System** - Save/load game state
+5. **Scene Transitions** - Fade, slide, custom effects
+6. **Profiling Tools** - Performance metrics
+7. **Particle System** - Visual effects framework
+8. **Shader Support** - Custom rendering effects
+
+---
+
+## 🚀 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*
+- [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
+
+---
+
+## ✅ ALPHA 0.1 RELEASE ACHIEVED! (All Blockers Complete)
+
+### ✅ All Alpha Requirements Complete!
+- [x] **#69** - Collections use Python Sequence Protocol - *Completed! (2025-07-05)*
+- [x] **#63** - Z-order rendering for UIDrawables - *Completed! (2025-07-05)*  
+- [x] **#59** - Animation system for arbitrary UIDrawable fields - *Completed! (2025-07-05)*
+- [x] **#47** - New README.md for Alpha release - *Completed*
+- [x] **#3** - Remove deprecated `McRFPy_API::player_input` - *Completed*
+- [x] **#2** - Remove `registerPyAction` system - *Completed*
+
+### 📋 Moved to Beta:
+- [ ] **#6** - RenderTexture concept - *Moved to Beta (not needed for Alpha)*
+
+---
+
+## 🗂 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)  
+- [ ] **#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 - *Extensive Overhaul*
+- [ ] **#46** - Subinterpreter threading tests - *Multiple Integrations*
+
+#### UI/Rendering System (12 issues)
+- [ ] **#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*
+- [ ] **#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*
+- [ ] **#12** - GridPoint/GridPointState forbid direct init - *Isolated Fix*
+
+#### Scene/Window Management (5 issues)
+- [ ] **#61** - Scene object encapsulating key callbacks - *Extensive Overhaul*
+- [ ] **#34** - Window object for resolution/scaling - *Extensive Overhaul*
+- [ ] **#62** - Multiple windows support - *Extensive Overhaul*  
+- [ ] **#49** - Window resolution & viewport controls - *Multiple Integrations*
+- [ ] **#1** - Scene resize event handling - *Isolated Fix*
+
+### 🔧 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)
+- [ ] **#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*
+
+---
+
+## 🎯 RECOMMENDED TRIAGE SEQUENCE
+
+### Phase 1: Foundation Stabilization (1-2 weeks)
+```
+✅ COMPLETE AS OF 2025-01-03:
+1. ✅ Fix Grid Segfault - Grid now supports None/null textures
+2. ✅ Fix #78 Middle Mouse Click bug - Event type checking added
+3. ✅ Fix Entity/Sprite property setters - PyVector conversion fixed
+4. ✅ Fix #77 - Error message copy/paste bug fixed
+5. ✅ Fix #74 - Grid.grid_y property added
+6. ✅ Fix keypressScene() validation - Now rejects non-callable
+7. ✅ Fix Sprite texture setter - No longer returns error without exception
+8. ✅ Fix PyVector x/y properties - Were returning None
+
+REMAINING IN PHASE 1:
+9. ✅ Fix #73 - Entity.index() method for removal
+10. ✅ Fix #27 - EntityCollection.extend() method
+11. ✅ Fix #33 - Sprite index validation
+12. Alpha Blockers (#3, #2) - Remove deprecated methods
+```
+
+### Phase 2: Alpha Release Preparation (4-6 weeks)  
+```
+1. Collections Sequence Protocol (#69) - Major refactor, alpha blocker
+2. Z-order rendering (#63) - Essential UI improvement, alpha blocker  
+3. RenderTexture overhaul (#6) - Core rendering improvement, alpha blocker
+4. ✅ Animation system (#59) - COMPLETE! 30+ easing functions, all UI properties
+5. ✅ Documentation (#47) - README.md complete, #48 dependency docs remaining
+```
+
+### Phase 3: Engine Architecture (6-8 weeks)
+```
+1. Drawable base class (#71) - Clean up inheritance patterns  
+2. Entity/Grid associations (#30) - Proper lifecycle management
+3. Window object (#34) - Scene/window architecture
+4. UIDrawable visibility (#10) - Rendering optimization
+```
+
+### Phase 4: Advanced Features (8-12 weeks)
+```
+1. Grid strict mode (#16) - Entity knowledge/visibility system
+2. SFML/TCOD integration (#14, #35) - Expose native libraries
+3. Scene object refactor (#61) - Better input handling  
+4. Name-based finding (#39, #40, #41) - UI element management
+5. Demo projects (#54, #55, #36) - Showcase capabilities
+```
+
+### Ongoing/Low Priority
+```
+- PyPI distribution (#70) - Community access
+- Multiple windows (#62) - Advanced use cases  
+- Grid stitching (#67) - Infinite world support
+- Accessibility (#45) - Important but not blocking
+- Subinterpreter tests (#46) - Performance research
+```
+
+---
+
+## 📊 DIFFICULTY ASSESSMENT SUMMARY
+
+**Isolated Fixes (24 issues)**: Single file/function changes
+- Bugfixes: #77, #74, #37, #78
+- Simple features: #73, #52, #50, #33, #17, #38, #42, #27, #28, #26, #12, #1
+- Cleanup: #3, #2, #21, #47, #48
+
+**Multiple Integrations (28 issues)**: Cross-system changes  
+- UI/Rendering: #63, #8, #9, #19, #39, #40, #41
+- Grid/Entity: #15, #20, #76, #46, #49, #75
+- Features: #54, #55, #53, #45, #7
+
+**Extensive Overhauls (26 issues)**: Major architectural changes
+- Core Systems: #69, #59, #6, #10, #30, #16, #67, #61, #34, #62
+- Integration: #71, #70, #32, #35, #14  
+- Advanced: #36, #65
+
+---
+
+## 🎮 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
+
+### Success Metrics for Alpha 0.1
+- [ ] All Alpha Blocker issues resolved (5 of 7 complete: #69, #59, #47, #3, #2)
+- [ ] Grid point iteration complete and tested
+- [ ] Clean build on Windows and Linux  
+- [ ] Documentation sufficient for external developers
+- [ ] At least one compelling demo (Wumpus or Jupyter integration)
+
+---
+
+## 📚 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)
+
+---
+
+*Last Updated: 2025-07-05*  
+*Total Open Issues: 62* (from original 78)  
+*Alpha Status: 🎉 COMPLETE! All blockers resolved!*  
+*Achievement Unlocked: Alpha 0.1 Release Ready*  
+*Next Phase: Beta features including RenderTexture (#6), advanced UI patterns, and platform polish*
+
--- a/STRATEGIC_VISION.md
+++ b/STRATEGIC_VISION.md
@ -0,0 +1,226 @@
+# McRogueFace Strategic Vision: Beyond Alpha
+
+## 🎯 Three Transformative Directions
+
+### 1. **The Roguelike Operating System** 🖥️
+
+Transform McRogueFace into a platform where games are apps:
+
+#### Core Platform Features
+- **Game Package Manager**: `mcrf install dungeon-crawler`
+- **Hot-swappable Game Modules**: Switch between games without restarting
+- **Shared Asset Library**: Common sprites, sounds, and UI components
+- **Cross-Game Saves**: Universal character/inventory system
+- **Multi-Game Sessions**: Run multiple roguelikes simultaneously in tabs
+
+#### Technical Implementation
+```python
+# Future API Example
+import mcrfpy.platform as platform
+
+# Install and launch games
+platform.install("nethack-remake")
+platform.install("pixel-dungeon-port")
+
+# Create multi-game session
+session = platform.MultiGameSession()
+session.add_tab("nethack-remake", save_file="warrior_lvl_15.sav")
+session.add_tab("pixel-dungeon-port", new_game=True)
+session.run()
+```
+
+### 2. **AI-Native Game Development** 🤖
+
+Position McRogueFace as the first **AI-first roguelike engine**:
+
+#### Integrated AI Features
+- **GPT-Powered NPCs**: Dynamic dialogue and quest generation
+- **Procedural Content via LLMs**: Describe a dungeon, AI generates it
+- **AI Dungeon Master**: Adaptive difficulty and narrative
+- **Code Assistant Integration**: Built-in AI helps write game logic
+
+#### Revolutionary Possibilities
+```python
+# AI-Assisted Game Creation
+from mcrfpy import ai_tools
+
+# Natural language level design
+dungeon = ai_tools.generate_dungeon("""
+    Create a haunted library with 3 floors. 
+    First floor: Reading rooms with ghost librarians
+    Second floor: Restricted section with magical traps
+    Third floor: Ancient archive with boss encounter
+""")
+
+# AI-driven NPCs
+npc = ai_tools.create_npc(
+    personality="Grumpy dwarf merchant who secretly loves poetry",
+    knowledge=["local rumors", "item prices", "hidden treasures"],
+    dynamic_dialogue=True
+)
+```
+
+### 3. **Web-Native Multiplayer Platform** 🌐
+
+Make McRogueFace the **Discord of Roguelikes**:
+
+#### Multiplayer Revolution
+- **Seamless Co-op**: Drop-in/drop-out multiplayer
+- **Competitive Modes**: Racing, PvP arenas, daily challenges
+- **Spectator System**: Watch and learn from others
+- **Cloud Saves**: Play anywhere, sync everywhere
+- **Social Features**: Guilds, tournaments, leaderboards
+
+#### WebAssembly Future
+```python
+# Future Web API
+import mcrfpy.web as web
+
+# Host a game room
+room = web.create_room("Epic Dungeon Run", max_players=4)
+room.set_rules(friendly_fire=False, shared_loot=True)
+room.open_to_public()
+
+# Stream gameplay
+stream = web.GameStream(room)
+stream.to_twitch(channel="awesome_roguelike")
+```
+
+## 🏗️ Architecture Evolution Roadmap
+
+### Phase 1: Beta Foundation (3-4 months)
+**Focus**: Stability and Polish
+- Complete RenderTexture system (#6)
+- Implement save/load system
+- Add audio mixing and 3D sound
+- Create plugin architecture
+- **Deliverable**: Beta release with plugin support
+
+### Phase 2: Platform Infrastructure (6-8 months)
+**Focus**: Multi-game Support
+- Game package format specification
+- Resource sharing system
+- Inter-game communication API
+- Cloud save infrastructure
+- **Deliverable**: McRogueFace Platform 1.0
+
+### Phase 3: AI Integration (8-12 months)
+**Focus**: AI-Native Features
+- LLM integration framework
+- Procedural content pipelines
+- Natural language game scripting
+- AI behavior trees
+- **Deliverable**: McRogueFace AI Studio
+
+### Phase 4: Web Deployment (12-18 months)
+**Focus**: Browser-based Gaming
+- WebAssembly compilation
+- WebRTC multiplayer
+- Cloud computation for AI
+- Mobile touch controls
+- **Deliverable**: play.mcrogueface.com
+
+## 🎮 Killer App Ideas
+
+### 1. **Roguelike Maker** (Like Mario Maker)
+- Visual dungeon editor
+- Share levels online
+- Play-test with AI
+- Community ratings
+
+### 2. **The Infinite Dungeon**
+- Persistent world all players explore
+- Procedurally expands based on player actions
+- AI Dungeon Master creates personalized quests
+- Cross-platform play
+
+### 3. **Roguelike Battle Royale**
+- 100 players start in connected dungeons
+- Dungeons collapse, forcing encounters
+- Last adventurer standing wins
+- AI-generated commentary
+
+## 🛠️ Technical Innovations to Pursue
+
+### 1. **Temporal Debugging**
+- Rewind game state
+- Fork timelines for "what-if" scenarios
+- Visual debugging of entity histories
+
+### 2. **Neural Tileset Generation**
+- Train on existing tilesets
+- Generate infinite variations
+- Style transfer between games
+
+### 3. **Quantum Roguelike Mechanics**
+- Superposition states for entities
+- Probability-based combat
+- Observer-effect puzzles
+
+## 🌍 Community Building Strategy
+
+### 1. **Education First**
+- University partnerships
+- Free curriculum: "Learn Python with Roguelikes"
+- Summer of Code participation
+- Student game jams
+
+### 2. **Open Core Model**
+- Core engine: MIT licensed
+- Premium platforms: Cloud, AI, multiplayer
+- Revenue sharing for content creators
+- Sponsored tournaments
+
+### 3. **Developer Ecosystem**
+- Comprehensive API documentation
+- Example games and tutorials
+- Asset marketplace
+- GitHub integration for mods
+
+## 🎯 Success Metrics
+
+### Year 1 Goals
+- 1,000+ games created on platform
+- 10,000+ monthly active developers
+- 3 AAA-quality showcase games
+- University curriculum adoption
+
+### Year 2 Goals
+- 100,000+ monthly active players
+- $1M in platform transactions
+- Major game studio partnership
+- Native VR support
+
+### Year 3 Goals
+- #1 roguelike development platform
+- IPO or acquisition readiness
+- 1M+ monthly active players
+- Industry standard for roguelikes
+
+## 🚀 Next Immediate Actions
+
+1. **Finish Beta Polish**
+   - Merge alpha_streamline_2 → master
+   - Complete RenderTexture (#6)
+   - Implement basic save/load
+
+2. **Build Community**
+   - Launch Discord server
+   - Create YouTube tutorials
+   - Host first game jam
+
+3. **Prototype AI Features**
+   - Simple GPT integration
+   - Procedural room descriptions
+   - Dynamic NPC dialogue
+
+4. **Plan Platform Architecture**
+   - Design plugin system
+   - Spec game package format
+   - Cloud infrastructure research
+
+---
+
+*"McRogueFace: Not just an engine, but a universe of infinite dungeons."*
+
+Remember: The best platforms create possibilities their creators never imagined. Build for the community you want to see, and they will create wonders.