plugin-based effects architecture, daemon mode with command-and-control (C&C), and display abstraction #25

david · 2026-03-16T02:07:57Z

david commented

2026-03-16 02:07:57 +00:00

Changes

Effects Plugin System

Add engine/effects/types.py - EffectConfig, EffectContext dataclasses and EffectPlugin protocol
Add engine/effects/registry.py - Plugin discovery and management (EffectRegistry)
Add engine/effects/chain.py - Ordered pipeline execution (EffectChain)
Add engine/effects/performance.py - Performance monitoring (PerformanceMonitor)
Add engine/effects/controller.py - NTFY command handler
Add effects_plugins/ - Externalized effect plugins (noise, glitch, fade, firehose)
Refactor engine/effects.py → engine/effects/legacy.py for compatibility

Display Abstraction

Add engine/display.py - Swappable display backends
- TerminalDisplay - ANSI terminal output
- NullDisplay - Headless/discard output for testing

Daemon Mode & Command-and-Control

Separate C&C into RX/TX topics (serial-like communication):
- klubhaus_terminal_mainline_cc_cmd - commands TO mainline
- klubhaus_terminal_mainline_cc_resp - responses FROM mainline
Add StreamController with automatic ntfy topic warmup
Add performance monitoring for render + display stages
Add cmdline.py for interactive C&C

Documentation

Update AGENTS.md with new operating procedures
Update README.md with daemon/cmd documentation

Testing

28 files changed, +2350 lines
Added tests:
- test_display.py - TerminalDisplay, NullDisplay
- test_effects.py - Plugin system, chain, registry, performance
- test_effects_controller.py - C&C command handler
- test_ntfy_integration.py - Topic integration tests
All 225 tests pass

## Changes ### Effects Plugin System - Add `engine/effects/types.py` - EffectConfig, EffectContext dataclasses and EffectPlugin protocol - Add `engine/effects/registry.py` - Plugin discovery and management (EffectRegistry) - Add `engine/effects/chain.py` - Ordered pipeline execution (EffectChain) - Add `engine/effects/performance.py` - Performance monitoring (PerformanceMonitor) - Add `engine/effects/controller.py` - NTFY command handler - Add `effects_plugins/` - Externalized effect plugins (noise, glitch, fade, firehose) - Refactor `engine/effects.py` → `engine/effects/legacy.py` for compatibility ### Display Abstraction - Add `engine/display.py` - Swappable display backends - TerminalDisplay - ANSI terminal output - NullDisplay - Headless/discard output for testing ### Daemon Mode & Command-and-Control - Separate C&C into RX/TX topics (serial-like communication): - `klubhaus_terminal_mainline_cc_cmd` - commands TO mainline - `klubhaus_terminal_mainline_cc_resp` - responses FROM mainline - Add StreamController with automatic ntfy topic warmup - Add performance monitoring for render + display stages - Add cmdline.py for interactive C&C ### Documentation - Update AGENTS.md with new operating procedures - Update README.md with daemon/cmd documentation ## Testing - **28 files changed, +2350 lines** - Added tests: - `test_display.py` - TerminalDisplay, NullDisplay - `test_effects.py` - Plugin system, chain, registry, performance - `test_effects_controller.py` - C&C command handler - `test_ntfy_integration.py` - Topic integration tests - All 225 tests pass

david added 8 commits 2026-03-16 02:07:58 +00:00

refactor: phase 1 - testability improvements b5d6eeedc0

- Add Config dataclass with get_config()/set_config() for injection
- Add Config.from_args() for CLI argument parsing (testable)
- Add platform font path detection (Darwin/Linux)
- Bound translate cache with @lru_cache(maxsize=500)
- Add fixtures for external dependencies (network, feeds, config)
- Add 15 tests for Config class, from_args, and platform detection

This enables testability by:
- Allowing config injection instead of global mutable state
- Supporting custom argv in from_args() for testing
- Providing reusable fixtures for mocking network/filesystem
- Preventing unbounded memory growth in translation cache

Fixes: _arg_value/_arg_int not accepting custom argv

refactor: phase 2 - modularization of scroll engine 7193e7487b

Split monolithic scroll.py into focused modules:
- viewport.py: terminal size (tw/th), ANSI positioning helpers
- frame.py: FrameTimer class, scroll step calculation
- layers.py: message overlay, ticker zone, firehose rendering
- scroll.py: simplified orchestrator, imports from new modules

Add stream controller and event types for future event-driven architecture:
- controller.py: StreamController for source initialization and stream lifecycle
- events.py: EventType enum and event dataclasses (HeadlineEvent, FrameTickEvent, etc.)

Added tests for new modules:
- test_viewport.py: 8 tests for viewport utilities
- test_frame.py: 10 tests for frame timing
- test_layers.py: 13 tests for layer compositing
- test_events.py: 11 tests for event types
- test_controller.py: 6 tests for stream controller

