Scope-Based Visual Feedback System & Reactive UI Performance Optimizations

[trissim]

Scope-Based Visual Feedback System & Reactive UI Performance Optimizations

Overview

This PR implements a comprehensive scope-based visual feedback system and refactors the configuration framework to support generic N-level scope hierarchies. The work addresses fundamental architectural limitations in how the GUI represents configuration inheritance and propagates changes across windows.

Key Achievements:

• ✅ Scope-based visual feedback with WCAG AA compliant color schemes
• ✅ Flash animations triggered by resolved value changes (not raw value changes)
• ✅ Generic N-level scope hierarchy replacing hardcoded GlobalPipelineConfig/PipelineConfig checks
• ✅ Framework-level cache control infrastructure for debugging
• ✅ Fixed 10 critical bugs in placeholder rendering, flash detection, and scope contamination
• ⚠️ Performance improvements implemented but not yet achieving 60 FPS target

---

New Features

1. Scope-Based Visual Feedback System

Motivation: The GUI had no visual indication of which plate a step belonged to or how configuration changes propagated through the inheritance hierarchy. Users couldn't tell if a flash was due to their direct edit or an inherited value change.

Solution: Implemented a complete visual feedback system using perceptually distinct colors, layered borders, and flash animations that trigger only when resolved values change.

Scope-Based Coloring

• Perceptually distinct colors for each plate using distinctipy library
• Deterministic assignment via MD5 hashing of scope_id ensures consistent colors across sessions
• WCAG AA compliance checking (4.5:1 contrast ratio) for accessibility
• Opacity-based hierarchy: Orchestrator items (15% tint), Step items (5% tint)

Layered Borders

Steps within each orchestrator get layered borders to visually differentiate them:

• Cycling tint factors: [0.7, 1.0, 1.4]
• Cycling patterns: [solid, dashed, dotted]
• 9 combinations before adding additional border layers
• Per-orchestrator indexing via scope_id format: "plate_path::step_token@position"

Flash Animations

Critical Design Decision: Flash on resolved value changes, not raw value changes.

Why this matters: A step with an override shouldn't flash if you edit the inherited value, because the step's resolved value didn't change. This prevents false positives and makes flashes semantically meaningful.

Implementation:

• Compare preview instances (with live edits) vs original instances (saved values)
• Build full context stacks for both states
• Resolve all attributes in batch (O(1) context setup)
• Flash only if resolved values differ
• 300ms duration, 50% opacity

Design Principle: Live Values, Not Saved Values

Critical concept: All flashes and labels are based on live values from open form editors, not saved values on disk.

When you open a config editor and make changes without saving:

1. Other widgets flash if their resolved values change based on the unsaved edits
2. Step labels show what the values WOULD BE if the current edits were saved
3. All previews use the live context with unsaved edits

When you close the editor without saving:

1. All affected widgets flash again (values revert to saved state)
2. Labels revert to show the saved values

This provides instant feedback and enables "what-if" exploration without committing changes.

2. Centralized Cache Settings Toggle

Motivation: During development, cache-related bugs were difficult to isolate because caches were scattered across multiple modules with no unified control.

Solution: openhcs/config_framework/cache_settings.py provides a single source of truth for cache toggles, controllable via environment variables. Useful for debugging correctness by forcing fresh resolution without modifying code.

---

Architecture & Framework Changes

1. Generic Scope Hierarchy System

Problem: The configuration framework had hardcoded assumptions about a 2-level hierarchy (global → plate). Adding step-level configs required 50+ isinstance checks scattered across the codebase. This violated the open/closed principle and made the system brittle.

Solution: Refactored to a generic N-level scope hierarchy using the ScopedObject ABC.

New Abstractions

ScopedObject ABC (openhcs/config_framework/config.py):

class ScopedObject(ABC):
    @abstractmethod
    def build_scope_id(self) -> Optional[str]:
        """Build scope identifier for this object."""
        pass

Implemented by:

• GlobalPipelineConfig → returns None (global scope)
• PipelineConfig → returns plate path
• FunctionStep → returns "plate_path::step_token"

