klubhaus/sideline
2
0
Fork 0
forked from genewildish/Mainline
Code Issues 5 Pull Requests Projects 1 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

12
engine/app/pipeline_runner.py
View File

@@ -870,7 +870,17 @@ def run_pipeline_mode(preset_name: str = "demo"):
show_border = (
params.border if isinstance(params.border, bool) else False
)
display.show(result.data, border=show_border)
# Pass positioning mode if display supports it
positioning = getattr(params, "positioning", "mixed")
if (
hasattr(display, "show")
and "positioning" in display.show.__code__.co_varnames
):
display.show(
result.data, border=show_border, positioning=positioning
)
else:
display.show(result.data, border=show_border)
if hasattr(display, "is_quit_requested") and display.is_quit_requested():
if hasattr(display, "clear_quit_request"):

34
engine/display/backends/terminal.py
View File

@@ -83,7 +83,16 @@ class TerminalDisplay:
return self._cached_dimensions
def show(self, buffer: list[str], border: bool = False) -> None:
def show(
self, buffer: list[str], border: bool = False, positioning: str = "mixed"
) -> None:
"""Display buffer with optional border and positioning mode.
Args:
buffer: List of lines to display
border: Whether to apply border
positioning: Positioning mode - "mixed" (default), "absolute", or "relative"
"""
import sys
from engine.display import get_monitor, render_border
@@ -109,8 +118,27 @@ class TerminalDisplay:
if border and border != BorderMode.OFF:
buffer = render_border(buffer, self.width, self.height, fps, frame_time)
# Write buffer with cursor home + erase down to avoid flicker
output = "\033[H\033[J" + "\n".join(buffer)
# Apply positioning based on mode
if positioning == "absolute":
# All lines should have cursor positioning codes
# Join with newlines (cursor codes already in buffer)
output = "\033[H\033[J" + "\n".join(buffer)
elif positioning == "relative":
# Remove cursor positioning codes (except colors) and join with newlines
import re
cleaned_buffer = []
for line in buffer:
# Remove cursor positioning codes but keep color codes
# Pattern: \033[row;colH or \033[row;col;...H
cleaned = re.sub(r"\033\[[0-9;]*H", "", line)
cleaned_buffer.append(cleaned)
output = "\033[H\033[J" + "\n".join(cleaned_buffer)
else: # mixed (default)
# Current behavior: join with newlines
# Effects that need absolute positioning have their own cursor codes
output = "\033[H\033[J" + "\n".join(buffer)
sys.stdout.buffer.write(output.encode())
sys.stdout.flush()

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,