update hot reload track

2026-05-16 03:11:58 -04:00
parent 8065b14d90
commit 73402d05fa
4 changed files with 128 additions and 13 deletions
@@ -0,0 +1,60 @@
+# Track Specification: Hot Reload Python Codebase
+
+## Overview
+
+Implement selective, state-preserving hot-reload for the Manual Slop `./src` Python codebase. This follows the "data in stable memory, code in reloadable modules" pattern. The initial target is `src/gui_2.py`, with a delegation pattern that decouples render logic from the stable `App` class.
+
+## Current State Audit (as of 3414625)
+
+### Already Implemented (DO NOT re-implement)
+
+- **HotModule dataclass** (`src/hot_reloader.py:8-12`) — Fields: `name`, `file_path`, `state_keys`, `delegation_targets`
+- **HotReloader core** (`src/hot_reloader.py:14-67`) — Registry (`HOT_MODULES`), `register()`, `capture_state()`, `restore_state()`, `reload()`, `reload_all()`
+- **Delegation pattern design** (`docs/superpowers/specs/2026-05-14-hot-reloader-design.md`) — Full architecture documented
+
+### Gaps to Fill (This Track's Scope)
+
+1. **No GUI trigger** — No `Ctrl+Alt+R` keyboard handler in `App.run()` (gui_2.py:268-332) and no "Hot Reload" button in MMA dashboard (gui_2.py:4664-4695)
+2. **No src.gui_2 registration** — `HotReloader.HOT_MODULES` is empty; no module is registered
+3. **No delegation wrappers** — All `_render_xxx` methods are bound to `App` class; must be refactored to module-level functions with thin App wrappers
+4. **No visual error tint** — No overlay on `HotReloader.is_error_state == True`
+5. **No state_keys inventory** — The full list of App attrs to preserve hasn't been cataloged
+
+## Goals
+
+- Manual trigger via `Ctrl+Alt+R` keyboard shortcut and GUI "Hot Reload" button
+- State preservation across reloads using `copy.deepcopy` capture/restore
+- Silent fallback on failure with visual error tint overlay
+- Delegation pattern: module-level render functions, thin App delegation wrappers
+- Extensible registry for future hot modules (ai_client.py, etc.)
+
+## Functional Requirements
+
+1. `HotReloader.register()` registers modules with state_keys and delegation_targets
+2. `Ctrl+Alt+R` captured in main loop triggers `HotReloader.reload_all(app)`
+3. MMA dashboard contains a "Hot Reload" button calling same
+4. Failed reload renders red-tint overlay on viewport and restores pre-reload state
+5. `src.gui_2` registered as first hot module with complete state_keys and delegation_targets list
+6. All `App._render_xxx` methods refactored to module-level `render_xxx(app)` functions
+
+## Non-Functional Requirements
+
+- <1ms overhead per frame when not reloading
+- Error tint uses ImGui draw list (no GPU shaders)
+- State capture uses `copy.deepcopy` for isolation
+- All errors logged to `HotReloader.last_error` with full traceback
+
+## Architecture Reference
+
+- `docs/superpowers/specs/2026-05-14-hot-reloader-design.md` — Full architecture
+- `docs/guide_architecture.md` — Thread domains, event system
+- `src/hot_reloader.py` — Existing core implementation
+- `src/gui_2.py:App.run` (lines 268-332) — Main loop, keyboard capture target
+- `src/gui_2.py:_render_mma_dashboard` (lines 4664-4695) — Button placement
+
+## Out of Scope
+
+- Automatic file watching (manual trigger only)
+- Hot-reloading of C extensions or native code
+- Cross-platform reload support (Windows focus)
+- Adding ai_client.py as hot module (future extensibility)