program

type Component interface {
	grid.Drawer
	input.Handler
}

type Config struct {
	// Root builds the component to run on a screen of its own. It is given the loop
	// first, so the component can hold it from the moment it exists.
	Root func(Loop) Component

	// Inline builds the component to run as a block in the terminal's own screen,
	// with output that is finished printed above it. Its component is given an
	// [InlineLoop], which is a [Loop] that can also print.
	Inline func(InlineLoop) Component

	// Terminal says which of the terminal's optional behaviours to ask for. Ignored
	// when Host is set.
	//
	// AltScreen is the program's to decide rather than the caller's, because where
	// frames go is the rendering model and not an input capability: it follows from
	// which of Root and Inline was set. Asking for it alongside Inline is a
	// contradiction and is reported as one.
	Terminal term.Options

	// Color says how much colour the terminal can show. The zero value, [grid.Auto],
	// asks [term.DetectDepth] — which is the one thing in this library that reads
	// its environment rather than making a request and letting it be ignored,
	// because a truecolor sequence a terminal cannot read prints wrong rather than
	// degrading.
	//
	// Setting it is how a program that already knows — from its own configuration,
	// or because it is writing to something that is not a terminal at all — takes
	// that decision back.
	Color grid.Depth

	// Host overrides where input comes from and frames go. Nil opens the real terminal
	// and gives it back on the way out.
	Host Host

	// FrameRate caps how often the interface redraws. Zero uses [DefaultFrameRate].
	FrameRate time.Duration
}

type Host interface {
	// Events is the input, closed when the input ends.
	Events() <-chan input.Event
	// Writer is where frames go.
	Writer() *term.Writer
	// Size is the terminal's size in cells.
	Size() (w, h int, err error)
}

type InlineLoop interface {
	Loop

	// Print draws something that can size itself into the terminal's own output,
	// above the interface, where it stays after the program exits.
	//
	// It is how a streaming interface says something final: the interface itself is
	// what is still changing, and everything it has finished with belongs to the
	// terminal.
	//
	// The width is the program's to know and not the caller's. Measuring happens
	// here, on the goroutine that owns the interface, which is both why a caller
	// does not have to remember how wide the last frame was and why measuring a
	// widget from somewhere else — a mutable object, on another goroutine — is not
	// something this can be made to do by accident.
	Print(p Printable)

	// PrintRows is the same for a caller that has already worked out the height:
	// rows it composed by hand, or content whose shape it knows better than any
	// measurement would. draw is given a view rows tall and as wide as the
	// interface.
	PrintRows(rows int, draw func(grid.View))
}

type Loop interface {
	// Refresh asks for a frame.
	Refresh()

	// Post runs fn on the program's goroutine and asks for a frame afterwards.
	//
	// This is the only safe way to change what a component holds from anywhere else.
	// Work posted after the program has stopped is dropped rather than run: there is
	// nothing left to show it, and blocking the caller for ever would be worse.
	Post(fn func())

	// Every calls fn on the program's goroutine at an interval until the returned
	// function is called, or until the program stops.
	//
	// It is how anything animated advances. Nothing ticks unless something asked for
	// it, which is what lets an idle interface be silent.
	Every(d time.Duration, fn func()) (stop func())

	// Quit asks the program to stop. The program returns from Run once the frame in
	// hand has been dealt with.
	Quit()
}

type Printable interface {
	grid.Drawer
	layout.Measurer
}