Sky.Tui overview

Status: the Rust compiler (rust/, cargo build --release -p sky) is the primary Sky compiler; the Haskell compiler is preserved under legacy-haskell-compiler/. Verified by the example sweep + compiler test suite (cargo test + xtask gates). See ../history/compiler/journey.md for the changelog.

Terminal-rendering TEA backend. Sky.Tui runs an init / update / view / subscriptions app the same way Sky.Live runs a web app — but the view function paints to ANSI terminal cells instead of HTML. The same Std.Ui element tree renders in both backends, so a counter, a stopwatch, or a small dashboard ports between the browser and the terminal with no view rewrites.

You write it through Std.App. Don't import Std.Tui in app code — write one App.app (or App.tui) value and pick the terminal at build time with --target:

A Std.Ui Element view under App.app renders full-screen ANSI on terminal:tui — the exact same view function that renders HTML on --target web and a native window on --target desktop. Std.Tui / Std.Cli themselves are the low-level runtimes Std.App composes; you never call them directly.

module Main exposing (main)

import Sky.Core.Prelude exposing (..)
import Sky.Core.String as String
import Sky.Core.System as System
import Std.App as App
import Std.Cmd as Cmd
import Std.Sub as Sub
import Std.Ui as Ui exposing (Element)
import Std.Ui.Font as Font


type alias Model =
    { count : Int }


type alias KeyEvent =
    { kind : String, value : String }


type Msg
    = Increment
    | Decrement
    | Quit
    | NoOp


init : () -> ( Model, Cmd Msg )
init _ =
    ( { count = 0 }, Cmd.none )


update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        Increment -> ( { model | count = model.count + 1 }, Cmd.none )
        Decrement -> ( { model | count = model.count - 1 }, Cmd.none )
        Quit      -> ( model, Cmd.perform (System.exit 0) (\_ -> NoOp) )
        NoOp      -> ( model, Cmd.none )


view : Model -> Element Msg
view model =
    Ui.column [ Ui.padding 16, Ui.spacing 8 ]
        [ Ui.el [ Font.bold ] (Ui.text ("Count: " ++ String.fromInt model.count))
        , Ui.row [ Ui.spacing 8 ]
            [ Ui.button [] { onPress = Just Decrement, label = Ui.text "-" }
            , Ui.button [] { onPress = Just Increment, label = Ui.text "+" }
            ]
        ]


subscriptions : Model -> Sub Msg
subscriptions _ =
    Sub.none


onKey : KeyEvent -> Msg
onKey k =
    if k.kind == "char" && k.value == "q" then
        Quit

    else
        NoOp


appDef =
    App.app
        { init = init, update = update, view = view, subscriptions = subscriptions }
        |> App.withOnKey onKey
        -- The same App.app also builds for `--target web`, which needs a
        -- not-found page (a bare `sky check` / `sky build` checks that target).
        |> App.withNotFound ()


main =
    App.run appDef

Pin the terminal backend so a bare sky build / sky run picks it (an explicit --target still wins):

# sky.toml
[app]
target = "terminal:tui"

sky run src/Main.sky builds and launches the binary. The terminal switches to alt-screen, raw mode, and mouse tracking; teardown on exit (Ctrl-C, Quit, panic, SIGTERM) restores the user's primary screen. App.withOnKey onKey attaches the raw key-event handler (KeyEvent -> Msg) the terminal backend delivers — the runner maps it to the low-level Tui.withOnKey.

Runner-direct form. main = App.runTui appDef builds the TUI backend without a --target flag or sky.toml pin. App.run + --target terminal:tui is the portable default.

Status: stable

Sky.Tui shipped as part of v0.12 and has tracked Sky.Live in the 27-example regression sweep since. The surface follows the same backwards-compatibility discipline as Sky.Live — examples/21..24 exercise the full primitive set on every release.

What works

The runtime restores the terminal in every exit path: panic, signal (SIGTERM/HUP/QUIT/INT), System.exit, normal Quit Msg. mosh sessions don't end up with a corrupted readline.

The terminal loop contract

The terminal backends (terminal:tui Element and String views, terminal:cli) share one update core (runtime-go/rt/tea_loop.go), so these rules hold on all of them:

Logical-pixel canvas

Attach a logical-pixel canvas via a TerminalConfig passed to App.withConfig. The runtime computes pxPerCell from the live terminal size and scales every Ui.padding 8, Ui.spacing 4, Ui.px N to character cells. Default 1280×720 matches a typical web canvas — Std.Ui apps written for the browser look right in the terminal without re-tuning. Tweak canvasWidth for denser layout. (App.withConfig (App.TerminalConfig …) maps to the low-level Tui.withCanvasWidth / Tui.withCanvasHeight.)

appDef =
    App.app
        { init = init, update = update, view = view, subscriptions = subscriptions }
        |> App.withOnKey onKey
        |> App.withConfig
            (App.TerminalConfig { App.terminalDefaults | canvasWidth = 1024, canvasHeight = 768 })


main =
    App.run appDef

Auth guard middleware

The App.withGuard builder attaches a guard — Msg -> Model -> Result Error (). Returning Err reason skips the update and (if your model has notification / notificationType fields) writes the rejection into them for the view to render. The same guard function works under every backend (the runner maps it to Tui.withGuard on both terminal:tui views, Cli.withGuard on terminal:cli and Live.withGuard on the web), so authentication logic stays portable.

Sky.Cli — line-oriented TEA (--target terminal:cli)

For apps that DON'T want raw-mode and full-screen rendering, build with App.cli and --target terminal:cli: the view returns a String, App.withInput maps each stdin line to a Msg, and the runtime runs on a regular non-raw terminal. Useful for piped scripts and CI diagnostics.

appDef =
    App.cli
        { init = init, update = update, view = view, subscriptions = subscriptions }
        |> App.withInput onLine

# sky.toml
[app]
target = "terminal:cli"

Cli.readPassword : () -> Task Error Secret (a helper of the line-oriented runtime) reads a line from stdin with terminal echo disabled — wraps golang.org/x/term's ReadPassword. Falls back gracefully on non-TTY stdin.

Examples

Environment variables

Reliability floor

These are enforced runtime invariants — every panic / signal / malformed input path was audited before the experimental tag.

Prior-art attribution

The TEA shape (init / update / view / subscriptions) is adapted from elm-lang's Browser.element. bubbletea's renderer inspired the safeGo + alt-screen lifecycle. See NOTICE.md.

See also

• docs/skyapp/overview.md — Std.App + --target, the front door for every app shape (web / terminal / desktop).
• docs/skylive/overview.md — the web-side TEA backend that shares the same Std.Ui element tree.
• docs/skyui/overview.md — the layout DSL itself.
• examples/24-tui-kitchen-sink/src/Main.sky — every supported primitive in one screen.