GlobalConfigBase Virtual Base Class:

• Uses custom metaclass for isinstance() checks without inheritance
• Replaces hardcoded isinstance(config, GlobalPipelineConfig) checks
• Enables generic config type handling

ScopeProvider Helper:

• For UI code that needs scope context without full objects
• Usage: ScopeProvider(scope_id="...")

Scope Contamination Fix

Critical Bug: Parent scopes (GlobalPipelineConfig) were incorrectly inheriting values from child scopes (PipelineConfig/FunctionStep). This violated the semantic meaning of "global" configuration.

Root Cause: dual_axis_resolver.py had no concept of scope specificity - it would merge contexts from all scopes indiscriminately.

Solution: Added scope specificity filtering:

• Scope specificity: global=0, plate=1, step=2+
• Configs can only see values from EQUAL or LESS specific scopes
• Prevents GlobalPipelineConfig from seeing PipelineConfig values
• Implemented in context_manager.py via _calculate_scope_specificity() and scope filtering in context merging

2. Framework-Level Cache Control

Problem: Cache-related bugs were recurring throughout development. When a bug appeared, it was unclear which cache was responsible, and disabling caches required code changes.

Solution: FrameworkConfig class in openhcs/config_framework/config.py provides environment variable-based cache toggles:

@dataclass
class FrameworkConfig:
    disable_all_token_caches: bool = False  # Master switch
    disable_lazy_resolution_cache: bool = False
    disable_placeholder_text_cache: bool = False
    disable_live_context_resolver_cache: bool = False
    disable_unsaved_changes_cache: bool = False

Environment Variables:

• OPENHCS_DISABLE_TOKEN_CACHES=1 - Disable all caches
• OPENHCS_DISABLE_LAZY_RESOLUTION_CACHE=1 - Disable lazy resolution cache
• OPENHCS_DISABLE_PLACEHOLDER_CACHE=1 - Disable placeholder text cache
• OPENHCS_DISABLE_LIVE_CONTEXT_CACHE=1 - Disable live context resolver cache
• OPENHCS_DISABLE_UNSAVED_CHANGES_CACHE=1 - Disable unsaved changes cache

Integration: Caches check these flags before returning cached values, allowing runtime debugging without code modification.

3. Scope-Aware Configuration Priority

Problem: Unsaved changes cache was unscoped, causing cross-step contamination. Editing step 6 would incorrectly mark step 0 as having unsaved changes.

Root Cause: Cache used Dict[Type, Set[str]] - keyed only by config type, not by scope. All steps shared the same cache entry.

Solution:

1. Scoped cache structure: Dict[Tuple[Type, Optional[str]], Set[str]] - keyed by (config_type, scope_id)
2. Multi-level lookup: Check step-specific → plate-level → global scopes using MRO chain traversal
3. Scope specificity resolution: When multiple configs match, prioritize by scope (step > plate > global)
4. Token-based instance selection: Use context.token to choose between preview instances (live values) and original instances (saved values)

Files Changed:

• openhcs/config_framework/context_manager.py - Scope tracking context vars
• openhcs/config_framework/dual_axis_resolver.py - Scope specificity calculation
• openhcs/pyqt_gui/widgets/config_preview_formatters.py - Scoped cache structure
• openhcs/pyqt_gui/widgets/shared/parameter_form_manager.py - LiveContextSnapshot.scopes field

---

Performance Optimizations

⚠️ Note: Significant optimization work completed but 60 FPS target not yet achieved. Further profiling needed.

1. Type-Based Caching (O(n_managers) → O(1))

Problem: Unsaved changes detection iterated through all form managers on every keystroke.

Solution: Type-based cache Dict[Type, Set[str]] maps config type → changed field names. O(1) lookup to check if any manager has unsaved changes for a given config type.

2. Batch Cross-Window Updates (John Carmack-style)

Problem: Cross-window updates used Qt signals, causing O(N×M) signal emissions (N managers × M steps).

