WIP: Scope-Based Visual Feedback + Context Stack Registry

[trissim]

Overview

This PR implements a comprehensive scope-based visual feedback system with a centralized context resolution architecture. It reimplements the goals of the original PR #55 while building on the solid foundation established by PR #44.

Status: 🚧 Work In Progress - All components implemented, debugging in progress

What This PR Does

1. Scope-Based Visual Feedback System ✅ (Working)

Perceptually distinct visual identification for scope hierarchy:

• Scope Color Generation - MD5-based deterministic colors, WCAG AA compliant
• Flash Animations - 60fps smooth transitions when resolved values change
  • WidgetFlashAnimator - GroupBox backgrounds
  • TreeItemFlashAnimator - Tree widget items
  • ListItemFlashAnimator - List widget items
• Layered Borders - Scope-colored window borders
  • Simple solid borders for orchestrator scopes
  • Layered patterned borders for step scopes
• Integration Mixins
  • ScopedBorderMixin - Renders scope borders on dialogs
  • TreeFormFlashMixin - Coordinates tree+form flash animations

2. Context Stack Registry 🚧 (Implemented, Debugging)

Centralized resolution architecture replacing forms building their own context stacks:

class ContextStackRegistry(QObject):
    value_changed = pyqtSignal(str, str, object, object)  # scope_id, field_path, old, new
    
    def register_scope(scope_id, context_obj, dataclass_type) -> None
    def unregister_scope(scope_id) -> None
    def set(scope_id, field_name, value, dataclass_type) -> None  # Immutable
    def resolve(scope_id, dataclass_type, field_name) -> Any  # Cached
    def get_materialized_object(scope_id) -> Any  # For compilation
    def get_resolved_state(scope_id) -> Dict[str, Any]  # For dirty tracking

Key Design Decisions:

• Immutability: set() stores concrete values but does NOT mutate context_obj
• Materialization: get_materialized_object() creates new instances with resolved values
• Single Source of Truth: All resolution goes through registry, not forms

3. Reactive Flash/Dirty Tracking 🚧 (Implemented, Debugging)

ResolvedItemStateService listens to registry changes:

• Flash list items when visible scope values change
• Dirty tracking via baseline comparison

---

Architecture Comparison: Main vs This Branch

Aspect	Main Branch	This Branch
Context Resolution	Forms build own stacks via build_context_stack()	Centralized via ContextStackRegistry
Value Storage	Direct mutation via setattr()	Immutable via registry.set()
Flash Trigger	N/A	registry.value_changed signal
Dirty Tracking	N/A	Baseline comparison via get_resolved_state()
Preview Labels	LiveContextResolver	registry.resolve()
Scope Colors	N/A	MD5-based WCAG AA colors

---

Plan Files (Implementation Roadmap)

All plans implemented in WIP commit, need debugging:

plans/context-registry/plan_01_context_stack_registry.md

Create a ContextStackRegistry service that serves as the single source of truth for all resolved configuration values across the application. This eliminates the current architecture where:

• ParameterFormManager builds its own context stacks
• Preview labels resolve values through a separate path
• Flash/dirty tracking would need yet another resolution path

Key Findings from Plan:

There are exactly 2 ways configuration state changes:

1. ParameterFormManager edits (field-level changes) → registry.set()
2. Code mode edits (instance replacement) → registry.register_scope() (re-registration)

No other mutation paths exist.

plans/context-registry/plan_02_form_manager_integration.md

Migrate ParameterFormManager to use ContextStackRegistry as the single source of truth:

• Write to registry when user edits a field
• Read from registry for placeholder resolution
• No longer build their own context stacks

Key Change:

Remove setattr(self.step, field_name, value) from step_parameter_editor.py (no more in-place mutation)

plans/context-registry/plan_03_preview_label_integration.md

Preview labels will:

• Read from registry for resolved values
• React to registry.value_changed signal for updates
• No longer resolve through separate LiveContextResolver path

plans/context-registry/plan_04_flash_dirty_integration.md

Flash: Registry emits (scope_id, field_path, old_value, new_value) - flash if old != new
Dirty: Compare registry.get_resolved_state(scope_id) to saved baseline

User's Exact Specification:

1. Flash: "only flash if the resolved state changes from before the signal and after the signal"
2. Preview text: "just reads the current resolved state always, simple as"
3. Dirty: "checks if the current resolved state is different from the saved resolved state"

---

Known Issues (from WIP commit)

The end-to-end integration is not yet working. Known bugs:

• Flash animation timing and visibility filtering needs work
• Dirty tracking baseline comparison may have edge cases
• Scope visibility rules need validation across all scenarios
• Registry cache invalidation may be incomplete
• Nested manager scope handling needs testing
• Cross-window update propagation untested
• Performance impact of registry lookups unknown

---

Files Changed

New Files (34 total)

Config Framework:

• context_stack_registry.py - Central registry (406 lines)

Visual Feedback:

• scope_color_utils.py - Color generation utilities (258 lines)
• scope_color_strategy.py - Strategy pattern for colors (128 lines)
• scope_visual_config.py - Color scheme dataclass (148 lines)
• scope_color_service.py - Reactive color service (151 lines)

Flash Animations:

• smooth_flash_base.py - Base animator (128 lines)
• widget_flash_animation.py - Widget flash (121 lines)
• tree_item_flash_animation.py - Tree item flash (166 lines)
• list_item_flash_animation.py - List item flash (168 lines)

Mixins:

• scoped_border_mixin.py - Border rendering (134 lines)
• tree_form_flash_mixin.py - Flash coordination (165 lines)

Services:

• resolved_item_state_service.py - Reactive flash/dirty (165 lines)

Docs:

• scope_visual_feedback_system.rst - Architecture docs

Modified Files

• abstract_manager_widget.py - Registry connection, flash handlers
• parameter_form_manager.py - Registry registration
• parameter_ops_service.py - Use registry.resolve()
• field_change_dispatcher.py - Update registry on changes
• live_context_service.py - Track changed field
• pipeline_editor.py - Scope ID builder, baselines
• plate_manager.py - Baselines, abstract methods
• step_parameter_editor.py - Registry for immutable storage
• config_window.py, dual_editor_window.py - Mixins
• list_item_delegate.py - Scope border rendering

---

Commits

1. a4f8805 - feat(ui): Implement scope-based visual feedback system
2. 21da0eb - Add plans for context-registry refactor
3. 3109421 - WIP: Context Stack Registry integration - many bugs to fix
4. e8b4fbf - Add dependencies to pyproject.toml for color generation

---

For Reviewers

@smagruder - This PR serves as a starting point for understanding the visual feedback + registry architecture. The visual feedback system (commit 1) is working. The registry refactor (commit 3) implements all 4 plans but has bugs preventing end-to-end functionality.

Key questions for architectural review:

1. Is the immutability pattern (registry stores values, never mutates context_obj) the right approach?
2. Should materialization happen lazily or eagerly?
3. Is the scope visibility filtering logic correct for cross-window updates?
4. How should we handle nested manager registration (currently only root managers register)?

---

Dependencies Added

disinctipy = "^1.3.4"  # Perceptually distinct colors
wcag-contrast-ratio = "^0.9"  # WCAG AA compliance

---

Pull Request opened by Augment Code with guidance from the PR author