Apparition.Mediation 0.2.1

Apparition UI Framework

An interactive terminal UI framework built around three layers and a small set of first-class concepts. Each concept has a single responsibility; together they compose into fully interactive terminal applications.

Getting started

Consuming applications must set the console output encoding to UTF-8 before running an Application — Apparition renders Unicode characters that display as garbled text on a Windows console left on its default code page, so this is needed for proper rendering:

Console.OutputEncoding = Encoding.UTF8;

See Sample/Program.cs for a runnable example.

Layers

Apparition.App

The host layer. Owns the terminal, navigates between Scenes, and manages the application lifecycle from launch to exit.

Apparition.Presentation

The view shell. Everything that touches the actual terminal — rendering, layout, console/keyboard I/O, and the orchestration that wires an interaction together (Plan, Scene). Presentation never contains domain-translation logic itself; it delegates that to Mediation.

Apparition.Mediation

The layer between Presentation and the domain model. It is split into two one-way halves, never one bidirectional object:

• Mediation.Projection (read) — maps domain state into something renderable. May hold its own state (e.g. history) to decide how to render, but never writes back to the domain.
• Mediation.Actuation (write) — decides what a keystroke means, including calling into the domain model, and reports the result as emitted values.

The domain model itself lives outside this project entirely — Apparition never references it. Consuming applications provide the concrete Projection/Actuation implementations that bridge the two (e.g. Stab.UI.Projectors, Stab.UI.Actuators).

Concepts

Widget (Presentation)

A live display component. A Widget shows the current state of something and automatically updates whenever that state changes. A Widget doesn't know how to turn that state into something visual — it delegates to an injected IProjector<T>. Widgets are purely about what the user sees.

Projector (Mediation.Projection)

An IProjector<T> implementation. A Projector maps a domain value into a renderable — the actual "how do I display this" knowledge that a Widget delegates to.

Input (Presentation)

An interactive element. An Input responds to user actions — such as navigating a list with the arrow keys — and produces a typed value. Like Widget, an Input doesn't interpret a keystroke itself — it delegates to an injected IActuator<T>. Inputs are purely about how the user acts.

Actuator (Mediation.Actuation)

An IActuator<T> implementation. An Actuator decides what a keystroke means and reports the outcome as zero or more emitted values, optionally followed by completion. This is where domain writes happen.

Layout element (Presentation)

A visual component (ILayoutElement). A layout element describes a piece of the screen — a stack, a grid, a frame, or a widget — and composes with other elements to define the scene's visual structure. Widgets are also layout elements and can be placed directly in a scene.

Plan (Presentation)

A single interaction session. A Plan wires an Input to its Widgets, keeps them in sync while the user interacts, and completes when the user makes a selection. It is what makes Input and Widget work together.

Scene (Presentation)

A screen. The unit of navigation — what the user moves to and from. A Scene arranges layout elements and executes a Plan. Its outcome can lead to another Scene, forming a navigable application. A Scene assumes full ownership of the console for its lifetime; the Application clears the console before each Scene runs.

Application (App)

The host. An Application owns the terminal, starts the first Scene, and manages the lifecycle from launch to exit. It is the entry point the user runs.

How they fit together

App
  └─ Application runs a Scene (or a chain of Scenes, routed by Application)
       └─ Scene (Presentation) arranges layout elements and executes a Plan
            └─ Plan (Presentation) wires an Input to one or more Widgets
                 ├─ Input (Presentation) responds to keystrokes
                 │    └─ IActuator (Mediation.Actuation) decides what the keystroke means,
                 │                                        may call into the domain model
                 └─ Widget (Presentation) is a layout element that observes a value and re-renders
                      └─ IProjector (Mediation.Projection) decides how to render the current value

Static content that does not change in response to user input is not a Widget — it is rendered directly as a plain renderable and placed as a layout element.