Solution: Universal reactive update coordinator with direct widget updates. Batch all cross-window updates into single operation, eliminating signal emission overhead.

Files: cross_window_preview_mixin.py, pipeline_editor.py, plate_manager.py

3. Placeholder Refresh Filtering (50-90% reduction)

Problem: Every keystroke refreshed placeholders for ALL fields, even unchanged ones.

Solution: Track which fields changed and only refresh placeholders for those fields. 50-90% reduction in placeholder resolution calls.

4. Class-Level Lazy Cache (70-90% speedup)

Problem: Each lazy dataclass instance had its own resolution cache, causing redundant resolution.

Solution: Class-level cache shared across all instances. 70-90% speedup for lazy field resolution.

File: openhcs/config_framework/lazy_factory.py

5. Logging Spam Reduction

Problem: 140+ log messages per keystroke from flash animations, flash restorations, and batch processing.

Solution: Reduced logging verbosity, batched flash restorations via coordinator.

6. Content-Based Caching & Batch Resolution

Problem: Flash detection was creating 29MB-31MB logs per keystroke, thousands of function calls per second. Root cause: extract_all_configs() was being called repeatedly for frozen dataclasses recreated with dataclasses.replace().

Solution:

1. Content-based caching in extract_all_configs() - cache by dataclass content, not identity
2. Batch resolution method resolve_all_config_attrs() - O(1) context setup when resolving multiple attributes
3. Merged context caching - avoid recreating dataclass instances
4. Lazy/non-lazy type matching in MRO inheritance (e.g., LazyStepWellFilterConfig matches StepWellFilterConfig)

Performance Impact:

• Typing in config fields: 29MB logs → minimal logging
• Flash detection: Always flash → only flash when resolved values change
• Context extraction: Thousands of calls/sec → once per context setup

Files: context_manager.py, dual_axis_resolver.py, lazy_factory.py, cross_window_preview_mixin.py

7. Batch Flash Detection (6.8x speedup)

Problem: Flash detection was sequential - check item 1, flash item 1, check item 2, flash item 2, etc.

Solution: Two-phase batch process:

1. Phase 1: Collect all items, build before/after object pairs, batch check which items should flash, update ALL labels and styling
2. Phase 2: Trigger ALL flashes simultaneously

Performance: 314ms → 46ms for 7 steps (6.8x speedup)

Files: pipeline_editor.py, plate_manager.py

---

Bug Fixes

1. Invisible Flash Animation

Problem: Flash animations were being called but not visible to users.

Root Cause: Scope-based styling methods were called AFTER flash, overwriting the flash background color with normal scope colors.

Solution: Reordered operations to apply styling BEFORE flash.

2. Flash Killed by Debounced Updates

Problem: Flash animations were invisible for isolated keystrokes. User types → flash starts (300ms duration) → 123ms later, debounce triggers preview update → styling overwrites flash color → flash becomes invisible.

Solution: Added reapply_flash_if_active() helper to check if item is currently flashing and restore flash color if it was overwritten.

3. Unsaved Changes Detection Asymmetry

Problem: Editing PipelineConfig.well_filter_config.well_filter showed unsaved changes for both plate AND steps, but editing PipelineConfig.step_well_filter_config.well_filter only showed unsaved changes for plate.

Root Cause: Cache was using inconsistent key formats - cache population used just type as key, but cache lookup used (type, scope) tuple as key.

Solution: Changed cache key from step_config_type to (step_config_type, cache_scope_id) tuple to match the lookup pattern.

4. Race Condition Requiring Typing Twice

Problem: First keystroke only showed unsaved changes for plate, second keystroke showed unsaved changes for both plate AND steps.

