GPU Layout Phase 0: Architecture Improvements

[Pluglug]

Overview

Before proceeding with UI Scaling (#106), improve the architectural foundation of the GPU Layout system based on professional feedback.

Problems Identified

1. Phase mixing: draw() calls layout() internally (layout.py:624)

   • Unpredictable behavior
   • Performance issues
   • Prevents Dirty Flag optimization

2. State scattering: hovered/pressed states exist in multiple places

   • ButtonItem._hovered, _pressed (items.py)
   • InteractionState.hovered, pressed (interactive.py)
   • GPULayout._close_button_hovered (layout.py)

3. Event propagation incomplete: Only bubble phase, no stopPropagation()

Sub-tasks

• Phase 0-A: Separate draw() and layout() phases ✅ d3feb58
• Phase 0-B: Centralize state management with UIState ✅ d3feb58
• Phase 0-C: Improve event propagation with UIEvent.consume() (deferred)

Design Document

See _docs/design/gpu_phase0_architecture.md

Success Criteria

• TEST_OT_gpu_layout works correctly
• TEST_OT_gpu_interactive works correctly (drag, close button, hover, press)
• Clean separation between layout and drawing phases
• Single source of truth for UI state

Implementation Notes

Phase 0-A: Layout/Draw Separation

• draw() no longer calls layout() internally
• Added update_and_draw() convenience method
• Introduced Dirty Flag pattern for optimization

Phase 0-B: Centralized State

• UIState class: ID-based state management
• ItemRenderState: passed to draw() methods
• Removed _hovered/_pressed from items
• State flows: HitTestManager → UIState → ItemRenderState → draw()

Related

• [Tracking] PME2: GPU Layout System - Interactive UI Framework #104 GPU Layout Tracking Issue
• GPU Layout: UI scaling with over_scale pattern #106 UI Scaling (can now proceed)

[Pluglug]

Observer Review: Phase 0-A/0-B Implementation

✅ Excellent Implementation

The Phase 0-A/0-B implementation successfully achieves:

• UIState centralization: ID-based state management creates Single Source of Truth
• ItemRenderState: Makes draw functions pure (no side effects)
• Dirty Flag pattern: Properly propagates to children via mark_dirty()
• Phase separation: Clear layout() / draw() / update_and_draw() API

⚠️ Minor Issues for Future Consideration

1. handle_event() still calls layout() internally

Location: layout.py:771

def handle_event(self, event: Event, region=None) -> bool:
    self.layout()  # ← Still present
    return self._handle_event(event, region)

Impact: Low (Dirty Flag mitigates performance issues)
Suggestion: Consider moving layout() to caller's responsibility for consistency with Phase 0-A goals.

2. _close_button_hovered not migrated to UIState

Location: layout.py:107, 529-531, 749

self._close_button_hovered: bool = False  # ← Still using instance variable

def on_close_hover_enter():
    self._close_button_hovered = True  # ← Not using UIState

Impact: Low (title bar is a special case)
Suggestion: Assign item_id="close_button" to _close_button_rect and use UIState.is_hovered("close_button") for consistency. Could be addressed in #107 (Panel drag & close button).

3. item_id generation uses id()

Location: layout.py:686

item_id = str(id(item))

Impact: Low (currently safe, but fragile for future)
Concern: id() returns memory address, which can be reused after GC. May cause unexpected collisions if items are frequently created/destroyed.
Suggestion (low priority): Consider explicit ID generation in future:

item_id = f"button_{uuid.uuid4().hex[:8]}"

4. Design note: InteractionState vs UIState

The coexistence of InteractionState (HitRect references) and UIState (string IDs) appears intentional:

• InteractionState: Internal state for hit testing logic
• UIState: Public state for rendering

Suggestion: Document this design decision explicitly in interactive.py docstring.

---

Verdict

Phase 0-A/0-B is successful. The architecture improvements provide a solid foundation for #106 (UI Scaling) and #109 (Text Rendering).

🤖 Review by Claude Opus 4.5