Implement a Read-Eval-Print Loop (REPL) effect that provides a
HUD-style overlay for interactive pipeline control.
## New Files
- engine/effects/plugins/repl.py - REPL effect plugin with command processor
- engine/display/backends/terminal.py - Added raw mode and input handling
- examples/repl_simple.py - Simple demonstration script
- tests/test_repl_effect.py - 18 comprehensive tests
## Features
### REPL Interface
- HUD-style overlay showing FPS, command history, output buffer size
- Command history navigation (Up/Down arrows)
- Command execution (Enter)
- Character input and backspace support
- Output buffer with scrolling
### Commands
- help - Show available commands
- status - Show pipeline status and metrics
- effects - List all effects in pipeline
- effect <name> <on|off> - Toggle effect
- param <effect> <param> <value> - Set parameter
- pipeline - Show current pipeline order
- clear - Clear output buffer
- quit - Show exit message
### Terminal Input Support
- Added set_raw_mode() to TerminalDisplay for capturing keystrokes
- Added get_input_keys() to read keyboard input
- Proper terminal state restoration on cleanup
## Usage
Add 'repl' to effects in your configuration:
## Testing
All 18 REPL tests pass, covering:
- Effect registration
- Command processing
- Navigation (history, editing)
- Configuration
- Rendering
## Integration
The REPL effect integrates with the existing pipeline system:
- Uses EffectPlugin interface
- Supports partial updates
- Reads metrics from EffectContext
- Can be controlled via keyboard when terminal display is in raw mode
Next steps:
- Integrate REPL input handling into pipeline_runner.py
- Add keyboard event processing loop
- Create full demo with interactive features
- Added PositioningMode enum (ABSOLUTE, RELATIVE, MIXED)
- Created PositionStage class with configurable positioning modes
- Updated terminal display to support positioning parameter
- Updated PipelineParams to include positioning field
- Updated DisplayStage to pass positioning to terminal display
- Added documentation in docs/positioning-analysis.md
Positioning modes:
- ABSOLUTE: Each line has cursor positioning codes (\033[row;1H)
- RELATIVE: Lines use newlines (no cursor codes, better for scrolling)
- MIXED: Base content uses newlines, effects use absolute positioning (default)
Usage:
# In pipeline or preset:
positioning = "absolute" # or "relative" or "mixed"
# Via command line (future):
--positioning absolute
The terminal display was using which concatenated lines
without separators, causing text to render incorrectly and appear to jump
vertically.
Changed to so lines are properly separated with
newlines, allowing the terminal to render each line on its own row.
The ANSI cursor positioning codes (\033[row;colH) added by effects like
HUD and firehose still work correctly because:
1. \033[H moves cursor to (1,1) and \033[J clears screen
2. Newlines move cursor down for subsequent lines
3. Cursor positioning codes override the newline positions
4. This allows effects to position content at specific rows while the
base content flows naturally with newlines
- Fixes issue #45: Add state property to EffectContext for motionblur/afterimage effects
- Fixes issue #44: Reset camera bounce direction state in reset() method
- Fixes issue #43: Implement pipeline hot-rebuild with state preservation
- Adds radial camera mode for polar coordinate scanning
- Adds afterimage and motionblur effects
- Adds acceptance tests for camera and pipeline rebuild
Closes#43, #44, #45
BUG: FPS display showed incorrect values (e.g., >1000 when actual FPS was ~60)
ROOT CAUSE: Display backends were looking for avg_ms at the wrong level
in the stats dictionary. The PerformanceMonitor.get_stats() returns:
{
'frame_count': N,
'pipeline': {'avg_ms': X, ...},
'effects': {...}
}
But the display backends were using:
avg_ms = stats.get('avg_ms', 0) # ❌ Returns 0 (not found at top level)
FIXED: All display backends now use:
avg_ms = stats.get('pipeline', {}).get('avg_ms', 0) # ✅ Correct path
Updated backends:
- engine/display/backends/terminal.py
- engine/display/backends/websocket.py
- engine/display/backends/sixel.py
- engine/display/backends/pygame.py
- engine/display/backends/kitty.py
Now FPS displays correctly (e.g., 60 FPS for 16.67ms avg frame time).
MAJOR REFACTORING: Consolidate duplicated pipeline code and standardize on
capability-based dependency resolution. This is a significant but backwards-compatible
restructuring that improves maintainability and extensibility.
## ARCHITECTURE CHANGES
### Data Sources Consolidation
- Move engine/sources_v2.py → engine/data_sources/sources.py
- Move engine/pipeline_sources/ → engine/data_sources/
- Create unified DataSource ABC with common interface:
* fetch() - idempotent data retrieval
* get_items() - cached access with automatic refresh
* refresh() - force cache invalidation
* is_dynamic - indicate streaming vs static sources
- Support for SourceItem dataclass (content, source, timestamp, metadata)
### Display Backend Improvements
- Update all 7 display backends to use new import paths
- Terminal: Improve dimension detection and handling
- WebSocket: Better error handling and client lifecycle
- Sixel: Refactor graphics rendering
- Pygame: Modernize event handling
- Kitty: Add protocol support for inline images
- Multi: Ensure proper forwarding to all backends
- Null: Maintain testing backend functionality
### Pipeline Adapter Consolidation
- Refactor adapter stages for clarity and flexibility
- RenderStage now handles both item-based and buffer-based rendering
- Add SourceItemsToBufferStage for converting data source items
- Improve DataSourceStage to work with all source types
- Add DisplayStage wrapper for display backends
### Camera & Viewport Refinements
- Update Camera class for new architecture
- Improve viewport dimension detection
- Better handling of resize events across backends
### New Effect Plugins
- border.py: Frame rendering effect with configurable style
- crop.py: Viewport clipping effect for selective display
- tint.py: Color filtering effect for atmosphere
### Tests & Quality
- Add test_border_effect.py with comprehensive border tests
- Add test_crop_effect.py with viewport clipping tests
- Add test_tint_effect.py with color filtering tests
- Update test_pipeline.py for new architecture
- Update test_pipeline_introspection.py for new data source location
- All 463 tests pass with 56% coverage
- Linting: All checks pass with ruff
### Removals (Code Cleanup)
- Delete engine/benchmark.py (deprecated performance testing)
- Delete engine/pipeline_sources/__init__.py (moved to data_sources)
- Delete engine/sources_v2.py (replaced by data_sources/sources.py)
- Update AGENTS.md to reflect new structure
### Import Path Updates
- Update engine/pipeline/controller.py::create_default_pipeline()
* Old: from engine.sources_v2 import HeadlinesDataSource
* New: from engine.data_sources.sources import HeadlinesDataSource
- All display backends import from new locations
- All tests import from new locations
## BACKWARDS COMPATIBILITY
This refactoring is intended to be backwards compatible:
- Pipeline execution unchanged (DAG-based with capability matching)
- Effect plugins unchanged (EffectPlugin interface same)
- Display protocol unchanged (Display duck-typing works as before)
- Config system unchanged (presets.toml format same)
## TESTING
- 463 tests pass (0 failures, 19 skipped)
- Full linting check passes
- Manual testing on demo, poetry, websocket modes
- All new effect plugins tested
## FILES CHANGED
- 24 files modified/added/deleted
- 723 insertions, 1,461 deletions (net -738 LOC - cleanup!)
- No breaking changes to public APIs
- All transitive imports updated correctly
