Frog

Frog is the core TUI framework of the Pondworks ecosystem. It provides the runtime loop, renderer, input decoding, validation, and layout/style primitives for terminal apps in Go.

Installation

go get github.com/pondworks-lib/frog@latest

Quick Start

package main

import (
	"fmt"

	"github.com/pondworks-lib/frog"
)

type helloModel struct {
	count int
}

func (m helloModel) Init() frog.Cmd { return nil }

func (m helloModel) Update(msg frog.Msg) (frog.Model, frog.Cmd) {
	switch msg := msg.(type) {
	case frog.KeyMsg:
		if msg.String == "q" {
			return m, frog.Quit()
		}
		m.count++
	}
	return m, nil
}

func (m helloModel) View() string {
	return fmt.Sprintf("Hello Frog!\n\nKeys pressed: %d\n\nPress 'q' to quit.", m.count)
}

func main() {
	if err := frog.Run(helloModel{}); err != nil {
		panic(err)
	}
}

Features

• MUV architecture: Model, Update, View.
• Standard messages: KeyMsg, TickMsg, QuitMsg, ResizeMsg, MouseMsg, PasteMsg.
• Commands: Cmd, Tick, Quit, Nil.
• Renderer: ANSI renderer with diff mode and safe full repaint fallback on wrapped frames.
• Input: raw mode, UTF-8 decoding, escape sequences, mouse, bracketed paste.
• Styling: ANSI16, ANSI256, TrueColor, chained Style.
• Layout: Center, PlaceBlock, Align*.
• Sessions: Run, RunContext, NewApp, NewAppWithContext.
• Runtime options: alt screen, mouse, bracketed paste, custom renderer, logger, non-interactive mode.
• Validation: InspectModel, ValidateModel, structured FROG... issue codes.
• Runtime errors: structured FROG2.. errors from the session loop.

Examples

Examples live in example/0.0.9. The set includes basics, input demos, rendering demos, app-style demos, and errors/ for validator testing.

Status

• Frog is in pre-release stage (v0.0.9).
• The goal of v0.0.9 is to make the current surface smaller, clearer, and much closer to the v0.1.0 freeze.

Toward v0.1.0

• Stabilize the core runtime, renderer, input, validation and layout/style helpers.
• Freeze the public API for frog at v0.1.0.
• Build higher-level packages on top of the frozen core:
  • lily: widgets such as list, table, text input, form, progress.
  • ripple: event bus / reactive orchestration on top of Frog.
  • future packages only after the base API has stopped moving.

Notes

pad and splash were merged into Frog starting in v0.0.3. For now, layout and styling remain in this repository until the base API is frozen.