292 lines
8.5 KiB
Markdown
292 lines
8.5 KiB
Markdown
# ImGui ID Management Analysis & Implementation Summary
|
|
|
|
**Date**: October 2, 2025
|
|
**Prepared for**: @scawful
|
|
**Topic**: GUI widget ID refactoring for z3ed test automation
|
|
|
|
## Executive Summary
|
|
|
|
I've completed a comprehensive analysis of YAZE's ImGui ID management and created a complete refactoring plan to enable better test automation and eliminate duplicate ID issues.
|
|
|
|
### Key Findings
|
|
|
|
1. **100+ uses of `##` prefix** - Creates unnamed widgets that are hard to reference from tests
|
|
2. **Potential ID conflicts** - Multiple widgets with same label (`##table`, `##canvas`) in different scopes
|
|
3. **No centralized registry** - Test automation has no way to discover available widgets
|
|
4. **Inconsistent naming** - No convention across editors
|
|
|
|
### Proposed Solution
|
|
|
|
**Hierarchical Widget ID System** with:
|
|
- Automatic ID scoping via RAII helpers
|
|
- Centralized widget registry for discovery
|
|
- Stable, predictable widget paths
|
|
- Machine-readable catalog for AI agents
|
|
|
|
**Example transformation**:
|
|
```cpp
|
|
// Before
|
|
if (ImGui::BeginChild("##Canvas", ...)) { }
|
|
|
|
// After
|
|
YAZE_WIDGET_SCOPE("Canvas");
|
|
if (ImGui::BeginChild("OverworldMap", ...)) {
|
|
YAZE_REGISTER_WIDGET(canvas, "OverworldMap");
|
|
// Widget path: Overworld/Main/Canvas/canvas:OverworldMap
|
|
}
|
|
```
|
|
|
|
## Deliverables Created
|
|
|
|
### 1. Comprehensive Design Document
|
|
**File**: `docs/z3ed/IMGUI_ID_MANAGEMENT_REFACTORING.md`
|
|
|
|
**Contents**:
|
|
- Current state analysis (100+ ##-prefixed widgets cataloged)
|
|
- Hierarchical ID scheme design
|
|
- 4-phase implementation plan (17-26 hours)
|
|
- Testing strategy
|
|
- Integration with z3ed agent workflow
|
|
- Backwards compatibility approach
|
|
|
|
**Key sections**:
|
|
- Pattern analysis of existing code
|
|
- Proposed naming convention: `<Editor>/<Tab>/<Section>/<WidgetType>:<Name>`
|
|
- Benefits for AI-driven automation
|
|
- Migration timeline and priorities
|
|
|
|
### 2. Core Infrastructure Implementation
|
|
**Files**:
|
|
- `src/app/gui/widget_id_registry.h` (177 lines)
|
|
- `src/app/gui/widget_id_registry.cc` (193 lines)
|
|
|
|
**Features**:
|
|
- `WidgetIdScope` - RAII helper for automatic ID push/pop
|
|
- `WidgetIdRegistry` - Singleton registry with discovery methods
|
|
- Thread-safe ID stack management
|
|
- Pattern matching for widget lookup
|
|
- YAML/JSON export for z3ed agent
|
|
|
|
**API Highlights**:
|
|
```cpp
|
|
// RAII scoping
|
|
YAZE_WIDGET_SCOPE("Overworld");
|
|
YAZE_WIDGET_SCOPE("Canvas");
|
|
|
|
// Widget registration
|
|
YAZE_REGISTER_WIDGET(button, "DrawTile");
|
|
|
|
// Discovery
|
|
auto matches = registry.FindWidgets("*/button:*");
|
|
std::string catalog = registry.ExportCatalog("yaml");
|
|
```
|
|
|
|
### 3. Documentation Updates
|
|
**Updated**: `docs/z3ed/README.md`
|
|
- Added new "Implementation Guides" section
|
|
- Updated documentation structure
|
|
- Cross-references to refactoring guide
|
|
|
|
## Implementation Plan Summary
|
|
|
|
### Phase 1: Core Infrastructure (2-3 hours) ⚡
|
|
**Priority**: P0 - Immediate
|
|
**Status**: Code complete, needs build integration
|
|
|
|
**Tasks**:
|
|
- ✅ Created WidgetIdScope RAII helper
|
|
- ✅ Created WidgetIdRegistry with discovery
|
|
- 📋 Add to CMake build system
|
|
- 📋 Write unit tests
|
|
|
|
### Phase 2: Overworld Editor Refactoring (3-4 hours)
|
|
**Priority**: P0 - This week
|
|
**Rationale**: Most complex, most tested, immediate value for E2E validation
|
|
|
|
**Tasks**:
|
|
- Add `YAZE_WIDGET_SCOPE` at function boundaries
|
|
- Replace `##name` with meaningful names
|
|
- Register all interactive widgets
|
|
- Test with z3ed agent test
|
|
|
|
### Phase 3: Test Harness Integration (1-2 hours)
|
|
**Priority**: P0 - This week
|
|
|
|
**Tasks**:
|
|
- Add `DiscoverWidgets` RPC to proto
|
|
- Update Click/Type/Assert handlers to use registry
|
|
- Add widget suggestions on lookup failures
|
|
- Test with grpcurl
|
|
|
|
### Phase 4: Gradual Migration (4-6 hours per editor)
|
|
**Priority**: P1-P2 - Next 2-3 weeks
|
|
|
|
**Order**:
|
|
1. Overworld Editor (P0)
|
|
2. Dungeon Editor (P1)
|
|
3. Palette Editor (P1)
|
|
4. Graphics Editor (P1)
|
|
5. Remaining editors (P2)
|
|
|
|
## Benefits for z3ed Agent Workflow
|
|
|
|
### 1. Stable Widget References
|
|
```bash
|
|
# Before: brittle string matching
|
|
z3ed agent test --prompt "Click button:Overworld"
|
|
|
|
# After: hierarchical path resolution
|
|
z3ed agent test --prompt "Click the DrawTile tool"
|
|
# Resolves to: Overworld/Main/Toolset/button:DrawTile
|
|
```
|
|
|
|
### 2. Widget Discovery for AI
|
|
```bash
|
|
z3ed agent describe --widgets --format yaml > docs/api/yaze-widgets.yaml
|
|
```
|
|
|
|
**Output includes**:
|
|
- Full widget paths
|
|
- Widget types (button, input, canvas, etc.)
|
|
- Hierarchical context (editor, tab, section)
|
|
- Available actions (click, type, drag, etc.)
|
|
|
|
### 3. Automated Test Generation
|
|
AI agents can:
|
|
- Query widget catalog to understand UI structure
|
|
- Generate commands with stable widget references
|
|
- Use partial matching for fuzzy lookups
|
|
- Get helpful suggestions when widgets not found
|
|
|
|
## Integration with Existing Work
|
|
|
|
### Complements IT-01 (ImGuiTestHarness)
|
|
- Test harness can now discover widgets dynamically
|
|
- Widget registry provides stable IDs for Click/Type/Assert RPCs
|
|
- Better error messages with suggested alternatives
|
|
|
|
### Enables IT-02 (CLI Agent Test)
|
|
- Natural language prompts can resolve to exact widget paths
|
|
- TestWorkflowGenerator can query available widgets
|
|
- LLM can read widget catalog to understand UI
|
|
|
|
### Supports E2E Validation
|
|
- Fixes window detection issues with proper ID scoping
|
|
- Eliminates duplicate ID warnings
|
|
- Provides foundation for comprehensive GUI testing
|
|
|
|
## Next Steps
|
|
|
|
### Immediate (Tonight/Tomorrow) - 3 hours
|
|
1. Add widget_id_registry to CMakeLists.txt
|
|
2. Write unit tests for WidgetIdScope and WidgetIdRegistry
|
|
3. Build and verify no compilation errors
|
|
|
|
### This Week - 6 hours
|
|
4. Refactor Overworld Editor (Phase 2)
|
|
- Start with DrawToolset() and DrawOverworldCanvas()
|
|
- Add scoping and registration
|
|
- Test with existing E2E tests
|
|
|
|
5. Integrate with test harness (Phase 3)
|
|
- Add DiscoverWidgets RPC
|
|
- Update Click handler to use registry
|
|
- Test widget discovery via grpcurl
|
|
|
|
### Next Week - 8 hours
|
|
6. Continue editor migration (Dungeon, Palette, Graphics)
|
|
7. Write comprehensive documentation
|
|
8. Update z3ed guides with widget path examples
|
|
|
|
## Success Metrics
|
|
|
|
**Technical**:
|
|
- ✅ Zero duplicate ImGui ID warnings
|
|
- ✅ All interactive widgets registered and discoverable
|
|
- ✅ Test automation can reference any widget
|
|
- ✅ No performance regression
|
|
|
|
**UX**:
|
|
- ✅ Natural language prompts work reliably
|
|
- ✅ Error messages suggest correct widget paths
|
|
- ✅ AI agents can understand UI structure
|
|
- ✅ Tests are maintainable across refactors
|
|
|
|
## Risk Mitigation
|
|
|
|
### Backwards Compatibility
|
|
- Fallback mechanism for legacy string lookups
|
|
- Gradual migration, no breaking changes
|
|
- Both systems work during transition
|
|
|
|
### Performance
|
|
- Registry overhead minimal (hash map lookup)
|
|
- Thread-local storage for ID stack
|
|
- Lazy registration (only interactive widgets)
|
|
|
|
### Maintenance
|
|
- RAII helpers prevent scope leaks
|
|
- Macros hide complexity from editor code
|
|
- Centralized registry simplifies updates
|
|
|
|
## Code Review Notes
|
|
|
|
### Design Decisions
|
|
|
|
**Why RAII for scoping?**
|
|
- Automatic push/pop prevents mistakes
|
|
- Matches ImGui's own ID scoping semantics
|
|
- Clean, exception-safe
|
|
|
|
**Why thread_local for ID stack?**
|
|
- ImGui contexts are per-thread
|
|
- Avoids race conditions
|
|
- Allows multiple test instances
|
|
|
|
**Why singleton for registry?**
|
|
- Single source of truth
|
|
- Easy access from any editor
|
|
- Matches ImGui's singleton pattern
|
|
|
|
**Why hierarchical paths?**
|
|
- Natural organization (editor/tab/section/widget)
|
|
- Easy to understand and remember
|
|
- Supports partial matching
|
|
- Mirrors filesystem conventions
|
|
|
|
### Future Enhancements
|
|
|
|
1. **Widget State Tracking**
|
|
- Track enabled/disabled state
|
|
- Track visibility
|
|
- Track value changes
|
|
|
|
2. **Action Recording**
|
|
- Record user interactions
|
|
- Generate tests from recordings
|
|
- Replay for regression testing
|
|
|
|
3. **Visual Tree Inspector**
|
|
- ImGui debug window showing widget hierarchy
|
|
- Click to highlight in UI
|
|
- Real-time registration updates
|
|
|
|
## References
|
|
|
|
**Related z3ed Documents**:
|
|
- [E6-z3ed-cli-design.md](E6-z3ed-cli-design.md) - Agent architecture
|
|
- [IT-01-QUICKSTART.md](IT-01-QUICKSTART.md) - Test harness usage
|
|
- [NEXT_PRIORITIES_OCT2.md](NEXT_PRIORITIES_OCT2.md) - Current priorities
|
|
- [PROJECT_STATUS_OCT2.md](PROJECT_STATUS_OCT2.md) - Project status
|
|
|
|
**ImGui Documentation**:
|
|
- [ImGui FAQ - Widget IDs](https://github.com/ocornut/imgui/blob/master/docs/FAQ.md#q-how-can-i-have-multiple-widgets-with-the-same-label)
|
|
- [ImGui Test Engine](https://github.com/ocornut/imgui_test_engine) - Reference implementation
|
|
|
|
---
|
|
|
|
**Prepared by**: GitHub Copilot
|
|
**Review Status**: Ready for implementation
|
|
**Estimated Total Effort**: 17-26 hours over 2-3 weeks
|
|
**Immediate Priority**: Phase 1 build integration (3 hours)
|