diff --git a/docs/ISSUE_TRIAGE_2026-04.md b/docs/ISSUE_TRIAGE_2026-04.md new file mode 100644 index 0000000..228d43f --- /dev/null +++ b/docs/ISSUE_TRIAGE_2026-04.md @@ -0,0 +1,238 @@ +# McRogueFace Issue Triage — April 2026 + +**46 open issues** across #53–#304. Grouped by system, ordered by impact. + +--- + +## Group 1: Render Cache Dirty Flags (Bugfix Cluster) + +**4 issues — all quick-to-moderate fixes, high user-visible impact** + +These are systemic bugs where Python property setters bypass the render cache invalidation system (#144). They cause stale frames when using `clip_children` or `cache_subtree`. Issue #291 is the umbrella audit; the other three are specific bugs it identified. + +| Issue | Title | Difficulty | +|-------|-------|------------| +| #291 | Audit all Python property setters for missing markDirty() calls | Medium — systematic sweep of all tp_getset setters | +| #290 | UIDrawable base x/y/pos setters don't propagate dirty flags to parent | Quick — add markCompositeDirty() call in set_float_member() | +| #289 | Caption Python property setters don't call markDirty() | Quick — add markDirty() to text/font_size/fill_color setters | +| #288 | UICollection mutations don't invalidate parent Frame's render cache | Quick — add markCompositeDirty() in append/remove/etc | + +**Dependencies:** None external. #291 depends on #288–#290 being fixed first (or done together). + +**Recommendation: Tackle first.** These are correctness bugs affecting every user of the caching system. The fixes are mechanical (add missing dirty-flag calls), low risk, and testable. One focused session can close all four. + +--- + +## Group 2: Grid Dangling Pointer Bugs + +**3 issues — moderate fixes, memory safety impact** + +All three are the same class of bug: raw `UIGrid*` pointers in child objects that dangle when the parent grid is destroyed. Part of the broader memory safety audit (#279). + +| Issue | Title | Difficulty | +|-------|-------|------------| +| #270 | GridLayer::parent_grid dangling raw pointer | Moderate — convert to weak_ptr or add invalidation | +| #271 | UIGridPoint::parent_grid dangling raw pointer | Moderate — same pattern as #270 | +| #277 | GridChunk::parent_grid dangling raw pointer | Moderate — same pattern as #270 | + +**Dependencies:** These are the last 3 unfixed bugs from the memory safety audit (#279). Fixing all three would effectively close #279. + +**Recommendation: Tackle second.** Same fix pattern applied three times. Closes the memory safety audit chapter. + +--- + +## Group 3: Animation System Fixes + +**2 issues — one bugfix, one feature** + +| Issue | Title | Difficulty | +|-------|-------|------------| +| #256 | Animation system bypasses spatial hash updates for entity position | Moderate — hook animation property changes into spatial hash | +| #218 | Color and Vector animation targets | Minor feature — compound property animation support | + +**Dependencies:** #256 is independent. #218 is a nice-to-have that improves DX. + +--- + +## Group 4: Grid Layer & Rendering Fixes + +**2 issues — quick fixes** + +| Issue | Title | Difficulty | +|-------|-------|------------| +| #257 | Grid layers with z_index of zero are on top of entities | Quick — change `>=0` to `>0` or similar in draw order | +| #152 | Sparse Grid Layers | Major feature — default values + sub-grid chunk optimization | + +**Dependencies:** #257 is standalone. #152 builds on the existing layer system. + +--- + +## Group 5: API Cleanup & Consistency + +**1 issue — quick, blocks v1.0** + +| Issue | Title | Difficulty | +|-------|-------|------------| +| #304 | Remove camelCase module functions before 1.0 | Quick — delete 4 method entries from mcrfpyMethods[], update tests | + +**Dependencies:** Snake_case aliases already added. This is a breaking change gated on the 1.0 release. + +--- + +## Group 6: Multi-Tile Entity Rendering + +**5 issues — parent + 4 children, all tier3-future** + +Umbrella issue #233 with four sub-issues for different approaches to entities larger than one grid cell. + +| Issue | Title | Difficulty | +|-------|-------|------------| +| #233 | Enhance Entity rendering and positioning capabilities (parent) | Meta/tracking | +| #234 | Entity origin offset for oversized sprites | Minor — add pixel offset to entity draw position | +| #235 | Texture display bounds for non-uniform sprite content | Minor — support non-cell-aligned sprite regions | +| #236 | Multi-tile entities using oversized sprites | Minor — render single large sprite across cells | +| #237 | Multi-tile entities using composite sprites | Major — multiple sprite indices per entity | + +**Dependencies:** #234 is the simplest starting point. #236 and #237 build on #234/#235. + +--- + +## Group 7: Memory Safety Audit Tail + +**9 issues — testing/tooling infrastructure for the #279 audit** + +These are the remaining items from the 7DRL 2026 post-mortem. The actual bugs are mostly fixed; these are about preventing regressions and improving the safety toolchain. + +| Issue | Title | Difficulty | +|-------|-------|------------| +| #279 | Engine memory safety audit — meta/tracking | Meta — close when #270/#271/#277 done | +| #287 | Regression tests for each bug from #258–#278 | Medium — write targeted test scripts | +| #285 | CI pipeline for debug-test and asan-test | Medium — CI/CD configuration | +| #286 | Re-enable ASan leak detection | Tiny — remove detect_leaks=0 suppression | +| #284 | Valgrind Massif heap profiling target | Tiny — add Makefile target | +| #283 | Atheris fuzzing harness for Python API | Major — significant new infrastructure | +| #282 | Install modern Clang for TSan/fuzzing | Minor — toolchain upgrade | +| #281 | Free-threaded CPython + TSan Makefile targets | Minor — Makefile additions | +| #280 | Instrumented libtcod debug build | Minor — rebuild libtcod with sanitizers | + +**Dependencies:** #286 depends on #266/#275 (both closed). #287 depends on the actual bugs being fixed. #283 depends on #282. + +--- + +## Group 8: Grid Data Model Enhancements + +**3 issues — foundation work for game data** + +| Issue | Title | Difficulty | +|-------|-------|------------| +| #293 | DiscreteMap serialization via bytes | Minor — add bytes() and from_bytes() to DiscreteMap | +| #294 | Entity.gridstate as DiscreteMap reference | Minor — refactor internal representation | +| #149 | Reduce the size of UIGrid.cpp | Refactoring — break 1400+ line file into logical units | + +**Dependencies:** #294 depends on #293. #149 is independent refactoring. + +--- + +## Group 9: Performance Optimization + +**4 issues — significant effort, needs benchmarks first** + +| Issue | Title | Difficulty | +|-------|-------|------------| +| #255 | Tracking down performance improvement opportunities | Investigation — profiling session | +| #117 | Memory Pool for Entities | Major — custom allocator | +| #145 | TexturePool with power-of-2 RenderTexture reuse | Major — deferred from #144 | +| #124 | Grid Point Animation | Major — per-tile animation system, needs design | + +**Dependencies:** #255 should be done first to identify where optimization matters. #145 builds on the dirty-flag system (#144, closed). #124 is a large standalone feature. + +--- + +## Group 10: WASM / Playground Tooling + +**3 issues — all tier3-future** + +| Issue | Title | Difficulty | +|-------|-------|------------| +| #238 | Emscripten debugging infrastructure (DWARF, source maps) | Minor — build config additions | +| #239 | Automated WASM testing with headless browser | Major — new test infrastructure | +| #240 | Developer troubleshooting docs for WASM deployments | Documentation — write guide | + +**Dependencies:** #238 supports #239. #240 is standalone documentation. + +--- + +## Group 11: LLM Agent Testbed + +**3 issues — research/demo infrastructure** + +| Issue | Title | Difficulty | +|-------|-------|------------| +| #55 | McRogueFace as Agent Simulation Environment | Major — umbrella/vision issue | +| #154 | Grounded Multi-Agent Testbed | Major — research infrastructure | +| #156 | Turn-based LLM Agent Orchestration | Major — orchestration layer | + +**Dependencies:** #156 depends on #154. Both depend on #55 conceptually. These also depend on #53 (alternative input methods) and mature API stability. + +--- + +## Group 12: Demo Games & Tutorials + +**2 issues — showcase/marketing** + +| Issue | Title | Difficulty | +|-------|-------|------------| +| #248 | Crypt of Sokoban Remaster (7DRL prep) | Major — full game remaster | +| #167 | r/roguelikedev Tutorial Series Demo Game | Major — tutorial content + demo game | + +**Dependencies:** Both benefit from a stable, well-documented API. #167 specifically needs the API to be settled. + +--- + +## Group 13: Platform & Architecture (Far Future) + +**5 issues — large features, mostly deferred** + +| Issue | Title | Difficulty | +|-------|-------|------------| +| #70 | Package mcrfpy without embedded interpreter (wheels) | Major — significant build system rework | +| #62 | Multiple Windows | Major — architectural change | +| #67 | Grid Stitching / infinite world prototype | Major — new rendering/data infrastructure | +| #54 | Jupyter Notebook Interface | Major — alternative rendering target | +| #53 | Alternative Input Methods | Major — depends on #220 | + +--- + +## Group 14: Concurrency + +**1 issue — deferred** + +| Issue | Title | Difficulty | +|-------|-------|------------| +| #220 | Secondary Concurrency Model: Subinterpreter Support | Major — Python 3.12+ subinterpreters | + +**Dependencies:** Depends on free-threaded CPython work (#281). + +--- + +## Summary by Priority + +| Priority | Groups | Issue Count | Session Estimate | +|----------|--------|-------------|-----------------| +| **Do now** | G1 (dirty flags), G2 (dangling ptrs) | 7 | 1 session | +| **Do soon** | G3 (animation), G4 (grid fixes), G5 (API cleanup) | 5 | 1 session | +| **Foundation** | G7 (safety tests), G8 (grid data) | 12 | 2-3 sessions | +| **When ready** | G6 (multi-tile), G9 (perf), G10 (WASM) | 12 | 3-4 sessions | +| **Future** | G11 (LLM), G12 (demos), G13 (platform), G14 (concurrency) | 10 | unbounded | + +## Recommended First Session + +**Groups 1 + 2: Dirty flags + dangling pointers (7 issues)** + +Rationale: +- All are correctness/safety bugs, not features — fixes don't need design decisions +- Dirty flag fixes (#288-#291) share the same mechanical pattern: add missing `markDirty()` or `markCompositeDirty()` calls +- Dangling pointer fixes (#270, #271, #277) share the same pattern: convert `UIGrid*` to `weak_ptr` or add invalidation on grid destruction +- Closing these also effectively closes the meta issue #279 +- High confidence of completing all 7 in one session +- Clears the way for performance work (Group 9) which depends on correct caching