tui-development

name	tui-development
description	Use for the robotics showcase Textual UI: report panes, launch helpers, screenshots, visual tests, and changes under `src/worldforge/harness/tui.py` or robotics view/rendering modules. Preserves the optional Textual boundary while keeping robotics flow logic testable without the TUI.

TUI Development

Architecture Boundary

• src/worldforge/harness/robotics_launch.py: launcher and host-owned viewer helpers.
• src/worldforge/harness/robotics_view.py: Textual-free robotics report model and constants.
• src/worldforge/harness/robotics_tui_rendering.py: pure Rich renderable builders for panes.
• src/worldforge/harness/tui.py: robotics-showcase-only Textual import surface.
• src/worldforge/harness/tui_styles.py and tui_robotics_styles.py: Textual CSS constants.

Never import Textual from worldforge.__init__, worldforge.cli, or non-TUI harness modules.

Robotics TUI Engineering Contract

• Treat the robotics showcase as a testable report renderer first and a Textual screen second.
• Keep robotics summaries and screen state JSON-native so evidence can move between CLI, tests, screenshots, and docs.
• Keep long-running optional runtime work behind explicit commands; UI state should report progress and failure without hiding the underlying exception context.
• The removed world-creation/provider/eval/benchmark harness screens must not come back through this skill. Use CLI/docs surfaces for those workflows.

Workflow

1. Read robotics_view.py, robotics_tui_rendering.py, robotics_launch.py, and tui.py before touching TUI modules.
2. Keep all Textual imports inside harness/tui.py.
3. Keep report rendering pure and deterministic outside Textual so tests can run without the harness extra.
4. Update the relevant tests: test_robotics_tui_rendering.py, test_robotics_showcase.py, test_robotics_showcase_scripts.py, or focused harness report tests.
5. Update screenshots only when UI behavior or documented visual state changed.
6. Validate with focused robotics tests, optional-import boundary checks, and the --extra harness coverage gate when behavior changes.

Definition Of Done

• Robotics report rendering works without the harness extra.
• Changed robotics UI behavior is covered at the pure-rendering level before TUI-specific tests.
• Textual imports remain isolated and optional-import boundary checks pass when imports moved.
• Snapshot or screenshot updates are intentional and tied to verified behavior.

Spec Map

Current robotics showcase spec triads live under:

• specs/roboto-showcase/

Update the relevant spec.md, plan.md, or tasks.md before implementing a new milestone.

Sharp Edges

Symptom	Cause	Fix
Base import fails without Textual	Optional import leaked	Move Textual import under harness/tui.py or guarded launch path
Robotics report import fails	Rendering coupled to Textual	Move pure report logic back into robotics_view.py or robotics_tui_rendering.py
Snapshot drift	UI text or command surface changed	Update snapshot only after verifying behavior