marathon/docs/bevy-rendering-vendoring-breakdown.md

# Bevy Rendering Vendoring - Task Breakdown

**Epic:** Vendor Bevy Renderer and Eliminate Window Component Duplication (#2)
**Overall Size:** XXL (32+ points across 5 phases)
**Priority:** P2 (Medium - architectural improvement)

This document breaks down the 5 phases into specific, sized tasks for prioritization and scheduling.

---

## Phase 1: Vendoring

**Phase Goal:** Bring Bevy's rendering stack into Marathon codebase
**Phase Size:** 20 points
**Dependencies:** None (can start immediately)
**Risk:** Medium (large code drop, potential API mismatches)

### Tasks

| # | Task | Size | Points | Rationale | Priority |
|---|------|------|--------|-----------|----------|
| 1.1 | Vendor `bevy_render` core into `crates/libmarathon/src/render/` | L | 8 | ~15K LOC, complex module structure, need to preserve API surface | P2 |
| 1.2 | Vendor `bevy_pbr` materials and lighting | M | 4 | Smaller than render core, well-isolated system | P2 |
| 1.3 | Vendor `bevy_core_pipeline` | S | 2 | Thin abstraction layer over render core | P2 |
| 1.4 | Vendor wgpu integration helpers | S | 2 | Limited surface area, mostly type wrappers | P2 |
| 1.5 | Update `Cargo.toml` and remove Bevy renderer dependencies | XS | 1 | Straightforward dependency changes | P2 |
| 1.6 | Verify existing rendering still works (smoke test) | M | 4 | Need to test all platforms, lighting, PBR materials | P1 |

**Phase 1 Total:** 21 points

### Lean Analysis
- **Eliminate Waste:** Is vendoring 15K+ LOC necessary? YES - window state duplication is causing bugs
- **Amplify Learning:** What will we learn? How deeply Bevy's renderer couples to Window components
- **Deliver Fast:** Can we vendor incrementally? YES - by module (render, then pbr, then pipeline)
- **Build Quality In:** Risk of introducing regressions? YES - comprehensive smoke testing critical

### Phase 1 Recommendations
1. **Do 1.1-1.5 as a batch** - vendoring is all-or-nothing, partial state is worse
2. **Do 1.6 immediately after** - verify nothing broke before proceeding
3. **Consider:** Create a feature flag `vendored-renderer` to toggle between vendored/upstream during transition

---

## Phase 2: Renderer Refactoring

**Phase Goal:** Make renderer work with winit handles directly
**Phase Size:** 18 points
**Dependencies:** Phase 1 complete
**Risk:** High (core renderer architecture changes)

### Tasks

| # | Task | Size | Points | Rationale | Priority |
|---|------|------|--------|-----------|----------|
| 2.1 | Design `WindowInfo` abstraction for render queries | S | 2 | Clear API, minimal state | P1 |
| 2.2 | Modify renderer initialization to accept winit handles | M | 4 | Need to trace through render graph setup | P1 |
| 2.3 | Update `RawHandleWrapper` to provide window info | S | 2 | Add methods for size, scale_factor queries | P2 |
| 2.4 | Refactor camera viewport calculations | M | 4 | Cameras need aspect ratio, DPI - multiple call sites | P1 |
| 2.5 | Audit and update all window queries in render systems | L | 8 | Many systems query window, need comprehensive search | P1 |
| 2.6 | Verify PBR materials work with new architecture | M | 4 | Test metallic/roughness, normal maps, AO | P1 |

**Phase 2 Total:** 24 points

### Lean Analysis
- **Eliminate Waste:** Can we avoid refactoring everything? NO - window queries are scattered
- **Amplify Learning:** Should we prototype WindowInfo first? YES - design task 2.1 is critical
- **Decide Late:** Can we defer PBR verification? NO - it's core to the aesthetic
- **Optimize Whole:** Does this improve both desktop and iOS? YES - fixes DPI bugs on both

### Critical Path
```
2.1 (WindowInfo design)
  ↓
2.2 (renderer init) → 2.3 (RawHandleWrapper)
  ↓
2.4 (cameras) + 2.5 (audit systems)
  ↓
2.6 (PBR verification)
```

### Phase 2 Recommendations
1. **Start with 2.1** - get design right before touching renderer
2. **Parallelize 2.4 and 2.5** - different areas of codebase
3. **Consider:** Keep old Window component code paths behind feature flag during transition

---

## Phase 3: Executor Cleanup

**Phase Goal:** Remove duplicate Bevy Window components
**Phase Size:** 8 points
**Dependencies:** Phase 2 complete (renderer no longer needs Window components)
**Risk:** Low (pure deletion once renderer is independent)

### Tasks

| # | Task | Size | Points | Rationale | Priority |
|---|------|------|--------|-----------|----------|
| 3.1 | Remove `bevy::window::Window` creation from iOS executor | S | 2 | Delete code, verify iOS still builds | P1 |
| 3.2 | Remove `bevy::window::Window` creation from desktop executor | S | 2 | Delete code, verify desktop still works | P1 |
| 3.3 | Migrate window config to winit `WindowAttributes` | M | 4 | Some logic may have lived in Bevy window creation | P2 |
| 3.4 | Remove `WindowMode` enum usage | XS | 1 | Straightforward deletion | P2 |
| 3.5 | Clean up unused imports and dead code | XS | 1 | Cargo clippy + manual review | P3 |

**Phase 3 Total:** 10 points

### Lean Analysis
- **Eliminate Waste:** This entire phase IS waste elimination - removing duplicate state
- **Deliver Fast:** Can we do this immediately after Phase 2? YES - it's pure cleanup
- **Build Quality In:** Risk of breaking something? LOW if Phase 2 is solid

### Phase 3 Recommendations
1. **Do 3.1 and 3.2 together** - both platforms should behave identically
2. **Do 3.5 last** - easy win after harder work
3. **Fast phase:** Mostly verification

---

## Phase 4: egui Integration

**Phase Goal:** Ensure debug UI works with winit-only window state
**Phase Size:** 6 points
**Dependencies:** Phase 3 complete
**Risk:** Low (egui is already vendored and working)

### Tasks

| # | Task | Size | Points | Rationale | Priority |
|---|------|------|--------|-----------|----------|
| 4.1 | Update debug UI to query scale factor from winit | S | 2 | Replace any Bevy window queries | P1 |
| 4.2 | Verify custom input system still works | S | 2 | Input already uses custom event buffer | P1 |
| 4.3 | Test DPI scaling on HiDPI displays | S | 2 | Manual testing on Retina macOS + iPad | P1 |
| 4.4 | Update debug UI documentation | XS | 1 | Reflect new architecture | P3 |

**Phase 4 Total:** 7 points

### Lean Analysis
- **Amplify Learning:** Will this reveal DPI bugs? YES - explicit test for it
- **Build Quality In:** Test HiDPI early? YES - that's what this phase is

### Phase 4 Recommendations
1. **Do 4.1-4.3 as quick verification** - egui should "just work" since we already vendored it
2. **This is a checkpoint** - if 4.3 reveals DPI issues, they're from Phase 2/3

---

## Phase 5: Testing & Documentation

**Phase Goal:** Comprehensive verification and knowledge capture
**Phase Size:** 12 points
**Dependencies:** Phases 1-4 complete
**Risk:** Low (pure verification)

### Tasks

| # | Task | Size | Points | Rationale | Priority |
|---|------|------|--------|-----------|----------|
| 5.1 | PBR materials test with low-poly assets | M | 4 | Create test scene, verify metallic/roughness | P1 |
| 5.2 | Lighting system verification | M | 4 | Point, directional, spot lights + shadows | P1 |
| 5.3 | Cross-platform testing battery | S | 2 | macOS desktop, macOS Retina, iOS device, iPad simulator | P1 |
| 5.4 | Update architecture docs (RFC or new doc) | S | 2 | Explain window ownership, renderer changes | P2 |
| 5.5 | Remove obsolete TODOs and comments | XS | 1 | Code archaeology, cleanup | P3 |
| 5.6 | Create before/after architecture diagrams | S | 2 | Visual explanation for future contributors | P3 |

**Phase 5 Total:** 15 points

### Lean Analysis
- **Amplify Learning:** Testing amplifies confidence, docs amplify knowledge transfer
- **Build Quality In:** When should we test? CONTINUOUSLY, but this is final verification
- **Eliminate Waste:** Are diagrams worth 2 points? YES if they prevent future confusion

### Phase 5 Recommendations
1. **Do 5.1-5.3 first** - verification before celebration
2. **Do 5.4 immediately** - knowledge is fresh
3. **Do 5.5-5.6 when inspired** - nice-to-haves, P3 priority

---

## Overall Scheduling Recommendations

### Critical Path (Sequential)
```
Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5
Total: ~77 points
```

### Parallel Opportunities
- **During Phase 1:** Write Phase 2 design docs (2.1)
- **During Phase 2:** Plan Phase 3 deletions
- **During Phase 5:** Parallelize testing (5.1, 5.2, 5.3) if multiple devices available

### Risk Mitigation Strategy
1. **Phase 1.6 is a GO/NO-GO gate** - if smoke tests fail, stop and debug
2. **Phase 2.1 design review** - get feedback on WindowInfo before implementing
3. **Feature flags** - keep ability to toggle between old/new during Phases 1-3
4. **Incremental commits** - don't batch entire phase into one PR

---

## WSJF Prioritization (Within P2 Tier)

Scoring against other P2 work (hypothetical):

| Item | Player Value | Time Criticality | Risk Reduction | CoD | Size | WSJF |
|------|--------------|------------------|----------------|-----|------|------|
| **Bevy Vendor Epic** | 4 | 2 | 8 | 14 | 32 | **0.44** |
| Phase 1 alone | 3 | 2 | 9 | 14 | 21 | **0.67** |
| Phase 2 alone | 6 | 3 | 9 | 18 | 24 | **0.75** |

**Interpretation:**
- **Low player value initially** - this is technical debt, not features
- **High risk reduction** - fixes DPI bugs, enables future renderer work
- **Do Phase 1 + 2 together** - they're meaningless separately
- **Compare to:** Agent simulation (epic #5) likely has WSJF > 1.0, do that first if capacity allows

---

## Sequencing with Other Work

### Good to do BEFORE this epic:
- ✅ iOS deployment scripts (done)
- ✅ Basic ECS setup (done)
- Any small P1 bugs or quick wins

### Good to do AFTER this epic:
- Advanced rendering features (bloom, post-processing)
- Agent simulation rendering (needs clean renderer)
- Spatial audio visualization (uses renderer)

### Can do IN PARALLEL:
- Networking improvements (different subsystem)
- Content creation (doesn't depend on window architecture)
- Game design prototyping

---

## Decision Points

### Before Starting Phase 1:
- [ ] Do we have bandwidth for ~2 months of rendering work?
- [ ] Are there higher-priority bugs blocking players/demos?
- [ ] Have we validated PBR aesthetic matches Aspen vision?

### Before Starting Phase 2:
- [ ] Did Phase 1.6 smoke tests pass?
- [ ] Do we understand all Window component usage?
- [ ] Is WindowInfo design reviewed and approved?

### Before Starting Phase 3:
- [ ] Does renderer work 100% without Window components?
- [ ] Have we tested on both iOS and desktop?

### Before Closing Epic:
- [ ] All platforms tested with HiDPI/Retina displays?
- [ ] PBR materials look correct with low-poly assets?
- [ ] Architecture docs updated?
- [ ] Can we confidently say "winit is single source of truth"?

---

## Summary

**Total Effort:** ~77 points (XXL epic)
**Confidence:** Medium (vendoring is well-understood, refactoring has unknowns)
**Recommendation:** Defer until higher-value work (agent simulation, core gameplay) is stable
**When to do it:** When DPI bugs become P1, or when we need renderer extensibility

This is important technical debt payoff but not immediately urgent. The current duplicate window state works, just inelegantly.