This enables:
- Testable chunks with clear responsibilities
- Reusable viewport utilities across modules
- Better separation of concerns in render pipeline
- Foundation for future event-driven architecture

Also includes Phase 1 documentation updates in code comments.

refactor: phase 3 - API efficiency improvements fba183526a

Add typed dataclasses for tuple returns:
- types.py: HeadlineItem, FetchResult, Block dataclasses with legacy tuple converters
- fetch.py: Add type hints and HeadlineTuple type alias

Add pyright for static type checking:
- Add pyright to dependencies
- Verify type coverage with pyright (0 errors in core modules)

This enables:
- Named types instead of raw tuples (better IDE support, self-documenting)
- Type-safe APIs across modules
- Backward compatibility via to_tuple/from_tuple methods

Note: Lazy imports skipped for render.py - startup impact is minimal.

refactor: phase 4 - event-driven architecture foundation 3551cc249f

- Add EventBus class with pub/sub messaging (thread-safe)
- Add emitter Protocol classes (EventEmitter, Startable, Stoppable)
- Add event emission to NtfyPoller (NtfyMessageEvent)
- Add event emission to MicMonitor (MicLevelEvent)
- Update StreamController to publish stream start/end events
- Add comprehensive tests for eventbus and emitters modules

feat(effects): add plugin architecture with performance monitoring 35e5a71930

feat(cmdline): add command-line interface for mainline control dd282653b5

feat(cmdline): C&C with separate topics and rich output 020eb663ea

feat(daemon): add display abstraction and daemon mode with C&C 45fb06e0be

david added 7 commits 2026-03-16 02:18:02 +00:00

refactor: phase 1 - testability improvements f170143939

- Add Config dataclass with get_config()/set_config() for injection
- Add Config.from_args() for CLI argument parsing (testable)
- Add platform font path detection (Darwin/Linux)
- Bound translate cache with @lru_cache(maxsize=500)
- Add fixtures for external dependencies (network, feeds, config)
- Add 15 tests for Config class, from_args, and platform detection

This enables testability by:
- Allowing config injection instead of global mutable state
- Supporting custom argv in from_args() for testing
- Providing reusable fixtures for mocking network/filesystem
- Preventing unbounded memory growth in translation cache

Fixes: _arg_value/_arg_int not accepting custom argv

refactor: phase 2 - modularization of scroll engine cdc8094de2

Split monolithic scroll.py into focused modules:
- viewport.py: terminal size (tw/th), ANSI positioning helpers
- frame.py: FrameTimer class, scroll step calculation
- layers.py: message overlay, ticker zone, firehose rendering
- scroll.py: simplified orchestrator, imports from new modules

Add stream controller and event types for future event-driven architecture:
- controller.py: StreamController for source initialization and stream lifecycle
- events.py: EventType enum and event dataclasses (HeadlineEvent, FrameTickEvent, etc.)

Added tests for new modules:
- test_viewport.py: 8 tests for viewport utilities
- test_frame.py: 10 tests for frame timing
- test_layers.py: 13 tests for layer compositing
- test_events.py: 11 tests for event types
- test_controller.py: 6 tests for stream controller

This enables:
- Testable chunks with clear responsibilities
- Reusable viewport utilities across modules
- Better separation of concerns in render pipeline
- Foundation for future event-driven architecture

Also includes Phase 1 documentation updates in code comments.

refactor: phase 3 - API efficiency improvements 35e5c8d38b

Add typed dataclasses for tuple returns:
- types.py: HeadlineItem, FetchResult, Block dataclasses with legacy tuple converters
- fetch.py: Add type hints and HeadlineTuple type alias

Add pyright for static type checking:
- Add pyright to dependencies
- Verify type coverage with pyright (0 errors in core modules)

This enables:
- Named types instead of raw tuples (better IDE support, self-documenting)
- Type-safe APIs across modules
- Backward compatibility via to_tuple/from_tuple methods

Note: Lazy imports skipped for render.py - startup impact is minimal.

refactor: phase 4 - event-driven architecture foundation 15de46722a

- Add EventBus class with pub/sub messaging (thread-safe)
- Add emitter Protocol classes (EventEmitter, Startable, Stoppable)
- Add event emission to NtfyPoller (NtfyMessageEvent)
- Add event emission to MicMonitor (MicLevelEvent)
- Update StreamController to publish stream start/end events
- Add comprehensive tests for eventbus and emitters modules

feat(effects): add plugin architecture with performance monitoring cfd7e8931e

feat(cmdline): add command-line interface for mainline control 05cc475858

feat(daemon): add display abstraction and daemon mode with C&C 4228400c43

genewildish merged commit 58dbbbdba7 into main

2026-03-16 09:13:23 +00:00

genewildish referenced this issue from a commit

2026-03-16 09:13:23 +00:00

Merge pull request 'plugin-based effects architecture, daemon mode with command-and-control (C&C), and display abstraction' (#25) from david/Mainline:effects_plugins into main

Sign in to join this conversation.