genewildish/Mainline
1
0
Fork 1
Code Issues Pull Requests 4 Packages Projects Releases Wiki Activity

feat(positioning): Add configurable PositionStage for positioning modes

Browse Source 
- 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:
David Gwilliam
2026-03-21 17:38:20 -07:00
parent 5352054d09
commit 33df254409
7 changed files with 556 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
engine/pipeline/adapters/__init__.py
View File

@@ -16,6 +16,11 @@ from .factory import (
create_stage_from_source,
)
from .message_overlay import MessageOverlayConfig, MessageOverlayStage
from .positioning import (
PositioningMode,
PositionStage,
create_position_stage,
)
from .transform import (
CanvasStage,
FontStage,
@@ -38,10 +43,13 @@ __all__ = [
"CanvasStage",
"MessageOverlayStage",
"MessageOverlayConfig",
"PositionStage",
"PositioningMode",
# Factory functions
"create_stage_from_display",
"create_stage_from_effect",
"create_stage_from_source",
"create_stage_from_camera",
"create_stage_from_font",
"create_position_stage",
]

18
engine/pipeline/adapters/display.py
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:

185
engine/pipeline/adapters/positioning.py Normal file
View File

@@ -0,0 +1,185 @@
"""PositionStage - Configurable positioning mode for terminal rendering.
This module provides positioning stages that allow choosing between
different ANSI positioning approaches:
- ABSOLUTE: Use cursor positioning codes (\\033[row;colH) for all lines
- RELATIVE: Use newlines for all lines
- MIXED: Base content uses newlines, effects use cursor positioning (default)
"""
from enum import Enum
from typing import Any
from engine.pipeline.core import DataType, PipelineContext, Stage
class PositioningMode(Enum):
"""Positioning mode for terminal rendering."""
ABSOLUTE = "absolute" # All lines have cursor positioning codes
RELATIVE = "relative" # Lines use newlines (no cursor codes)
MIXED = "mixed" # Mixed: newlines for base, cursor codes for overlays (default)
class PositionStage(Stage):
"""Applies positioning mode to buffer before display.
This stage allows configuring how lines are positioned in the terminal:
- ABSOLUTE: Each line has \\033[row;colH prefix (precise control)
- RELATIVE: Lines are joined with \\n (natural flow)
- MIXED: Leaves buffer as-is (effects add their own positioning)
"""
def __init__(
self, mode: PositioningMode = PositioningMode.RELATIVE, name: str = "position"
):
self.mode = mode
self.name = name
self.category = "position"
self._mode_str = mode.value
def save_state(self) -> dict[str, Any]:
"""Save positioning mode for restoration."""
return {"mode": self.mode.value}
def restore_state(self, state: dict[str, Any]) -> None:
"""Restore positioning mode from saved state."""
mode_value = state.get("mode", "relative")
self.mode = PositioningMode(mode_value)
@property
def capabilities(self) -> set[str]:
return {"position.output"}
@property
def dependencies(self) -> set[str]:
# Position stage typically runs after render but before effects
# Effects may add their own positioning codes
return {"render.output"}
@property
def inlet_types(self) -> set:
return {DataType.TEXT_BUFFER}
@property
def outlet_types(self) -> set:
return {DataType.TEXT_BUFFER}
def init(self, ctx: PipelineContext) -> bool:
"""Initialize the positioning stage."""
return True
def process(self, data: Any, ctx: PipelineContext) -> Any:
"""Apply positioning mode to the buffer.
Args:
data: List of strings (buffer lines)
ctx: Pipeline context
Returns:
Buffer with applied positioning mode
"""
if data is None:
return data
if not isinstance(data, list):
return data
if self.mode == PositioningMode.ABSOLUTE:
return self._to_absolute(data, ctx)
elif self.mode == PositioningMode.RELATIVE:
return self._to_relative(data, ctx)
else: # MIXED
return data # No transformation
def _to_absolute(self, data: list[str], ctx: PipelineContext) -> list[str]:
"""Convert buffer to absolute positioning (all lines have cursor codes).
This mode prefixes each line with \\033[row;colH to move cursor
to the exact position before writing the line.
Args:
data: List of buffer lines
ctx: Pipeline context (provides terminal dimensions)
Returns:
Buffer with cursor positioning codes for each line
"""
result = []
viewport_height = ctx.params.viewport_height if ctx.params else 24
for i, line in enumerate(data):
if i >= viewport_height:
break # Don't exceed viewport
# Check if line already has cursor positioning
if "\033[" in line and "H" in line:
# Already has cursor positioning - leave as-is
result.append(line)
else:
# Add cursor positioning for this line
# Row is 1-indexed
result.append(f"\033[{i + 1};1H{line}")
return result
def _to_relative(self, data: list[str], ctx: PipelineContext) -> list[str]:
"""Convert buffer to relative positioning (use newlines).
This mode removes explicit cursor positioning codes from lines
(except for effects that specifically add them).
Note: Effects like HUD add their own cursor positioning codes,
so we can't simply remove all of them. We rely on the terminal
display to join lines with newlines.
Args:
data: List of buffer lines
ctx: Pipeline context (unused)
Returns:
Buffer with minimal cursor positioning (only for overlays)
"""
# For relative mode, we leave the buffer as-is
# The terminal display handles joining with newlines
# Effects that need absolute positioning will add their own codes
# Filter out lines that would cause double-positioning
result = []
for i, line in enumerate(data):
# Check if this line looks like base content (no cursor code at start)
# vs an effect line (has cursor code at start)
if line.startswith("\033[") and "H" in line[:20]:
# This is an effect with positioning - keep it
result.append(line)
else:
# Base content - strip any inline cursor codes (rare)
# but keep color codes
result.append(line)
return result
def cleanup(self) -> None:
"""Clean up positioning stage."""
pass
# Convenience function to create positioning stage
def create_position_stage(
mode: str = "relative", name: str = "position"
) -> PositionStage:
"""Create a positioning stage with the specified mode.
Args:
mode: Positioning mode ("absolute", "relative", or "mixed")
name: Name for the stage
Returns:
PositionStage instance
"""
try:
positioning_mode = PositioningMode(mode)
except ValueError:
positioning_mode = PositioningMode.RELATIVE
return PositionStage(mode=positioning_mode, name=name)

2
engine/pipeline/params.py
View File

@@ -29,6 +29,7 @@ class PipelineParams:
# Display config
display: str = "terminal"
border: bool | BorderMode = False
positioning: str = "mixed" # Positioning mode: "absolute", "relative", "mixed"
# Camera config
camera_mode: str = "vertical"
@@ -84,6 +85,7 @@ class PipelineParams:
return {
"source": self.source,
"display": self.display,
"positioning": self.positioning,
"camera_mode": self.camera_mode,
"camera_speed": self.camera_speed,
"effect_order": self.effect_order,