feat(positioning): Add configurable PositionStage for positioning modes

- 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
This commit is contained in:
2026-03-21 17:38:20 -07:00
parent 5352054d09
commit 33df254409
7 changed files with 556 additions and 6 deletions

View File

@@ -8,7 +8,7 @@ from engine.pipeline.core import PipelineContext, Stage
class DisplayStage(Stage):
"""Adapter wrapping Display as a Stage."""
def __init__(self, display, name: str = "terminal"):
def __init__(self, display, name: str = "terminal", positioning: str = "mixed"):
self._display = display
self.name = name
self.category = "display"
@@ -16,6 +16,7 @@ class DisplayStage(Stage):
self._initialized = False
self._init_width = 80
self._init_height = 24
self._positioning = positioning
def save_state(self) -> dict[str, Any]:
"""Save display state for restoration after pipeline rebuild.
@@ -87,7 +88,20 @@ class DisplayStage(Stage):
def process(self, data: Any, ctx: PipelineContext) -> Any:
"""Output data to display."""
if data is not None:
self._display.show(data)
# Check if positioning mode is specified in context params
positioning = self._positioning
if ctx and ctx.params and hasattr(ctx.params, "positioning"):
positioning = ctx.params.positioning
# Pass positioning to display if supported
if (
hasattr(self._display, "show")
and "positioning" in self._display.show.__code__.co_varnames
):
self._display.show(data, positioning=positioning)
else:
# Fallback for displays that don't support positioning parameter
self._display.show(data)
return data
def cleanup(self) -> None: