UI#

bgscan’s terminal UI is built on BubbleTea (the Elvish v2 fork at charm.land/bubbletea/v2) and Lipgloss for styling. The architecture is a component tree with an overlay dialog system and a centralized layout manager.

Package map#

Component interface#

Every screen, widget, and dialog implements ui.shared.ui.Component:

type Component interface {
    ID() ComponentID
    Name() string
    Init() tea.Cmd
    Update(tea.Msg) (Component, tea.Cmd)
    View() string
    OnClose() tea.Cmd
    Mode() env.Mode
}

• ID — UUID generated by NewComponentID(). Used to match open/close messages.
• Name — human-readable label shown in the footer status bar.
• Init — called once when mounted. Return a tea.Cmd for async setup.
• Update — message router. Returns the updated component and any commands.
• View — renders the component as a string.
• OnClose — cleanup when removed from the stack.
• Mode — determines which keys act as back/quit (see Input modes).

Root model (app)#

ui/main/app is the top-level BubbleTea model. It manages three application stages and the shared app state:

type model struct {
    state     *ui.AppState
    splash    ui.Component
    startup   ui.Component
    workspace ui.Component
    stage     AppStage
}

func New(cfg *config.ScannerConfig, store *config.Store) tea.Model

The app progresses through three stages:

AppState threads shared dependencies through the whole tree:

type AppState struct {
    Layout *layout.Layout
    Config *config.ScannerConfig
    Store  *config.Store
}

Components read settings from state.Config and persist edits with state.Store. There is no config singleton to reach for.

Message routing#

The app routes messages differently depending on the current stage:

1. Splash stage — the splash animation runs until complete, then transitions to startup.
2. Startup stage — health check messages flow from the goroutine via logCh channel. Critical errors abort subsequent checks. Pressing Enter transitions to workspace.
3. Workspace stage — the workspace handles all UI messages:
   • tea.WindowSizeMsg — recalculates layout.Update(width, height).
   • tea.KeyPressMsg — ctrl+c quits immediately; ctrl+t dumps goroutines.
   • Overlay intercept — if dialogs exist, the top dialog consumes all key input. Back/quit keys close it.
   • dialog.OpenDialogMsg — pushes a new overlay onto the stack with placement metadata.
   • ui.CloseComponentMsg — removes the matching overlay by ID and runs its OnClose.
   • Base dispatch — if no overlay blocks, the message fans out to header, body, and footer.

Rendering#

During the workspace stage, the rendering is:

┌─────────────────────────────────┐
│           header                │
├─────────────────────────────────┤
│                                 │
│           body                  │  ← component stack (menu → screen)
│                                 │
├─────────────────────────────────┤
│           footer                │  ← version · status · goroutines · mem
└─────────────────────────────────┘
   + overlay dialogs (centered/positioned)

Overlays are rendered on top via bubbletea-overlay. Minimum terminal size is 75×35; below that a “terminal too small” message is shown.

Splash screen#

ui/main/splash displays an animated ASCII art logo of “BGSCAN” with glitch effects:

• 80 animation frames at 30ms tick, then 150 hold frames
• Glitch characters (▓▒░╬╪┼╫┃━╳▄▀) replace logo characters with decreasing probability
• Horizontal sweep accent color highlight at 72% progress
• Horizontal shake and artifact rows during animation
• Version display with fade-in after animation completes

Startup checks#

ui/main/startup runs seven sequential health checks in a goroutine, reporting status through a sidebar with dots (pending/running/success/warn/error), a progress bar, and a scrollable viewport:

Critical errors abort subsequent checks. The user can scroll with j/k and press Enter to continue when done.

Body — component stack#

ui/main/body holds a stack of components. The top of the stack is the active screen. The body is part of the workspace stage and is not active during splash or startup.

components[0] = mainMenu (entry)   ← always present
components[1] = scan source picker ← pushed on top
components[2] = scan type picker    ← pushed on top
components[3] = scanner view        ← pushed on top

Navigation messages:

Only the top component receives Update. When it’s popped, the next one down becomes active. The footer status bar updates to show the new top component’s Name().

Overlay dialog system#

ui/shared/dialog provides popup dialogs rendered on top of the base layout.

type OpenDialogMsg struct {
    Component ui.Component
    XPos      DialogPosition   // Top, Right, Bottom, Left, Center
    YPos      DialogPosition
    XOffset   int
    YOffset   int
}

Dialogs use the rmhubbert/bubbletea-overlay library to position themselves. Most dialogs center on screen; file pickers and confirm dialogs may use different positions.

