From e34d4f967e1d576d3b4eaa176ba726bc3a23aa87 Mon Sep 17 00:00:00 2001
From: John McCardle <mccardle.john@gmail.com>
Date: Tue, 8 Jul 2025 10:09:37 -0400
Subject: [PATCH] docs: cancel PyPI wheel task and add future vision for Python
 extension architecture
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python

Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)

Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility

This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 ROADMAP.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 82 insertions(+), 4 deletions(-)

diff --git a/ROADMAP.md b/ROADMAP.md
index 3b6b482..abb65d5 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -290,9 +290,9 @@ Rendering Layer:
 **Goal**: Ready for the world
 ```
 1. ✅ #85 - Replace all "docstring" placeholders [COMPLETED 2025-07-08]
-2. #86 - Add parameter documentation
-3. #108 - Generate .pyi type stubs for IDE support
-4. #70 - PyPI wheel preparation
+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
 ```
 
@@ -535,4 +535,82 @@ Rendering Layer:
 
 ---
 
-*Last Updated: 2025-07-05*  
+## 🔮 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.
+
+---
+
+*Last Updated: 2025-07-08*