Root Cause: PipelineEditor processes BEFORE PlateManager, so when steps are checked on the first keystroke, the cache is empty (PlateManager hasn't populated it yet).

Solution: Changed active manager check to inspect field paths in _last_emitted_values instead of just checking if the dict is truthy.

5. Async Placeholder Rendering Bug

Problem: Placeholders not rendering correctly in nested configuration forms.

Dual Root Causes:

1. Race condition: Nested managers completed 43ms before registration in _pending_nested_managers
2. Cache pollution: Placeholder cache prevented re-application after async widget creation

Solution: Pre-register nested managers with placeholder (None) BEFORE creation to prevent race condition; invalidate placeholder refresh cache before final refresh.

6. Nested Form Placeholder Bug

Problem: Lazy class __init__ not inheriting custom __init__ from @global_pipeline_config decorated base classes, causing fields to initialize with concrete values instead of None.

Solution: Detect base class custom __init__ marker and apply same logic to lazy class; apply _fix_dataclass_field_defaults_post_processing to both base class (inherited fields only) and lazy class (ALL fields).

7. Placeholder Rendering on Initial Window Open

Problem: Placeholders not rendering on initial window open (sync mode).

Root Cause: Widgets were created but not visible when placeholders were applied. Qt's update() doesn't trigger repaint for invisible widgets. Sync widget creation path had only ONE event loop deferral, but widgets need TWO event loop ticks to become visible and paintable.

Solution: Added second QTimer.singleShot(0, ...) in sync path to match async behavior.

8. Streaming Configs Incorrectly Resolving to None

Problem: FijiStreamingConfig/NapariStreamingConfig were None instead of having enabled=False.

Root Cause: lazy_factory.py's _fix_dataclass_field_defaults_post_processing() was setting ALL fields to None default in the generated __init__, ignoring fields with default_factory.

Solution: Modified generated __init__ to use _MISSING sentinel for default_factory fields and call factory if value is _MISSING.

9. Nested Config Placeholders Not Inheriting from ui_hidden Fields

Problem: FijiStreamingConfig couldn't inherit from FijiDisplayConfig (ui_hidden).

Root Cause: collect_live_context() was filtering out scoped managers when scope_filter=None, preventing GlobalPipelineConfig from seeing nested config values from open windows.

Solution: Changed scope_filter=None to mean "no filtering" (include ALL scopes) instead of "only global scope".

10. Placeholder Live Context Scoping

Problem: Placeholders not updating correctly across different scopes.

Solution: Fixed scope filtering logic in live context collection and cache refresh mechanisms.

---

Documentation

New Architecture Documentation (6 files, ~3,800 lines):

1. docs/source/architecture/scope_visual_feedback_system.rst (1,531 lines) - Complete documentation of visual feedback system architecture
2. docs/source/architecture/reactive_ui_performance_optimizations.rst (569 lines) - Performance optimization patterns and rationale
3. docs/source/architecture/caching_architecture.rst (365 lines) - Maps all 5 caching systems and their token-based invalidation points
4. docs/source/development/scope_hierarchy_live_context.rst (860 lines) - Scope hierarchy system and live context resolution
5. docs/source/development/visual_feedback_integration.rst (343 lines) - Integration guide for adding visual feedback to new widgets
6. docs/source/user_guide/visual_feedback.rst (191 lines) - User-facing documentation

Updated Documentation:

• Configuration framework docs updated for ScopedObject and context_provider changes
• Context system docs updated for scope specificity filtering
• GUI performance patterns documented

---

Breaking Changes

1. config_context() Signature Change

Before:

config_context(scope_id="...")

After:

config_context(context_provider=orchestrator)

Migration: Replace all scope_id parameter calls with context_provider parameter. For objects implementing ScopedObject, pass the object directly. For UI code without full objects, use ScopeProvider(scope_id="...").

Rationale: The old API required manually building scope_id strings. The new API uses the ScopedObject interface, making it type-safe and eliminating string manipulation.

2. LiveContextSnapshot.scopes Field

Change: Added new scopes: Dict[str, str] field to LiveContextSnapshot.

Impact: Backward compatible - old code ignores the new field. New code uses it for scope-aware resolution.

3. Scope Contamination Fixes

Change: Scope specificity filtering prevents parent scopes from seeing child scope values.

Impact: May change resolved values in edge cases where GlobalPipelineConfig was incorrectly inheriting from PipelineConfig. This is a correctness fix, not a regression.

---

Dependencies

Added:

• wcag-contrast-ratio>=0.9 - WCAG color contrast compliance checking

Purpose: Ensures all generated scope colors meet WCAG AA accessibility standards (4.5:1 contrast ratio) for users with visual impairments.

---

Testing

Testing Approach: Primarily manual testing due to the GUI-heavy nature of this work.

Manual Test Coverage:

1. Scope-based coloring - Verified perceptually distinct colors for multiple plates, deterministic color assignment across sessions
2. Flash animations - Verified flash triggers only when resolved values change, not on raw value changes
3. Window close with unsaved changes - Verified flash triggers when closing editor without saving
4. Placeholder rendering - Verified placeholders render on initial window open and update on keystroke
5. Cross-window reactive updates - Verified changes in one window propagate to all open windows
6. Unsaved changes detection - Verified scope-aware detection (step 6 edits don't affect step 0)
7. Layered border rendering - Verified border cycling patterns and tint factors
8. Nested form placeholders - Verified inheritance from ui_hidden fields
9. Streaming config resolution - Verified configs resolve to enabled=False instead of None
10. Scope contamination - Verified GlobalPipelineConfig doesn't inherit from PipelineConfig

Integration Tests Updated:

• tests/integration/test_main.py - Updated streaming config creation pattern to always-create-with-enabled-flag pattern

---

Review Guidance

Focus Areas for Review

1. Performance Profiling

   • The 60 FPS target is not yet achieved despite significant optimization work
   • Recommend profiling with cProfile or py-spy to identify remaining bottlenecks
   • Key areas to investigate:
     • Placeholder resolution on every keystroke
     • Flash detection batch processing
     • Cross-window update coordination
     • Qt event loop blocking during batch operations

2. Future Refactoring Opportunities

   • Anti-duck-typing UI refactor (see antiducktype_ui_refactor branch):
     • Current implementation has widget type checks scattered throughout parameter_form_manager.py
     • The antiducktype_ui_refactor branch implements a polymorphic widget strategy pattern that eliminates duck typing
     • Recommend merging that work to clean up widget type handling in the visual feedback system
     • Specific integration points:
       • apply_scope_styling() methods currently check widget types with isinstance()
       • Flash animation system has separate code paths for QTreeWidgetItem vs QListWidgetItem
       • Placeholder rendering has widget-specific logic that could be polymorphic

3. Architecture Review

   • ScopedObject abstraction: Does this generalize well to future scope levels (e.g., well-level configs)?
   • Token-based cache invalidation: Is the global token counter approach sustainable as the codebase grows?
   • Content-based caching: Are there edge cases where frozen dataclass content hashing could fail?
   • Scope specificity calculation: Is the numeric specificity model (global=0, plate=1, step=2+) extensible?

4. Code Quality

   • Duplicate flash animation classes: widget_flash_animation.py, tree_item_flash_animation.py, list_item_flash_animation.py have similar logic - could be unified
   • Scope color utilities: scope_color_utils.py and scope_visual_config.py have overlapping responsibilities
   • Cache settings: Consider consolidating cache toggle logic into a single decorator pattern instead of manual checks in each cache

5. Documentation Completeness

   • Verify all new abstractions (ScopedObject, GlobalConfigBase, ScopeProvider) are documented
   • Verify performance optimization rationale is clear for future maintainers
   • Verify migration guide for breaking changes is sufficient

Known Limitations

1. Performance: 60 FPS target not achieved - further optimization needed
2. Flash animation classes: Code duplication across widget types
3. Widget type checks: Duck typing still present in some areas (addressed in antiducktype_ui_refactor branch)
4. Cache complexity: 5 different caching systems with token-based invalidation - high cognitive load for new contributors

Suggested Next Steps

1. Merge antiducktype_ui_refactor branch to eliminate widget duck typing
2. Profile GUI performance to identify remaining bottlenecks
3. Consider unifying flash animation classes into single polymorphic implementation
4. Add automated GUI tests using pytest-qt for critical paths
5. Document cache invalidation points in a centralized location (partially done in caching_architecture.rst)