The dialog stack in app.model supports multiple nested overlays — the topmost consumes all input.

Input modes#

ui/shared/env/type.go defines three modes that control how keyboard input is interpreted:

IsBackKey(msg, mode) and IsQuitKey(msg, mode) in env/keys.go check the mode-specific key sets. This prevents quit/back from firing while the user is typing in an input field.

Layout#

ui/shared/layout/layout.go is a stateful geometry calculator. It precomputes the position and size of each region (header, body, footer) whenever the terminal is resized:

type Layout struct {
    Terminal TerminalSize   // raw terminal dimensions
    Content  ContentSize    // drawable area (after margins/padding)
    Header   ComponentSize
    Body     ComponentSize
    Footer   ComponentSize
}

Layout.Update(width, height) is called on every tea.WindowSizeMsg. All components receive a reference to the shared *Layout so they can query their region without recomputing.

Reusable widgets (basic)#

ui/components/basic/ contains the building-block widgets used across screens:

Each widget follows the standard Component interface and is designed to be composed into larger screens.

Settings inspectors and forms#

Settings inspectors (ui/components/inspector/)#

Each inspector reads its section from state.Config, renders editable fields, and on save calls the matching state.Store.SaveXxx() method. Fields can be dynamic — for example, TLS options only appear when HTTPS is selected, and tunnel-specific fields only show when the corresponding protocol is enabled.

Every field validates before it commits. The inspector applies the edit to a copy of the section, runs validate.ValidateXxx on it, and rejects the input if that field reports an error, so an invalid value never reaches the config or the disk.

The generic basic/inspector widget handles the field rendering, formatting, and type adaptation; the per-protocol packages just define which fields to show and how to map them to the config struct.

DNS tunnel config forms (ui/components/form/)#

Each form creates a protocol-specific inspector with fields for connection settings, advanced options (VayDNS only), and proxy/authentication. Forms support both creating new configs and editing existing ones. On save, they call the matching service’s SaveConfig or EditConfig method.

Menus and tables#

Menus (ui/components/menus)#

Tables (ui/components/tables)#

Tables use the basic/table widget and a Provider interface that supplies rows and handles column sorting. resultlist renders its columns from the schema attached to each result.ResultFile, so a new probe’s results display without touching the table code. dnstun is a CRUD table that manages DNS tunnel configurations across all three protocols.

Scanner view#

ui/components/scanner is the live scan dashboard. It wires the Scanner to the UI:

• One tab per scan stage (via basic/tabs).
• Each tab shows a progress bar (basic/progress) and a live result table (tables/ipviewer).
• Stage status is tracked per-stage: Waiting → PreProcess → Scanning → Ended / Error.
• Progress updates flow via engine.ScanHooks.OnProgress → Progress message → scanner component Update.
• Successful results are buffered in per-stage batches and rendered in the ipviewer table.

Controls during a scan: pause/resume, stop, switch tabs to view different stages.

Theming#

ui/theme/theme.go provides a centralized color palette:

type Theme struct {
    Primary       color.Color
    Secondary     color.Color
    Border        color.Color
    BorderActive  color.Color
    Text          color.Color
    Muted         color.Color
    Timestamp     color.Color
    Info          color.Color
    Error         color.Color
    Success       color.Color
    Orange        color.Color
    Yellow        color.Color
    Purple        color.Color
    ProgressStart color.Color
    ProgressEnd   color.Color
}

Modes#

theme.Init() is called from main() before the TUI starts. Components retrieve the active palette via theme.Current() — never hardcode colors.

Huh integration#

ui/theme/huh.go builds a huh.Theme from the centralized palette so that form fields (select, confirm, text input) rendered by the huh library match the rest of the UI instead of huh’s defaults. This is used by the input and inspector widgets.

Debugging#

Goroutine dump#

Pressing Ctrl+T at any time triggers dumpGoroutines() in app/update.go:

• Logs the total goroutine count.
• Writes the full runtime/pprof goroutine profile to the debug log.
• Filters and logs lines containing [chan receive], [chan send], [select], [IO wait], [sleep] — useful for spotting stuck workers or probe leaks.

Runtime stats#

The footer component polls Go runtime metrics every second:

• runtime.NumGoroutine() — goroutine count
• runtime.ReadMemStats() — heap alloc and sys memory

These display in the status bar and are useful for monitoring scan resource usage in real time.

Related pages#

• Architecture — high-level project layout
• Core — scanner engine and probe interface